GetDateFormatWrapW function

Article
01/07/2021

[GetDateFormatWrapW is available for use in Windows XP. It will not be available in subsequent versions. You should use GetDateFormatW in its place.]

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

Note

GetDateFormatWrapW is a wrapper for the GetDateFormatW function. See the GetDateFormat page for further usage notes.

Syntax

int GetDateFormatWrapW(
  _In_        LCID       Locale,
  _In_        DWORD      dwFlags,
  _In_  const SYSTEMTIME *lpDate,
  _In_        LPCWSTR    pwzFormat,
  _Out_       LPWSTR     pwzDateStr,
  _In_        int        cchDate
);

Parameters

Locale [in]

Type: LCID

The locale for which the date string is to be formatted. If pwzFormat is NULL, the function formats the string according to the date format for this locale. If pwzFormat 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.

LOCALE_SYSTEM_DEFAULT

Default system locale.

LOCALE_USER_DEFAULT

Default user locale.

dwFlags [in]

Type: DWORD

Specifies various function options. If pwzFormat is not NULL, this parameter must be zero. If pwzFormat is NULL, you can specify a combination of the following values. If you do not specify either DATE_YEARMONTH, DATE_SHORTDATE, or DATE_LONGDATE, and pwzFormat is NULL, then DATE_SHORTDATE is used as the default.

LOCALE_NOUSEROVERRIDE

If 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_ACP

Uses the system ANSI code page for string translation instead of the locale's code page.

DATE_SHORTDATE

Uses the short date format. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.

DATE_LONGDATE

Uses the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.

DATE_YEARMONTH

Uses the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE.

DATE_USE_ALT_CALENDAR

Uses the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that 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.

DATE_LTRREADING

Adds marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING.

DATE_RTLREADING

Adds marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING.

lpDate [in]

Type: const SYSTEMTIME*

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

pwzFormat [in]

Type: LPCWSTR

A pointer to a format picture to use to form the date string. If pwzFormat is NULL, the function uses the date format of the specified locale. See GetDateFormat for more details.

pwzDateStr [out]

Type: LPWSTR

A pointer to a buffer that receives the formatted date string.

cchDate [in]

Type: int

Specifies the size, in characters, of the pwzDateStr 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 pwzDateStr is not used.

Return value

Type: int

If the function succeeds, the return value is the number of characters written to the buffer pointed to by pwzDateStr. If the cchDate parameter is zero, the return value is the number of characters required to hold the formatted date string. The count includes the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes.

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

GetDateFormatWrapW provides the ability to use Unicode strings in operating systems earlier than Windows XP. The preferred method is to use GetDateFormatW in conjunction with the Microsoft Layer for Unicode (MSLU).

GetDateFormatWrapW must be called directly from Shlwapi.dll, using ordinal 311.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
DLL	Shlwapi.dll (version 5.0 or later)

Share via