getTimeFormatEx 函数 (datetimeapi.h)

将时间格式化为由名称指定的区域设置的时间字符串。 函数设置指定时间或本地系统时间的格式。

注意 如果设计为仅在 Windows Vista 及更高版本上运行,则应用程序应优先调用 GetTimeFormat 函数。

 
注意 此函数可以设置不同版本之间更改的数据的格式,例如,由于自定义区域设置。 如果应用程序必须保留或传输数据,请参阅 使用永久性区域设置数据
 

语法

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

parameters

[in, optional] lpLocaleName

指向 区域设置名称或以下预定义值之一的指针。

[in] dwFlags

指定时间格式选项的标志。 应用程序可以指定以下值和 LOCALE_USE_CP_ACPLOCALE_NOUSEROVERRIDE的组合。

谨慎 强烈建议不要使用 LOCALE_NOUSEROVERRIDE ,因为它会禁用用户首选项。
 
含义
TIME_NOMINUTESORSECONDS
请勿使用分钟或秒。
TIME_NOSECONDS
请勿使用秒。
TIME_NOTIMEMARKER
请勿使用时间标记。
TIME_FORCE24HOURFORMAT
始终使用 24 小时时间格式。

[in, optional] lpTime

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

[in, optional] lpFormat

指向用于设置时间字符串格式的图片格式的指针。 如果应用程序将此参数设置为 NULL,则该函数将根据指定区域设置的时间格式设置字符串的格式。 如果应用程序未将 参数设置为 NULL,则该函数仅将区域设置用于未在格式图片字符串中指定的信息,例如特定于区域设置的时间标记。 有关格式图片字符串的信息,请参阅备注部分。

[out, optional] lpTimeStr

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

[in] cchTime

lpTimeStr 指示的时间字符串缓冲区的大小(以字符为单位)。 或者,应用程序可以将此参数设置为 0。 在这种情况下,函数返回时间字符串缓冲区所需的大小,并且不使用 lpTimeStr 参数。

返回值

返回 lpTimeStr 指示的缓冲区中检索到的字符数。 如果 cchTime 参数设置为 0,则该函数将返回保存格式化时间字符串(包括终止 null 字符)所需的缓冲区大小。

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

  • ERROR_INSUFFICIENT_BUFFER。 提供的缓冲区大小不够大,或者错误地设置为 NULL
  • ERROR_INVALID_FLAGS。 为标志提供的值无效。
  • ERROR_INVALID_PARAMETER。 任何参数值都无效。
  • ERROR_OUTOFMEMORY。 没有足够的存储空间可用于完成此操作。

注解

如果存在时间标记且未设置TIME_NOTIMEMARKER标志,则函数将根据指定的区域设置标识符本地化时间标记。 时间标记的示例为英语 (美国) 的“AM”和“PM”。

lpTime 指示的结构中的时间值必须有效。 函数检查每个时间值以确定它是否在适当的值范围内。 如果任何时间值超出了正确的范围,则函数将失败,并将最后一个错误设置为ERROR_INVALID_PARAMETER。

函数忽略 SYSTEMTIME 结构的日期成员。 其中包括: wYearwMonthwDayOfWeekwDay

如果指定TIME_NOMINUTESORSECONDS或TIME_NOSECONDS,函数将删除分钟和/或秒成员后面的分隔符。

如果指定了TIME_NOTIMEMARKER,函数将删除时间标记前面和后面的分隔符。

如果指定了TIME_FORCE24HOURFORMAT,该函数将显示任何现有的时间标记,除非还设置了TIME_NOTIMEMARKER标志。

该函数不包括毫秒作为格式化时间字符串的一部分。

该函数不返回错误格式字符串的错误,但只是构成可能的最佳时间字符串。 如果传入的图片超过两小时、分钟、秒或时间标记格式,则函数默认为 2。 例如,唯一有效的时间标记图片是“t”和“tt”。 如果传入“ttt”,则函数假定“tt”。

若要在不执行任何实际格式的情况下获取时间格式,应用程序应使用 GetLocaleInfoEx 函数,指定 LOCALE_STIMEFORMAT

应用程序可以使用以下元素来构造格式图片字符串。 如果使用空格分隔格式字符串中的元素,则这些空格将显示在输出字符串中的同一位置。 字母必须采用大写或小写,如所示,例如“ss”,而不是“SS”。 格式字符串中用单引号括起来的字符出现在同一位置,在输出字符串中保持不变。

图片 含义
h 对于个位数小时,没有前导零的小时数;12 小时制
hh 对于个位数小时数,前导为零的小时数;12 小时制
H 对于个位数小时,没有前导零的小时数;24 小时制
HH 对于个位数小时数,前导为零的小时数;24 小时制
m 对于个位数分钟,没有前导零的分钟数
mm 前导为零的分钟数(单位为分钟数)
s 对于个位数秒,没有前导零的秒
ss 前导零的秒数为个位数秒
t 一个字符的时间标记字符串,例如 A 或 P
tt 多字符时间标记字符串,例如 AM 或 PM
 

例如,获取时间字符串

"11:29:40 PM"

应用程序应使用图片字符串

"hh':'mm':'ss tt"

此函数可以从 自定义区域设置检索数据。 不保证数据在计算机之间或应用程序运行之间的数据相同。 如果应用程序必须保留或传输数据,请参阅 使用永久性区域设置数据

从Windows 8开始:如果你的应用将语言标记从 Windows.Globalization 命名空间传递到此函数,它必须首先通过调用 ResolveLocaleName 来转换标记。

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

要求

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

另请参阅

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

国家语言支持

国家语言支持函数