Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.
0 out of 3 rated this helpful - Rate this topic

GetTimeFormat function

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

Note  For interoperability reasons, the application should prefer the GetTimeFormatEx function to GetTimeFormat because Microsoft is migrating toward the use of locale names instead of locale identifiers for new locales. Any application that will be run only on Windows Vista and later should use GetTimeFormatEx.

Syntax


int GetTimeFormat(
  _In_       LCID Locale,
  _In_       DWORD dwFlags,
  _In_opt_   const SYSTEMTIME *lpTime,
  _In_opt_   LPCTSTR lpFormat,
  _Out_opt_  LPTSTR lpTimeStr,
  _In_       int cchTime
);

Parameters

Locale [in]

Locale identifier that specifies the locale. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values.

dwFlags [in]

Flags specifying time format options. For detailed definitions see the dwFlags parameter of GetTimeFormatEx.

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 TCHAR values, 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 TCHAR values 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

See Remarks for GetTimeFormatEx.

When the ANSI version of this function is used with a Unicode-only locale identifier, the function can succeed because the operating system uses the system code page. However, characters that are undefined in the system code page appear in the string as a question mark (?).

Starting with Windows 8: GetTimeFormat is declared in Datetimeapi.h. Before Windows 8, it was declared in Winnls.h.

Windows Phone 8: This API is supported.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Datetimeapi.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

GetTimeFormatW (Unicode) and GetTimeFormatA (ANSI)

See also

National Language Support
National Language Support Functions
GetDateFormat
GetLocaleInfo
GetTimeFormatEx

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft. All rights reserved.