getDateFormatA 函式 (datetimeapi.h)

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

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

 

語法

int GetDateFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpDateStr,
  [in]            int              cchDate
);

參數

[in] Locale

指定地區設定的地區設定識別碼,此函式會格式化的日期字串。 您可以使用 MAKELCID 宏來建立地區設定識別碼,或使用下列其中一個預先定義的值。

[in] dwFlags

指定日期格式選項的旗標。 如需詳細定義,請參閱GetDateFormatExdwFlags參數。

[in, optional] lpDate

SYSTEMTIME結構的指標,其中包含要格式化的日期資訊。 如果函式是使用目前的本機系統日期,應用程式會將此參數設定為 Null

[in, optional] lpFormat

用來形成日期之格式圖片字串的指標。 格式圖片字串的可能值定義于 日、月、年和紀元格式圖片中。

函式只會針對格式圖片字串中未指定的資訊使用指定的地區設定,例如地區設定的日和月名稱。 應用程式可以將此參數設定為 Null ,根據指定地區設定的日期格式來格式化字串。

[out, optional] lpDateStr

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

[in] cchDate

lpDateStr緩衝區的大小,以字元為單位。 應用程式可以將此參數設定為 0,以傳回保存格式化日期字串所需的緩衝區大小。 在此情況下,不會使用 lpDateStr 表示的緩衝區。

傳回值

如果成功,會傳回寫入 至 lpDateStr 緩衝區的字元數。 如果 cchDate 參數設定為 0,函式會傳回保存格式化日期字串所需的字元數,包括終止的 Null 字元。

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

  • ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大,或設定為 Null不正確。
  • ERROR_INVALID_FLAGS。 為旗標提供的值無效。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。

備註

注意 此 API 正在更新,以支援 2019 年 5 月日本紀元變更。 如果您的應用程式支援日曆,您應該驗證它是否正確地處理新紀元。 如需詳細資訊 ,請參閱為日文紀元變更準備您的應用程式
 
請參閱 GetDateFormatEx的。

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

從 Windows 8 開始: GetDateFormat 會在 Datetimeapi.h 中宣告。 在 Windows 8 之前,它會在 Winnls.h 中宣告。

注意

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

需求

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

另請參閱

日、月、年和紀元格式圖片

EnumCalendarInfo

EnumDateFormatsEx

GetCalendarInfo

GetDateFormatEx

GetLocaleInfo

GetTimeFormat

國家語言支援

國家語言支援函式