GetTimeFormatEx 函式 (datetimeapi.h)
將時間格式化為名稱所指定地區設定的時間字串。 函式會格式化指定的時間或本機系統時間。
語法
int GetTimeFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpTime,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpTimeStr,
[in] int cchTime
);
參數
[in, optional] lpLocaleName
地區設定名稱的指標，或下列其中一個預先定義的值。
[in] dwFlags
指定時間格式選項的旗標。 應用程式可以指定下列值和 LOCALE_USE_CP_ACP 或 LOCALE_NOUSEROVERRIDE的組合。
| 值 | 意義 |
|---|---|
|
請勿使用分鐘或秒。 |
|
請勿使用秒數。 |
|
請勿使用時間標記。 |
|
一律使用 24 小時的時間格式。 |
[in, optional] lpTime
SYSTEMTIME結構的指標，其中包含要格式化的時間資訊。 如果函式是使用目前的本機系統時間，應用程式可以將此參數設定為 Null 。
[in, optional] lpFormat
用來格式化時間字串之格式圖片的指標。 如果應用程式將此參數設定為 Null，則函式會根據指定地區設定的時間格式來格式化字串。 如果應用程式未將 參數設定為 Null，則函式只會針對格式圖片字串中未指定的資訊使用地區設定，例如地區設定特定的時間標記。 如需格式圖片字串的詳細資訊，請參閱一節。
[out, optional] lpTimeStr
這個函式擷取格式化時間字串的緩衝區指標。
[in] cchTime
大小，以字元為單位，表示 lpTimeStr所指示的時間字串緩衝區。 或者，應用程式可以將此參數設定為 0。 在此情況下，函式會傳回時間字串緩衝區所需的大小，而且不會使用 lpTimeStr 參數。
傳回值
傳回 lpTimeStr所指示之緩衝區中擷取的字元數。 如果 cchTime 參數設定為 0，則函式會傳回保留格式化時間字串所需的緩衝區大小，包括終止的 Null 字元。
如果函式未成功，此函式會傳回 0。 若要取得延伸的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：
- ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 Null不正確。
- ERROR_INVALID_FLAGS。 為旗標提供的值無效。
- ERROR_INVALID_PARAMETER。 任何參數值都無效。
- ERROR_OUTOFMEMORY。 沒有足夠的儲存體可完成這項作業。
備註
如果時間標記存在且未設定TIME_NOTIMEMARKER旗標，則函式會根據指定的地區設定識別碼當地語系化時間標記。 時間標記的範例包括英文 (美國) 的 「AM」 和 「PM」。
lpTime所指示結構中的時間值必須有效。 函式會檢查每個時間值，以判斷其是否位於適當的值範圍內。 如果任何時間值超出正確的範圍，則函式會失敗，並將最後一個錯誤設定為ERROR_INVALID_PARAMETER。
函式會忽略 SYSTEMTIME 結構的日期成員。 這些包括： wYear、 wMonth、 wDayOfWeek和 wDay。
如果指定TIME_NOMINUTESORSECONDS或TIME_NOSECONDS，則函式會在分鐘和/或秒成員之後移除分隔符號。
如果指定了TIME_NOTIMEMARKER，函式會移除時間標記前面和之後的分隔符號。
如果指定TIME_FORCE24HOURFORMAT，則函式會顯示任何現有的時間標記，除非同時設定TIME_NOTIMEMARKER旗標。
函式不包含毫秒做為格式化時間字串的一部分。
函式不會傳回不正確的格式字串錯誤，但只會形成最佳的可能時間字串。 如果傳入超過兩小時、分鐘、秒或時間標記格式圖片，則函式預設為兩個。 例如，有效的唯一時間標記圖片是 「t」 和 「tt」。 如果傳入 「ttt」，函式會假設 「tt」。
若要取得時間格式而不執行任何實際格式設定，應用程式應該使用 GetLocaleInfoEx 函式，並指定 LOCALE_STIMEFORMAT。
應用程式可以使用下列元素來建構格式圖片字串。 如果使用空格分隔格式字串中的專案，這些空格會出現在輸出字串中的相同位置。 字母必須以大寫或小寫表示，例如「ss」，而不是 「SS」。 以單引號括住的格式字串中的字元會出現在相同的位置，且輸出字串中未變更。
| Picture | 意義 |
|---|---|
| h | 沒有前置零的小時數，則為單一位數時數;12 小時制 |
| hh | 單一位數時數為前置零的小時數;12 小時制 |
| H | 沒有前置零的小時數，則為單一位數時數;24 小時制 |
| HH | 單一位數時數為前置零的小時數;24 小時制 |
| m | 單一位數分鐘沒有前置零的分鐘數 |
| mm | 單一位數分鐘數為前置零的分鐘數 |
| s | 在單一位數秒內沒有前置零的秒數 |
| ss | 具有前置零的秒數，以單一位數秒為單位 |
| t | 一個字元時間標記字串，例如 A 或 P |
| tt | 多重字元時間標記字串，例如 AM 或 PM |
例如，若要取得時間字串
"11:29:40 PM"
應用程式應該使用圖片字串
"hh':'mm':'ss tt"
此函式可以從 自訂地區設定擷取資料。 資料不保證從電腦到電腦或在應用程式執行之間相同。 如果您的應用程式必須保存或傳輸資料，請參閱 使用持續性地區設定資料。
從Windows 8開始：如果您的 app 從Windows.Globalization命名空間將語言標記傳遞至此函式，則必須先呼叫ResolveLocaleName來轉換標記。
從Windows 8開始：GetTimeFormatEx會在 Datetimeapi.h 中宣告。 在Windows 8之前，它會在 Winnls.h 中宣告。
規格需求
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | Windows |
| 標頭 | datetimeapi.h |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |