GetCalendarDateFormatEx 函式

已取代。 使用指定的日期和行事曆，擷取指定地區設定的格式正確日期字串。 使用者可以指定簡短日期格式、長日期格式、年月格式或自訂格式模式。

注意

此函式可以擷取版本之間變更的資料，例如，因為自訂地區設定。 如果您的應用程式必須保存或傳輸資料，請參閱 使用持續性地區設定資料。

 

語法

BOOL GetCalendarDateFormatEx(
  _In_        LPCWSTR       lpszLocale,
  _In_        DWORD         dwFlags,
  _In_  const LPCALDATETIME lpCalDateTime,
  _In_        LPCWSTR       lpFormat,
  _Out_       LPWSTR        lpDateStr,
  _In_        int           cchDate
);

參數

lpszLocale [in]

地區設定名稱的指標，或下列其中一個預先定義的值。

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

dwFlags [in]

指定日期格式選項的旗標。 如果 lpFormat 未設定為 Null，此參數必須設定為 0。 如果 lpFormat 設定為 Null，應用程式可以指定下列值和 LOCALE_NOUSEROVERRIDE的組合。

值	意義
DATE_SHORTDATE	使用簡短日期格式。 此為預設值。 這個值不能與DATE_LONGDATE或DATE_YEARMONTH搭配使用。
DATE_LONGDATE	使用長日期格式。 這個值不能與DATE_SHORTDATE或DATE_YEARMONTH搭配使用。
DATE_YEARMONTH	使用年/月格式。 這個值不能與DATE_SHORTDATE或DATE_LONGDATE搭配使用。
DATE_LTRREADING	新增由左至右閱讀版面配置的標記。 這個值不能與DATE_RTLREADING搭配使用。
DATE_RTLREADING	為從右至左閱讀版面配置新增標記。 這個值不能與DATE_LTRREADING搭配使用

 

lpCalDateTime [in]

CALDATETIME結構的指標，其中包含要格式化的日期和時間資訊。

lpFormat [in]

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

格式圖片字串必須以 Null 結尾。 函式只會針對格式圖片字串中未指定的資訊使用地區設定，例如地區設定的日和月名稱。 如果函式是使用指定地區設定的日期格式，應用程式會將此參數設定為 Null 。

lpDateStr [out]

這個函式接收格式化日期字串之緩衝區的指標。

cchDate [in]

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

傳回值

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

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

• ERROR_DATE_OUT_OF_RANGE。 指定的日期超出範圍。
• ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 Null不正確。
• ERROR_INVALID_FLAGS。 為旗標提供的值無效。
• ERROR_INVALID_PARAMETER。 任何參數值都無效。

備註

此函式支援的最早日期是 1601 年 1 月 1 日。

此函式沒有相關聯的標頭檔或程式庫檔案。 應用程式可以使用 DLL 名稱 (Kernel32.dll 呼叫 LoadLibrary) ，以取得模組控制碼。 然後，它可以使用該模組控制碼和此函式的名稱呼叫 GetProcAddress ，以取得函式位址。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
DLL	Kernel32.dll

另請參閱

國家語言支援

國家語言支援函式

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

NLS：以名稱為基礎的 API 範例

EnumDateFormatsExEx

GetDateFormat

GetDateFormatEx

CALDATETIME