Export (0) Print
Expand All
1 out of 6 rated this helpful - Rate this topic

GetDateFormat (Windows CE 5.0)

Windows CE 5.0
Send Feedback

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

int GetDateFormat(
  LCID Locale, 
  DWORD dwFlags, 
  CONST SYSTEMTIME* lpDate, 
  LPCTSTR lpFormat, 
  LPTSTR lpDateStr, 
  int cchDate 
); 

Parameters

Locale
[in] Value that specifies the locale for which the date string is to be formatted. If lpFormat is NULL, the function formats the string according to the date format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's day and month names).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values. The following table shows the values this parameter can take.

ValueDescription
LOCALE_SYSTEM_DEFAULTDefault system locale.
LOCALE_USER_DEFAULTDefault user locale.
LOCALE_NEUTRALDefault language-neutral locale.

For Microsoft® Windows® CE 1.0, Locale is ignored.

dwFlags
[in] Value that specifies various function options. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify a combination of the following flags. The following table shows the values this parameter can take.

ValueDescription
DATE_SHORTDATEUse the short date format. This is the default. Cannot be used with DATE_LONGDATE or DATE_YEARMONTH.
DATE_LONGDATEUse the long date format. Cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.
DATE_LTRREADINGAdds marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING.
DATE_RTLREADINGAdds marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING.
LOCALE_NOUSEROVERRIDEIf set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default–date format.
LOCALE_USE_CP_ACPNot supported
DATE_YEARMONTHNot supported.
DATE_USE_ALT_CALENDARUses the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for the specified alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.
lpDate
[in] Pointer to a SYSTEMTIME structure that contains the date information to be formatted. If this pointer is NULL, the function uses the current local system date.
lpFormat
[in] Pointer to a format picture string to use to form the date string. If lpFormat is NULL, the function uses the date 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 in the table (for example, "MM" not "mm"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

ValueDescription
DDay of month as digits with no leading zero for single-digit days.
DdDay of month as digits with leading zero for single-digit days.
DddDay of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
DdddDay of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
MMonth as digits with no leading zero for single-digit months.
MMMonth as digits with leading zero for single-digit months.
MMMMonth as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMMMonth as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
yYear as last two digits, with a leading zero for years less than 10. The same format as "yy."
yyYear as last two digits, with a leading zero for years less than 10.
yyyyYear represented by full four digits.
ggPeriod/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the date string

"Wed, Aug 31 94"

use the following picture string:

"ddd',' MMM dd yy"

lpDateStr
[out] Pointer to a buffer that receives the formatted date string.
cchDate
[in] Size, in characters, of the lpDateStr buffer. If cchDate is zero, the function returns the number of characters required to hold the formatted date string, and the buffer pointed to by lpDateStr is not used.

Return Values

The number of characters written to the lpDateStr buffer, or, if the cchDate parameter is zero, the number of characters required to hold the formatted date string indicates success. The count includes the terminating null. Zero indicates failure. To get extended error information, call the GetLastError function. The following table shows possible return values for the GetLastError function.

ValueDescription
ERROR_INSUFFICIENT_BUFFERThe data area passed to a system call is too small.
ERROR_INVALID_FLAGSThe flags are invalid.
ERROR_INVALID_PARAMETERThe parameter is incorrect.

Remarks

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the given locale identifier.

The Locale parameter is ignored and the system locale is always used. The Locale parameter should be set to LOCALE_SYSTEM_DEFAULT to ensure compatibility with future versions of Microsoft Windows CE.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the following date values: year, month, and day. If the day of the week that is specified in the wDayofWeek member of SYSTEMTIME is incorrect, the function uses the correct value and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER. If you try to get a one digit year by using GetDateFormat(LOCALE_USER_DEFAULT,0,NULL,TEXT("y"),
ach,50), the function returns a two-digit year.

The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

The DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If neither one is specified nor lpFormat is NULL, then DATE_SHORTDATE is the default.

For Windows CE 2.10 and later, default DATE_SHORTDATE formats for non-U.S. English locales that include the four-digit year are added. The following table shows the formats.

LocaleDate Format
United Kingdomdd/MM/yyyy
Canadadd/MM/yyyy
New Zealanddd/MM/yyyy
Irelanddd/MM/yyyy
South Africadd/MM/yyyy
CaribbeanMM/dd/yyyy
Belizedd/MM/yyyy
Trinidaddd/MM/yyyy

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L"yyyy" and L"yy" (the 'L' indicates a Unicode (16-bit characters) string). If L"y" is passed in, the function assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than 4 date (L"dddd") or 4 month (L"MMMM") pictures are passed in, then the function defaults to L"dddd" or L"MMMM".

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be: L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Winnls.h.
Link Library: Coreloc.lib.

See Also

GetTimeFormat | SYSTEMTIME | MAKELCID


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.