GetTimeFormat
The GetTimeFormat
function formats a time as a time string for a specified locale. The function
formats either a specified time or the local system time.
int GetTimeFormat(
|
LCID Locale, |
// locale for which
time is to be formatted |
|
DWORD dwFlags, |
// flags specifying
function options |
|
CONST SYSTEMTIME *lpTime, |
// time to be
formatted |
|
LPCTSTR lpFormat, |
// time format
string |
|
LPTSTR lpTimeStr, |
// buffer for
storing formatted string |
|
int cchTime |
// size, in bytes
or characters, of the buffer |
|
); |
|
Parameters
Locale
Specifies the
locale for which the time string is to be formatted. If lpFormat is
NULL, the function formats the string according to the time format for this
locale. If lpFormat is not NULL, the function uses the locale only for
information not specified in the format picture string (for example, the
locale s time markers).
This parameter
can be a locale identifier created by the MAKELCID macro, or one of the
following predefined values:
|
LOCALE_SYSTEM_DEFAULT |
Default
system locale. |
|
LOCALE_USER_DEFAULT |
Default
user locale. |
dwFlags
A set of bit
flags that specify various function options. You can specify a combination of
the following flags:
|
Flag |
Meaning |
|
LOCALE_NOUSEROVERRIDE |
If set, the
function formats the string using the system default time format for the
specified locale. If not set, the function formats the string using any user
overrides to the locale s default time format. This flag cannot be set if lpFormat
is non-NULL. |
|
TIME_NOMINUTESORSECONDS |
Do not use
minutes or seconds. |
|
TIME_NOSECONDS |
Do not use
seconds. |
|
TIME_NOTIMEMARKER |
Do not use
a time marker. |
|
TIME_FORCE24HOURFORMAT |
Always use
a 24-hour time format. |
lpTime
Pointer to a SYSTEMTIME structure that contains the
time information to be formatted. If this pointer is NULL, the function uses
the current local system time.
lpFormat
Pointer to a
format picture to use to form the time string. If lpFormat is NULL, the
function uses the time format of the specified locale.
Use the
following elements to construct a format picture string. If you use spaces to
separate the elements in the format string, these spaces will appear in the
same location in the output string. The letters must be in uppercase or
lowercase as shown (for example, ss , not SS ). Characters in the format
string that are enclosed in single quotation marks will appear in the same
location and unchanged in the output string.
|
Picture |
Meaning |
|
h |
Hours with
no leading zero for single-digit hours; 12-hour clock |
|
hh |
Hours with
leading zero for single-digit hours; 12-hour clock |
|
H |
Hours with
no leading zero for single-digit hours; 24-hour clock |
|
HH |
Hours with
leading zero for single-digit hours; 24-hour clock |
|
m |
Minutes
with no leading zero for single-digit minutes |
|
mm |
Minutes
with leading zero for single-digit minutes |
|
s |
Seconds
with no leading zero for single-digit seconds |
|
ss |
Seconds
with leading zero for single-digit seconds |
|
t |
One
character time marker string, such as A or P |
|
tt |
Multicharacter
time marker string, such as AM or PM |
For example,
to get the time string
11:29:40 PM
use the
following picture string:
hh':'mm':'ss
tt
lpTimeStr
Pointer to a
buffer that receives the formatted time string.
cchTime
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the lpTimeStr
buffer. If cchTime is zero, the function returns the number of bytes or
characters required to hold the formatted time string, and the buffer pointed
to by lpTimeStr is not used.
Return Values
If the
function succeeds, the return value is the number of bytes (ANSI version) or
characters (Unicode version) written to the buffer pointed to by lpTimeStr.
If the cchTime parameter is zero, the return value is the number of
bytes or characters required to hold the formatted time string.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
GetLastError may return one of the following error codes:
|
ERROR_INSUFFICIENT_BUFFER |
|
ERROR_INVALID_FLAGS |
|
ERROR_INVALID_PARAMETER |
Remarks
If a time
marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes
the time marker based on the specified locale identifier. Examples of time
markers are AM and PM for US English.
The time
values in the SYSTEMTIME
structure pointed to by lpTime must be valid. The function checks each
of the time values to determine that it is within the appropriate range of
values. If any of the time values are outside the correct range, the function
fails, and sets the last-error to ERROR_INVALID_PARAMETER.
The function
ignores the date portions of the SYSTEMTIME structure pointed to by lpTime:
wYear, wMonth, wDayOfWeek, and wDay.
If
TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes
the separator(s) preceding the minutes and/or seconds element(s).
If
TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding
and following the time marker.
If
TIME_FORCE24HOURFORMAT is specified, the function displays any existing time
marker, unless the TIME_NOTIMEMARKER flag is also set.
The function
does not include milliseconds as part of the formatted time string.
To use the
LOCALE_NOUSEROVERRIDE flag, lpFormat must be NULL.
No errors are
returned for a bad format string. The function simply forms the best time
string that it can. If more than two hour, minute, second, or time marker
format pictures are passed in, then the function defaults to two. For example,
the only time marker pictures that are valid are L t and L tt (the L
indicates a Unicode (16-bit characters) string). If L ttt is passed in, the
function assumes L tt .
See Also