getDurationFormat 函数 (winnls.h)

项目
08/27/2023

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

注意出于互操作性原因，应用程序应优先使用 GetDurationFormatEx 函数而不是 GetDurationFormat ，因为 Microsoft 正在迁移到使用区域设置名称而不是新区域设置的区域设置标识符。仅在 Windows Vista 及更高版本上运行的任何应用程序都应使用 GetDurationFormatEx。

语法

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

参数

[in] Locale

区域设置标识符，指定此函数为其设置持续时间格式的区域设置。可以使用 MAKELCID 宏创建区域设置标识符，也可以使用以下预定义值之一。

Windows Vista 及更高版本： 还支持以下自定义区域设置标识符。

[in] dwFlags

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

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

[in, optional] lpDuration

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

[in] ullDuration

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

[in, optional] lpFormat

指向格式字符串的指针。有关详细信息，请参阅 GetDurationFormatEx 的 lpFormat 参数。

[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。任何参数值都无效。

注解

请参阅 GetDurationFormatEx 的备注。

要求

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