getTimeFormatA 函式 (datetimeapi.h)

  • 發行項

將時間格式化為識別碼所指定地區設定的時間字串。 函式會格式化指定的時間或本機系統時間。

注意 基於互操作性考慮，應用程式應該偏好 GetTimeFormatEx 函式為 GetTimeFormat ，因為 Microsoft 正移轉至使用地區設定名稱，而不是新地區設定的地區設定標識符。 任何只會在 Windows Vista 和更新版本上執行的應用程式都應該使用 GetTimeFormatEx。
 

語法

int GetTimeFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpTimeStr,
  [in]            int              cchTime
);

參數

[in] Locale

指定地區設定的地區設定識別碼。 您可以使用 MAKELCID 宏來建立地區設定標識碼，或使用下列其中一個預先定義的值。

[in] dwFlags

指定時間格式選項的旗標。 如需詳細定義，請參閱 GetTimeFormatEx 的 dwFlags 參數。

[in, optional] lpTime

SYSTEMTIME 結構的指標，其中包含要格式化的時間資訊。 如果函式是使用目前的本機系統時間，應用程式可以將此參數設定為 NULL 。

[in, optional] lpFormat

用來格式化時間字串之格式圖片的指標。 如果應用程式將此參數設定為 NULL，函式會根據指定地區設定的時間格式來格式化字串。 如果應用程式未將 參數設定為 NULL，則函式只會針對格式圖片字串中未指定的資訊使用地區設定，例如地區設定特定的時間標記。 如需格式圖片字串的相關信息，請參閱一節。

[out, optional] lpTimeStr

此函式擷取格式化時間字串之緩衝區的指標。

[in] cchTime

大小，以 TCHAR 為單位，代表 lpTimeStr 所指示的時間字串緩衝區。 或者，應用程式可以將此參數設定為 0。 在此情況下，函式會傳回時間字串緩衝區所需的大小，而且不會使用 lpTimeStr 參數。

傳回值

傳回 lpTimeStr 所指示之緩衝區中擷取的 TCHAR 值數目。 如果 cchTime 參數設定為 0，函式會傳回保存格式化時間字串所需的緩衝區大小，包括終止的 Null 字元。

如果函式不成功，此函式會傳回 0。 若要取得擴充的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

  • ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 NULL 不正確。
  • ERROR_INVALID_FLAGS。 為旗標的值無效。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。
  • ERROR_OUTOFMEMORY。 沒有足夠的記憶體可完成此作業。

備註

請參閱 GetTimeFormatEx 的備註。

當此函式的 ANSI 版本與僅限 Unicode 的地區設定識別碼搭配使用時，函式可能會成功，因為操作系統使用系統代碼頁。 不過，系統代碼頁中未定義的字元會顯示在字串中，做為問號 (？) 。

從 Windows 8 開始：GetTimeFormat 會在 Datetimeapi.h 中宣告。 在 Windows 8 之前，它會在 Winnls.h 中宣告。

注意

datetimeapi.h 標頭會將 GetTimeFormat 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 datetimeapi.h
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

GetDateFormat

GetLocaleInfo

GetTimeFormatEx

國家語言支援

國家語言支援函式