getDurationFormatEx 函数 (winnls.h)

项目
03/18/2023

将持续时间格式化为由名称指定的区域设置的时间字符串。

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

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

语法

int GetDurationFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDuration,
  [in]            ULONGLONG        ullDuration,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDurationStr,
  [in]            int              cchDuration
);

参数

[in, optional] lpLocaleName

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

[in] dwFlags

指定函数选项的标志。如果 lpFormat 未设置为 NULL，则此参数必须设置为 0。如果 lpFormat 设置为 NULL，则应用程序可以指定 LOCALE_NOUSEROVERRIDE ，以使用指定区域设置的系统默认持续时间格式设置字符串的格式。

谨慎强烈建议不要使用 LOCALE_NOUSEROVERRIDE ，因为它会禁用用户首选项。

[in, optional] lpDuration

指向 SYSTEMTIME 结构的指针，该结构包含要设置格式的时间持续时间信息。如果函数忽略此参数并使用 ullDuration，则应用程序会将此参数设置为 NULL。

[in] ullDuration

64 位无符号整数，表示持续时间中的 100 纳秒间隔数。如果同时设置了 lpDuration 和 ullDuration ，则 lpDuration 参数优先。如果 lpDuration 设置为 NULL ， ullDuration 设置为 0，则持续时间为 0。

[in, optional] lpFormat

指向带字符的格式字符串的指针，如下所示。如果函数要根据指定区域设置的持续时间格式设置字符串的格式，则应用程序可以将此参数设置为 NULL 。如果 lpFormat 未设置为 NULL，则该函数仅对格式图片字符串中未指定的信息使用区域设置。

值	含义
d	days
h 或 H	小时
hh 或 HH	小时;如果小于 10，则前面添加前导零
m	分钟数
mm	分钟;如果小于 10，则前面添加前导零
s	seconds
ss	秒;如果小于 10，则前面添加前导零
f	秒的分数注意字符“f”最多可以连续出现九次 (fffffffff) ，但对频率计时器的支持限制为 100 纳秒。因此，如果存在 9 个字符，则最后两位数始终为 0。

[out, optional] lpDurationStr

指向函数在其中检索持续时间字符串的缓冲区的指针。

或者，如果 cchDuration 设置为 0，此参数将检索 NULL。在这种情况下，函数返回持续时间字符串缓冲区所需的大小。

[in] cchDuration

lpDurationStr 指示的缓冲区的大小（以字符为单位）。

或者，应用程序可以将此参数设置为 0。在这种情况下，函数在 lpDurationStr 中检索 NULL，并返回持续时间字符串缓冲区所需的大小。

返回值

如果成功，则返回 lpDurationStr 指示的缓冲区中检索到的字符数。如果 lpDurationStr 设置为 NULL ， cchDuration 设置为 0，则该函数将返回持续时间字符串缓冲区所需的大小，包括终止 null 字符。例如，如果将 10 个字符写入缓冲区，则该函数返回 11 以包含终止 null 字符。

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

ERROR_INSUFFICIENT_BUFFER。提供的缓冲区大小不够大，或者错误地设置为 NULL。
ERROR_INVALID_PARAMETER。任何参数值都无效。

备注

此函数可用于显示文件时间的多媒体应用程序和显示完成时间的体育赛事应用程序。

函数忽略 SYSTEMTIME 结构的前三个成员： wYear、 wMonth 和 wDayOfWeek。

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

以下是持续时间格式字符串的特征：

格式字符为小写。
注意 (H) 与 GetTimeFormatEx 保持一致是一个例外。
如果值小于 10，则小时、分钟和秒的两位数格式字符串在前导零前面添加。
第一个输出字段不受任何边界测试 (小时<24、分钟<60、秒<60、毫秒<1000) 。日期不受边界测试的约束。
函数假定所有格式字符串的字段大小都在减小，例如小时、分钟、秒、毫秒。
要显示的第一个字段将按照格式字符串的定义进行规范化。例如，如果应用程序指定 310 秒，并且格式字符串为 m：ss，则输出为 5：10。但是，如果格式字符串指定分钟和秒，但应用程序指定小时，则会相应地调整分钟字段。
如果分数不是第一个字段，则格式字符串中的“f”字符数指示显示的小数位数， (限制为 9) 。如果分数是第一个字段，则“f”字符数表示低于 1 秒的有效位数。
舍入是通过截断进行的，而不是按五舍五下的规则进行。
单引号用于转义字符。

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

示例

下面是指定持续时间的持续时间格式和相应输出的示例。

SYSTEMTIME = 14 天、2 小时、45 分钟、12 秒和 247 毫秒

格式	输出
d：hh：mm：ss	14:02:45:12
hh：mm：ss：ff	338:45:12:24
hh：mm：ss：fff	338:45:12:247
h' h 'mm' m 'ss' s'	338 小时 45 米 12 秒

SYSTEMTIME = 345 秒

格式	输出
hh:mm:ss	00:05:45
h：mm：ss	0:05:45
mm：ss	05:45
m：ss	5:45
mm' m 'ss'	05 m 45 秒
ss	345
ss' 秒'	345 秒

uulDuration = 51234567 (5.1234567 秒)

格式	输出
s.fff	5.123
s.ffffff	5.123456
s.fffffffff	5.123456700 (添加尾随零)
fff 'ms'	5123 毫秒
ffffff '微秒'	5123456微秒
fffffffff “ns”	5123456700 ns

要求


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