GetDurationFormat 函式 (winnls.h)

發行項
03/04/2024

將持續時間格式化為識別碼所指定地區設定的時間字串。

注意基於互操作性考慮，應用程式應該偏好 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)
程式庫	Kernel32.lib
DLL	Kernel32.dll