GetTimeFormatEx function (datetimeapi.h)

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

Syntax

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

Parameters

[in, optional] lpLocaleName

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

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFlags

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

[in, optional] lpTime

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.

[in, optional] lpFormat

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.

[out, optional] lpTimeStr

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

[in] cchTime

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 following 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.

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.

Requirements

See also

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

National Language Support

National Language Support Functions