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
);
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. |
| LOCALE_NEUTRAL | Default language-neutral locale. |
| 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. |
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"
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. The count includes the terminating null.
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
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".
Windows CE: The Locale parameter is ignored and the default system locale is always used. The Locale parameter should be set to LOCALE_SYSTEM_DEFAULT to ensure compatibility with future versions of Windows CE.
Windows CE does not support the LOCALE_NOUSEOVERRIDE flag for the dwFlags parameter.
Windows NT: Requires version 3.5 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in winnls.h.
Import Library: Use kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
National Language Support Overview, National Language Support Functions, GetDateFormat, SYSTEMTIME