GetTimeFormat

小甲鱼

注：本文档由 百日维新 翻译，小甲鱼校对。

原文链接 -> 传送门

函数功能：

GetTimeFormat 函数用于把时间字符串格式化为指定的区域时间格式。函数格式化一个指定的时间或本地的系统时间。

注意：由于互操作性，程序更倾向于使用 GetTimeFormatEx 函数而非 GetTimeFormat 函数，因为微软正在迁移到使用区域名称，取代使用区域标识。只运行在 Windows Vista 以及之后的 Windows 版本的应用程序应该使用 GetTimeFormatEx 函数。


API 函数原型：

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

int GetTimeFormat(
  _In_            LCID       Locale,
  _In_            DWORD      dwFlags,
  _In_opt_  const SYSTEMTIME *lpTime,
  _In_opt_        LPCTSTR    lpFormat,
  _Out_opt_       LPTSTR     lpTimeStr,
  _In_            int        cchTime
);

参数解析：

参数	含义
Locale	1. 区域的标识 2. 你可以使用 MAKELCID 宏创建区域标识或者使用下列其中一个预定义值： LOCALE_CUSTOM_DEFAULT LOCALE_CUSTOM_UI_DEFAULT LOCALE_CUSTOM_UNSPECIFIED LOCALE_INVARIANT LOCALE_SYSTEM_DEFAULT LOCALE_USER_DEFAULT
dwFlags	1. 指定时间格式选项的标记 2. 更多详细的定义参见 GetTimeFormatEx 函数的 dwFlags 参数
lpTime	1. 指向一个包含时间格式信息的系统结构指针 2. 设置该参数为 NULL 表示使用当前本地系统时间
lpFormat	1. 指向一个用来格式时间字符串的日期格式指针 2. 如果将该参数设置为 NULL，函数按照指定的区域时间格式格式化时间字符串 3. 如果该参数没有设置为 NULL，使用该参数值指定区域仅仅只是获取某些信息而不是获取指定在格式图片字符串中的信息，例如，区域特定时间标记 4. 更多格式图片字符串信息，参见备注部分
lpTimeStr	指向接收已格式化的时间字符串缓冲区指针
cchTime	1. 表示 lpTimeStr 指针指向的字符串缓冲区大小，以 TCHAR 为单位 2. 另外，你可以将这个参数设置为 0。在这种情况下，函数返回所需的时间字符串缓冲区的大小，并且不使用 lpTimeStr 参数

返回值：

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

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

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

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

备注：

1. 更多详细信息，参见 GetTimeFormatEx 函数备注部分。

2. 当 GetTimeFormat 函数的 ANSI 版本在只有 Unicode 区域标识中使用，函数调用会成功因为操作系统使用系统代码页。但是，如果字符串中有系统代码页未定义的字符就以问号（?）表示。

3. 从 Windows 8 以及之后的 Windows 版本 GetTimeFormat 函数在 Datetimeapi.h 声明。在 Windows 8 之前，在 Winnls.h 声明。


需求：

Minimum supported client	Windows 2000 专业版 [仅桌面应用程序]
Minimum supported server	Windows 2000 服务器版 [仅桌面应用程序]
Minimum supported phone	Windows Phone 8
Header	Datetimeapi.h (包含于  Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll
Unicode and ANSI names	GetTimeFormatW (Unicode) 和 GetTimeFormatA (ANSI)

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