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
);

参数解析：

参数	含义
lpLocaleName	指向区域名称的指针，或者使用下列其中一个预定义值： LOCALE_NAME_INVARIANT LOCALE_NAME_SYSTEM_DEFAULT LOCALE_NAME_USER_DEFAULT
dwFlags	1. 指定时间格式选项的标记 2. 应用程序可以指定下列值和组合 LOCALE_USE_CP_ACP 或 LOCALE_NOUSEROVERRIDE： 值 含义 TIME_NOMINUTESORSECONDS 不使用分或秒 TIME_NOSECONDS 不使用秒 TIME_NOTIMEMARKER 不使用时间标记 TIME_FORCE24HOURFORMAT 始终使用 24 小时时间格式 注意：强烈反对使用 LOCALE_NOUSEROVERRIDE ，因为它禁用用户偏好。
lpTime	1. 指向包含待格式化的时间信息 SYSTEMTIME 结构指针 2. 如果要格式化为当前的本地系统时间格式，应用程序可以将该参数设置为 NULL
lpFormat	1. 指向一个用来格式时间字符串的日期格式指针 2. 如果将该参数设置为 NULL，函数按照指定的区域时间格式格式化时间字符串 3. 如果该参数没有设置为 NULL，使用该参数值指定区域仅仅只是获取某些信息而不是获取指定在格式图片字符串中的信息，例如，区域特定时间标记 4. 更多格式图片字符串信息，参见备注部分。
lpTimeStr	指向接收已格式化的时间字符串缓冲区指针
cchTime	1. 表示 lpTimeStr 指针指向的字符串缓冲区大小，以字符为单位 2. 另外，您可以将这个参数设置为 0。在这种情况下，函数返回所需的时间字符串缓冲区的大小，且不使用 lpTimeStr 参数

返回值：

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”。用单引号包起来的格式字符串格式的字符和用双引号包起来的格式字符串格式的字符结果一样。

字符	含义
h	前面没有 0 填充的单数字小时；12 小时制
hh	前面有 0 填充的单数字小时；12 小时制
H	前面没有 0 填充的单数字小时；24 小时制
HH	前面有 0 填充的单数字小时；24 小时制
m	前面没有 0 填充的单数字分钟
mm	前面有 0 填充的单数字分钟
s	前面没有 0 填充的单数字秒
ss	前面有 0 填充的单数字秒
t	单个时间字符串标记字符，如 A 或 P
tt	多个时间字符串标记字符，如 AM 或 PM

例如，为了获得时间字符串 "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 被声明。


需求：

Minimum supported client	Windows Vista [桌面应用 | Windows 商店应用]
Minimum supported server	Windows 2008 服务器 [桌面应用 | Windows 商店应用]
Minimum supported phone	Windows Phone 8.1
Header	Datetimeapi.h (包含于  Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

【API档案】版权归鱼C工作室（www.fishc.com）所有，转载请注明来源。

拈花小仙

小新现在翻译水平越来越高啦`