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	hours
hh 或 HH	小時;如果小於 10，請在前置零前面加上
m	minutes
mm	分鐘;如果小於 10，請在前置零前面加上
s	seconds
ss	秒;如果小於 10，請在前置零前面加上
f	秒的分數注意字元「f」最多可以連續發生九次， (fffff) ，雖然頻率計時器的支援限制為 100 奈秒。因此，如果存在九個字元，最後兩位數一律為 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。不過，如果格式字串指定分鐘和秒，但應用程式會指定小時，則會據以調整分鐘數位段。
如果 fractions 不是第一個欄位，則格式字串中的「f」字元數表示要顯示 9 () 的十進位數。如果分數是第一個欄位，「f」字元的數目表示小於一秒的有效位數。
舍入是由截斷所發生，而不是由五個進位和四捨五入。
單引號可用來逸出字元。

從Windows 8開始：如果您的 app 從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' s'	05 公尺 45 秒
ss	345
ss' 秒	345 秒

uulDuration = 51234567 (5.1234567 秒)

格式	輸出
s.fff	5.123
s.ffffff	5.123456
s.fffffffffff	5.123456700 (新增尾端零)
fff 'ms'	5123 毫秒
ffffff 'microseconds'	5123456微秒
fffffff 'ns'	5123456700 ns

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平臺	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll