GetTimeFormat函数将时间格式化为指定区域设置的时间字符串。该函数格式化指定时间或本地系统时间。
int GetTimeFormat(
LCID 【语言环境】, | //将要格式化哪个时间的语言环境 |
DWORD 【dwFlags中】, | //标志指定功能选项 |
CONST SYSTEMTIME【* lpTime】, | //要格式化的时间 |
LPCTSTR 【lpFormat】, | //时间格式字符串 |
LPTSTR 【lpTimeStr】, | //存储格式化字符串的缓冲区 |
INT 【cchTime】 | //缓冲区的大小(以字节或字符为单位) |
); |
参数
【语言环境】
指定要格式化时间字符串的区域设置。如果【lpFormat】为NULL,则该函数将根据该语言环境的时间格式格式化该字符串。如果【lpFormat】不为NULL,则该函数仅对格式图片字符串中未指定的信息(例如,语言环境的时间标记)使用区域设置。
此参数可以是由MAKELCID宏或以下预定义值之一创建的区域设置标识符:
LOCALE_SYSTEM_DEFAULT | 默认系统区域设置。 |
LOCALE_USER_DEFAULT | 默认用户区域设置。 |
【dwFlags中】
一组位标志,指定各种功能选项。您可以指定以下标志的组合:
旗 | 含义 |
LOCALE_NOUSEROVERRIDE | 如果设置,该函数使用指定语言环境的系统默认时间格式对字符串进行格式化。如果未设置,该函数将使用任何用户覆盖到语言环境的默认时间格式来格式化该字符串。如果【lpFormat】非空,则无法设置此标志。 |
TIME_NOMINUTESORSECONDS | 不要使用几分钟或几秒钟。 |
TIME_NOSECONDS | 不要使用秒。 |
TIME_NOTIMEMARKER | 不要使用时间标记。 |
TIME_FORCE24HOURFORMAT | 始终使用24小时时间格式。 |
【lpTime】
指向SYSTEMTIME结构的指针,其中包含要格式化的时间信息。如果此指针为NULL,则该函数使用当前本地系统时间。
【lpFormat】
指向用于形成时间字符串的格式图片。如果【lpFormat】为NULL,则该函数使用指定语言环境的时间格式。
使用以下元素构建格式图片字符串。如果使用空格分隔格式字符串中的元素,则这些空格将显示在输出字符串中的相同位置。字母必须以大写或小写形式显示(例如,“ss”而不是“SS”)。包含在单引号中的格式字符串中的字符将显示在输出字符串中的相同位置和不变。
图片 | 含义 |
h | Hours with no leading zero for single-digit hours; 12-hour clock |
hh | Hours with leading zero for single-digit hours; 12-hour clock |
H | Hours with no leading zero for single-digit hours; 24-hour clock |
HH | Hours with leading zero for single-digit hours; 24-hour clock |
m | 对于单位数分钟,分钟不带前导零 |
mm | 分数为零,单位数分钟 |
s | 秒数无单位数秒的前导零 |
ss | 秒数为零,单位数秒 |
t | 一个字符时间标记字符串,如A或P |
tt | 多字符时间标记字符串,如AM或PM |
例如,获取时间字符串
"11:29:40 PM"
使用以下图片字符串:
“hh”:'mm':'ss tt“
【lpTimeStr】
指向接收格式化时间字符串的缓冲区的指针。
【cchTime】
指定【lpTimeStr】缓冲区的大小(以字节为单位(ANSI版本)或字符(Unicode版本))。如果【cchTime】为零,则该函数返回保存格式化时间字符串所需的字节数或字符数,不使用【lpTimeStr】指向的缓冲区。
返回值
如果函数成功,则返回值是写入【lpTimeStr】指向的缓冲区的字节数(ANSI版本)或字符(Unicode版本)。如果【cchTime】参数为零,则返回值是保存格式化时间字符串所需的字节数或字符数。
如果函数失败,返回值为零。要获取扩展错误信息,请调用GetLastError.GetLastError可能会返回以下错误代码之一:
ERROR_INSUFFICIENT_BUFFER |
ERROR_INVALID_FLAGS |
ERROR_INVALID_PARAMETER |
备注
如果存在时间标记并且未设置TIME_NOTIMEMARKER标志,则该函数将根据指定的区域设置标识符来定位时间标记。时间标记的例子是美国英语的“AM”和“PM”。
【lpTime】指向的SYSTEMTIME结构中的时间值必须有效。该函数检查每个时间值以确定它在适当的值范围内。如果任何时间值超出正确的范围,该函数将失败,并将最后一个错误设置为ERROR_INVALID_PARAMETER。
该函数忽略【lpTime】指向的SYSTEMTIME结构的日期部分:wYear,wMonth,wDayOfWeek和wDayso.
如果指定了TIME_NOMINUTESORSECONDS或TIME_NOSECONDS,则该函数将删除分钟和/或秒元素之前的分隔符。
如果指定了TIME_NOTIMEMARKER,则该函数将删除时间标记之前和之后的分隔符。
如果指定了TIME_FORCE24HOURFORMAT,该函数将显示任何现有的时间标记,除非TIME_NOTIMEMARKER标志也被设置。
该函数不包括毫秒作为格式化时间字符串的一部分。
要使用LOCALE_NOUSEROVERRIDE标志,【lpFormat】必须为NULL。
对于错误的格式字符串不会返回错误。该函数只需形成最佳的时间字符串即可。如果超过两个小时,分钟,秒或时间标记格式图片被传入,则该函数默认为两个。例如,有效的唯一时间标记画面是L“t”,L“tt”(“L”表示Unicode(16位字符)字符串)。如果传入L“ttt”,则函数假定为L“tt”。
也可以看看