Expand Minimize

GetTimeFormatEx function

Formats time as a time string for a locale specified by name. The function formats either a specified time or the local system time.

Note  The application should call this function in preference to GetTimeFormat if designed to run only on Windows Vista and later.

Note  This function can format data that changes between releases, for example, due to a custom locale. If your application must persist or transmit data, see Using Persistent Locale Data.

Syntax


int GetTimeFormatEx(
  _In_opt_   LPCWSTR lpLocaleName,
  _In_       DWORD dwFlags,
  _In_opt_   const SYSTEMTIME *lpTime,
  _In_opt_   LPCWSTR lpFormat,
  _Out_opt_  LPWSTR lpTimeStr,
  _In_       int cchTime
);

Parameters

lpLocaleName [in, optional]

Pointer to a locale name, or one of the following predefined values.

dwFlags [in]

Flags specifying time format options. The application can specify a combination of the following values and LOCALE_USE_CP_ACP or LOCALE_NOUSEROVERRIDE.

Caution  Use of LOCALE_NOUSEROVERRIDE is strongly discouraged as it disables user preferences.

ValueMeaning
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 [in, optional]

Pointer to a SYSTEMTIME structure that contains the time information to format. The application can set this parameter to NULL if the function is to use the current local system time.

lpFormat [in, optional]

Pointer to a format picture to use to format the time string. If the application sets this parameter to NULL, the function formats the string according to the time format of the specified locale. If the application does not set the parameter to NULL, the function uses the locale only for information not specified in the format picture string, for example, the locale-specific time markers. For information about the format picture string, see the Remarks section.

lpTimeStr [out, optional]

Pointer to a buffer in which this function retrieves the formatted time string.

cchTime [in]

Size, in characters, for the time string buffer indicated by lpTimeStr. Alternatively, the application can set this parameter to 0. In this case, the function returns the required size for the time string buffer, and does not use the lpTimeStr parameter.

Return value

Returns the number of characters retrieved in the buffer indicated by lpTimeStr. If the cchTime parameter is set to 0, the function returns the size of the buffer required to hold the formatted time string, including a terminating null character.

This function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
  • ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
  • ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
  • ERROR_OUTOFMEMORY. Not enough storage was available to complete this operation.

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 English (United States).

The time values in the structure indicated 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 members of the SYSTEMTIME structure. These include: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separators preceding the minutes and/or seconds members.

If TIME_NOTIMEMARKER is specified, the function removes the separators 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.

The function returns no errors for a bad format string, but just forms the best possible time string. If more than two hour, minute, second, or time marker format pictures are passed in, the function defaults to two. For example, the only time marker pictures that are valid are "t" and "tt". If "ttt" is passed in, the function assumes "tt".

To obtain the time format without performing any actual formatting, the application should use the GetLocaleInfoEx function, specifying LOCALE_STIMEFORMAT.

The application can use the following elements to construct a format picture string. If spaces are used to separate the elements in the format string, these spaces 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 appear in the same location and unchanged in the output string.

PictureMeaning
hHours with no leading zero for single-digit hours; 12-hour clock
hhHours with leading zero for single-digit hours; 12-hour clock
HHours with no leading zero for single-digit hours; 24-hour clock
HHHours with leading zero for single-digit hours; 24-hour clock
mMinutes with no leading zero for single-digit minutes
mmMinutes with leading zero for single-digit minutes
sSeconds with no leading zero for single-digit seconds
ssSeconds with leading zero for single-digit seconds
tOne character time marker string, such as A or P
ttMulti-character time marker string, such as AM or PM

 

For example, to get the time string

"11:29:40 PM"

the application should use the picture string

"hh':'mm':'ss tt"

This function can retrieve data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.

Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.

Beginning in Windows 8: GetTimeFormatEx is declared in Datetimeapi.h. Before Windows 8, it was declared in Winnls.h.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Datetimeapi.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
GetDateFormatEx
GetLocaleInfoEx
GetTimeFormat

 

 

Community Additions

ADD
Show:
© 2014 Microsoft