GetTimeFormatEx

原文链接 -> 传送门

函数功能：

GetTimeFormatEx 函数用于格式化由名称指定的区域时间字符串。该函数格式化时间字符串为指定的区域时间或本地系统时间。

注释1：只运行在 Windows Vista 以及之后的 Windows 版本的应用程序应该优先调用 GetTimeFormatEx 函数，而不是 GetTimeFormat 函数。

注释2：该函数可以格式化版本之间改变的数据，例如，自定义语言区域。如果您的应用程序必须要求数据相同或者传输数据，请参阅 Using Persistent Locale Data。


API 函数原型：

注释：_In_ 说明该参数是输入的，_Out_ 说明该参数是输出的，_opt_ 说明该参数是可选的。

int GetTimeFormatEx(
  _In_opt_        LPCWSTR    lpLocaleName,
  _In_            DWORD      dwFlags,
  _In_opt_  const SYSTEMTIME *lpTime,
  _In_opt_        LPCWSTR    lpFormat,
  _Out_opt_       LPWSTR     lpTimeStr,
  _In_            int        cchTime
);

参数解析：

返回值：

1. 如果函数调用成功，则返回写入 lpTimeStr 参数指向的缓冲区字符数。如果 cchTime 参数设置为 0，则返回所需容纳格式化过的时间字符串的缓冲区大小，含结尾空字符；

2. 如果函数调用失败，则返回 0 。

若想获得更多的错误信息，请调用 GetLastError 函数，下面是 GetLastError 函数返回的错误代码：

• ERROR_INSUFFICIENT_BUFFER：申请的缓冲区太小，或被错误地设置为 NULL
• ERROR_INVALID_FLAGS：分配給 dwFlags 参数的值无效
• ERROR_INVALID_PARAMETER：参数值全部都无效
• ERROR_OUTOFMEMORY：没有足够的可用内存来完成此操作

备注：

1. 如果时间标记存在且 dwFlags 参数没有设置 TIME_NOTIMEMARKER 参数值，函数基于指定区域标识符本地化时间标记。例如，英语（美国）的时间标记 "AM" 和 "PM" 。

2. lpTime 指针指向的 SYSTEMTIME 结构中的时间值必须有效。函数检查每一个时间值，以确定它是在适当范围值内。如果有时间值在正确的范围之外，则函数调用失败，并设置最后的错误代码为 ERROR_INVALID_PARAMETER。

3. 该函数忽略 SYSTEMTIME 结构的日期成员。这些日期成员为：wYear，wMonth，wDayOfWeek 和 wDay。

4. 如果指定 TIME_NOMINUTESORSECONDS 或 TIME_NOSECONDS 参数值，该函数移除分和秒或者分或秒成员前的分隔符。

5. 如果指定 TIME_NOTIMEMARKER 参数值，该函数移除时间标记之前和之后的分隔符。

6. 如果指定 TIME_FORCE24HOURFORMAT 参数值，则函数显示所有的时间标记。如果也设置 TIME_NOTIMEMARKER 标志，则不显示所有。

7. 该函数格式化过的时间字符串不包括毫秒。

8. 使用错误的时间格式字符串，该函数不报错，返回最大可能的时间字符串。如果超过 2 位小时，分，秒，或时间标记格式图片被传入，函数默认为 2。例如，唯一有效的是“t”和“tt”的时间标记图片。如果“ttt”传递中，函数假定“tt”。

9. 应用程序可以指定 LOCALE_STIMEFORMAT 参数值调用 GetLocaleInfoEx 函数，以获取没有经过任何格式化的时间格式。

10. 应用程序可以使用以下字符来构造的时间格式字符串。如果空格用于分隔时间格式字符串的字符，则这些空格在输出字符串的同一位置显示。该字母必须大写或小写，例如“ss”而不是“SS”。用单引号包起来的格式字符串格式的字符和用双引号包起来的格式字符串格式的字符结果一样。

例如，为了获得时间字符串 "11:29:40 PM"，应用程序应该使用 "hh':'mm':'ss tt" 图片字符串。

11. 该函数可以从自定义区域获取数据。在两个计算机或者两次程序运行之间不能保证获取的数据是相同的。如果您的应用程序必须要求数据相同或者传输数据，请参阅 Using Persistent Locale Data。

从 Windows 8 开始：如果您的应用程序从 Windows.Globalization 命名空间传递语言标记，它必须首先通过调用 ResolveLocaleName 函数转换语言标签。

从 Windows 8 开始：GetTimeFormatEx 函数在 Datetimeapi.h 头文件中声明。在 Windows 8 之前，在 Winnls.h 被声明。


需求：