getTimeFormatEx 函数 (datetimeapi.h)
将时间格式化为由名称指定的区域设置的时间字符串。 函数设置指定时间或本地系统时间的格式。
语法
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_ACP 或 LOCALE_NOUSEROVERRIDE的组合。
值 | 含义 |
---|---|
|
请勿使用分钟或秒。 |
|
请勿使用秒。 |
|
请勿使用时间标记。 |
|
始终使用 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 结构的日期成员。 其中包括: wYear、 wMonth、 wDayOfWeek 和 wDay。
如果指定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 |