getDateFormatEx 函数 (datetimeapi.h)
将日期格式设置为由 name 指定的区域设置的日期字符串。 函数设置指定日期或本地系统日期的格式。
语法
int GetDateFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpDate,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpDateStr,
[in] int cchDate,
[in, optional] LPCWSTR lpCalendar
);
参数
[in, optional] lpLocaleName
指向 区域设置名称或以下预定义值之一的指针。
[in] dwFlags
指定在 lpFormat 设置为 NULL 时可设置的各种函数选项的标志。 应用程序可以指定以下值和 LOCALE_USE_CP_ACP 或 LOCALE_NOUSEROVERRIDE的组合。
如果应用程序未指定DATE_YEARMONTH、DATE_MONTHDAY、DATE_SHORTDATE或DATE_LONGDATE，并且 lpFormat 设置为 NULL，则默认DATE_SHORTDATE。
[in, optional] lpDate
指向 SYSTEMTIME 结构的指针，该结构包含要设置格式的日期信息。 如果函数要使用当前本地系统日期，则应用程序可以将此参数设置为 NULL 。
[in, optional] lpFormat
指向用于构成日期的格式图片字符串的指针。 格式图片字符串的可能值在 “天”、“月”、“年”和“纪元格式图片”中定义。
例如，若要获取日期字符串“Wed， Aug 31 94”，应用程序使用图片字符串“ddd'，'MMM dd yy”。
函数仅对格式图片字符串中未指定的信息使用指定的区域设置，例如区域设置的日期和月份名称。 应用程序可以将此参数设置为 NULL ，以便根据指定区域设置的日期格式设置字符串的格式。
[out, optional] lpDateStr
指向缓冲区的指针，此函数在其中检索格式化日期字符串。
[in] cchDate
lpDateStr 缓冲区的大小（以字符为单位）。 应用程序可以将此参数设置为 0，以返回保存格式化日期字符串所需的缓冲区大小。 在这种情况下，不使用 lpDateStr 指示的缓冲区。
[in, optional] lpCalendar
保留;必须设置为 NULL。
返回值
如果成功，则返回写入 lpDateStr 缓冲区的字符数。 如果 cchDate 参数设置为 0，则该函数将返回保存格式化日期字符串所需的字符数，包括终止 null 字符。
如果未成功，则此函数返回 0。 若要获取扩展的错误信息，应用程序可以调用 GetLastError，这会返回以下错误代码之一：
- ERROR_INSUFFICIENT_BUFFER。 提供的缓冲区大小不够大，或者错误地设置为 NULL。
- ERROR_INVALID_FLAGS。 为标志提供的值无效。
- ERROR_INVALID_PARAMETER。 任何参数值都无效。
注解
日期名称、缩写日期名称、月份名称和缩写月份名称都基于区域设置标识符进行本地化。
lpDate 指示的结构中的日期值必须有效。 函数检查每个日期值：year、month、day 和 day of week。 如果星期中的某一天不正确，则函数使用正确的值，并且不返回错误。 如果任何其他日期值超出正确的范围，该函数将失败，并将最后一个错误设置为ERROR_INVALID_PARAMETER。
函数忽略 lpDate 指示的 SYSTEMTIME 结构的时间成员。 其中包括 wHour、 wMinute、 wSecond 和 wMilliseconds。
如果 lpFormat 参数包含错误的格式字符串，则函数不会返回任何错误，而只是形成可能的最佳日期字符串。 例如，唯一有效的年份图片是 L“yyyy”和 L“yy”，其中“L”指示 unicode (16 位字符) 字符串。 如果传入 L“y”，则函数假定 L“yy”。 如果传入 L“yyy”，则函数假定 L“yyyy”。 如果传入的图片 (L“dddd”) 或四个月 (L“MMMM”) ，则函数默认为 L“dddd”或 L“MMMM”。
应用程序应在日期格式图片中的单引号内将任何应保持其确切格式的文本括在日期字符串中。 单引号还可以用作转义字符，以允许单引号本身显示在日期字符串中。 但是，转义序列必须括在两个单引号内。 例如，若要将日期显示为“May '93”，格式字符串为：L“MMMM ''''yy”。 第一个和最后一个单引号是封闭引号。 第二个和第三个单引号是允许在世纪之前显示单引号的转义序列。
当日期图片同时包含日期 (d 或 dd) 和 MMMM) (月份的完整名称时，在日期字符串中检索月份名称的精灵形式。
若要在不执行任何实际格式的情况下获取默认的短日期和长日期格式，应用程序应将 GetLocaleInfoEx 与 LOCALE_SSHORTDATE 或 LOCALE_SLONGDATE 常量一起使用。 为了获取备用日历的日期格式，应用程序使用具有LOCALE_IOPTIONALCALENDAR常量的 GetLocaleInfoEx。 为了获取特定日历的日期格式，应用程序使用 GetCalendarInfoEx 传递相应的 日历标识符。 它可以调用 EnumCalendarInfoEx 或 EnumDateFormatsEx 来检索特定日历的日期格式。
此函数可以从 自定义区域设置检索数据。 不保证数据在计算机之间或应用程序运行之间的数据相同。 如果应用程序必须保留或传输数据，请参阅 使用永久性区域设置数据。
DATE_LONGDATE格式包括两种类型的日期模式：包含星期数的模式和不包括星期中的某一天的模式。 例如，“星期二，2016 年 10 月 18 日”或“2016 年 10 月 18 日”。 如果应用程序需要确保日期使用其中一种模式，而不是使用其他类型的模式，则应用程序应执行以下操作：
- 调用 EnumDateFormatsExExEx 函数 以获取DATE_LONGDATE格式的所有日期格式。
- 查找传递到为 EnumDateFormatsExEx 指定的 回调函数的第一个日期格式格式，该格式与请求的日历标识符匹配，并且具有与应用程序要求匹配的日期格式字符串。 例如，如果应用程序要求日期包含星期数的全名，请查找包含“dddd”的第一个日期格式;如果应用程序要求日期包含缩写名称或星期日期的全名，则查找不包含“ddd”和“ddd”的第一个日期格式。
- 调用 GetDateFormatEx 函数，并将 lpFormat 参数设置为在回调函数中标识为相应格式的日期格式字符串。
如果一周中某一天是否存在长日期格式对应用程序并不重要，则应用程序可以直接调用 GetDateFormatEx ，而无需通过调用 EnumDateFormatsExEx 首先枚举所有长日期格式。
从Windows 8开始：如果你的应用将语言标记从 Windows.Globalization 命名空间传递到此函数，它必须首先通过调用 ResolveLocaleName 来转换标记。
从 Windows 8 开始：GetDateFormatEx 在 Datetimeapi.h 中声明。 在Windows 8之前，它在 Winnls.h 中声明。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista [桌面应用 | UWP 应用] |
| 最低受支持的服务器 | Windows Server 2008 [桌面应用 | UWP 应用] |
| 目标平台 | Windows |
| 标头 | datetimeapi.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |