Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Note:
If you specify a locale with the LCID (Locale ID) parameter and that locale is not installed or available on the Windows ®phone, the function fails with ERROR_INVALID_PARAMETER. To determine whether the locale is supported or not, call IsValidLocale.

Syntax 

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

Parameters

Locale

[in] Value that specifies the locale for which the time string is to be formatted. If lpFormatis NULL, the function formats the string according to the time format for this locale. If lpFormatis 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 MAKELCIDmacro, or one of the following predefined values. The following table shows the values this parameter can take.

Value Description

LOCALE_SYSTEM_DEFAULT

Default system locale.

LOCALE_USER_DEFAULT

Default user locale.

LOCALE_NEUTRAL

Default language–neutral locale.

For Windows CE 1.0, Localeis ignored.

dwFlags

[in] Value that specifies various function options. You can specify a combination of the following flags. The following table shows the values this parameter can take.

Value Description

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.

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 lpFormatis non-NULL.
lpTime

[in] Pointer to a SYSTEMTIMEstructure that contains the time information to be formatted. If this pointer is NULL, the function uses the current local system time.

lpFormat

[in] Pointer to a format picture to use to form the time string. If lpFormatis 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. The following table shows the values that can be used to construct a format picture string.

Value Description

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

[out] Pointer to a buffer that receives the formatted time string.

cchTime

[in] Size, in characters, of the lpTimeStrbuffer. If cchTimeis zero, the function returns the number of characters required to hold the formatted time string, and the buffer pointed to by lpTimeStris not used.

Return Value

The number of characters written to the buffer pointed to by lpTimeStrindicates success. If the cchTimeparameter is zero, the number of characters required to hold the formatted time string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call the GetLastErrorfunction. The following table shows possible return values for GetLastError.

Value Description

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

ERROR_INVALID_FLAGS

The flags are invalid.

ERROR_INVALID_PARAMETER

The parameter is incorrect, or the specified LCID is not supported on the device.

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 SYSTEMTIMEstructure pointed to by lpTimemust be valid. The function checks each time values to determine if 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 SYSTEMTIMEstructure 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, lpFormatmust 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 valid time marker pictures are L"t" and L"tt" .The 'L' indicates a string consisting of Unicode 16-bit characters. If L"ttt" is passed in, the function assumes L"tt".

For more information about locales and LCID, see National Language support (NLS) Locale Identifiers.

Requirements

Header winnls.h
Library Coreloc.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also