getDateFormatW 函数 (datetimeapi.h)

将日期的格式设置为区域设置标识符指定的区域设置的日期字符串。 函数设置指定日期或本地系统日期的格式。

注意 出于互操作性原因,应用程序应优先使用 GetDateFormatEx 函数而不是 GetDateFormat ,因为 Microsoft 正在迁移到使用区域设置名称而不是新区域设置的区域设置标识符。 将仅在 Windows Vista 及更高版本上运行的任何应用程序都应使用 GetDateFormatEx

 

语法

int GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

参数

[in] Locale

指定 此函数为其设置日期字符串格式的区域设置的区域设置标识符。 可以使用 MAKELCID 宏创建区域设置标识符或使用以下预定义值之一。

[in] dwFlags

指定日期格式选项的标志。 有关详细定义,请参阅 GetDateFormatExdwFlags 参数。

[in, optional] lpDate

指向 SYSTEMTIME 结构的指针,该结构包含要设置格式的日期信息。 如果函数要使用当前本地系统日期,则应用程序将此参数设置为 NULL

[in, optional] lpFormat

指向用于构成日期的格式图片字符串的指针。 格式图片字符串的可能值在 “天”、“月”、“年”和“纪元格式图片”中定义。

函数仅对格式图片字符串中未指定的信息使用指定的区域设置,例如区域设置的日期和月份名称。 应用程序可以将此参数设置为 NULL ,以便根据指定区域设置的日期格式设置字符串的格式。

[out, optional] lpDateStr

指向缓冲区的指针,此函数在其中检索格式化日期字符串。

[in] cchDate

lpDateStr 缓冲区的大小(以字符为单位)。 应用程序可以将此参数设置为 0,以返回保存格式化日期字符串所需的缓冲区大小。 在这种情况下,不使用 lpDateStr 指示的缓冲区。

返回值

如果成功,则返回写入 lpDateStr 缓冲区的字符数。 如果 cchDate 参数设置为 0,则该函数将返回保存格式化日期字符串所需的字符数,包括终止 null 字符。

如果函数不成功,则返回 0。 若要获取扩展的错误信息,应用程序可以调用 GetLastError,这会返回以下错误代码之一:

  • ERROR_INSUFFICIENT_BUFFER。 提供的缓冲区大小不够大,或者错误地设置为 NULL
  • ERROR_INVALID_FLAGS。 为标志提供的值无效。
  • ERROR_INVALID_PARAMETER。 任何参数值都无效。

备注

注意 此 API 正在更新,以支持 2019 年 5 月日本纪元更改。 如果应用程序支持日语日历,则应验证它是否正确处理了新纪元。 有关详细信息 ,请参阅为日本纪元更改准备应用程序
 
请参阅 GetDateFormatEx 的备注。

当此函数的 ANSI 版本与仅限 Unicode 的区域设置标识符一起使用时,该函数可以成功,因为操作系统使用系统代码页。 但是,系统代码页中未定义的字符在字符串中显示为问号 (“?”) 。

从 Windows 8 开始: GetDateFormat 在 Datetimeapi.h 中声明。 在 Windows 8 之前,它在 Winnls.h 中声明。

注意

datetimeapi.h 标头将 GetDateFormat 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 datetimeapi.h
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

日、月、年和纪元格式图片

EnumCalendarInfo

EnumDateFormatsEx

GetCalendarInfo

GetDateFormatEx

GetLocaleInfo

GetTimeFormat

国家/地区语言支持

国家/地区语言支持函数