GetDateFormatEx 函式 (datetimeapi.h)
將日期格式化為名稱所指定地區設定的日期字串。 函式會格式化指定的日期或本機系統日期。
語法
int GetDateFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpDate,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpDateStr,
[in] int cchDate,
[in, optional] LPCWSTR lpCalendar
);
參數
[in, optional] lpLocaleName
地區設定名稱的指標，或下列其中一個預先定義的值。
[in] dwFlags
指定當 lpFormat 設定為 NULL 時可設定的各種函式選項的旗標。 應用程式可以指定下列值和 LOCALE_USE_CP_ACP 或 LOCALE_NOUSEROVERRIDE的組合。
如果應用程式未指定DATE_YEARMONTH、DATE_MONTHDAY、DATE_SHORTDATE或DATE_LONGDATE，且 lpFormat 設定為 NULL，則DATE_SHORTDATE為預設值。
[in, optional] lpDate
SYSTEMTIME 結構的指標，其中包含要格式化的日期資訊。 如果函式是使用目前的本機系統日期，應用程式可以將此參數設定為 NULL 。
[in, optional] lpFormat
用來形成日期之格式圖片字串的指標。 格式圖片字串的可能值定義於 日、月、年和紀元格式圖片中。
例如，若要取得日期字串 “Wed， Oct 31 94”，應用程式會使用圖片字串 “ddd'，' MMM dd yy”。
函式只會針對格式圖片字串中未指定的資訊使用指定的地區設定，例如地區設定的日和月名稱。 應用程式可以將此參數設定為 NULL ，根據指定地區設定的日期格式來格式化字串。
[out, optional] lpDateStr
此函式擷取格式化日期字串之緩衝區的指標。
[in] cchDate
lpDateStr 緩衝區的大小，以字元為單位。 應用程式可以將此參數設定為 0，以傳回儲存格式化日期字串所需的緩衝區大小。 在此情況下，不會使用 lpDateStr 表示的緩衝區。
[in, optional] lpCalendar
保留;必須設定為 NULL。
傳回值
如果成功，會傳回寫入 至 lpDateStr 緩衝區的字元數。 如果 cchDate 參數設定為 0，函式會傳回保存格式化日期字串所需的字元數，包括終止的 Null 字元。
如果函式不成功，此函式會傳回 0。 若要取得擴充的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：
- ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 NULL 不正確。
- ERROR_INVALID_FLAGS。 為旗標的值無效。
- ERROR_INVALID_PARAMETER。 任何參數值都無效。
備註
日期名稱、縮寫日期名稱、月份名稱和縮寫月份名稱都會根據地區設定標識符進行當地語系化。
lpDate 所指示之結構的日期值必須有效。 函式會檢查每個日期值：年、月、日和周中的日。 如果星期數不正確，函式會使用正確的值，而且不會傳回錯誤。 如果任何其他日期值超出正確的範圍，函式會失敗，並將最後一個錯誤設定為ERROR_INVALID_PARAMETER。
函式會忽略 lpDate 所指示之 SYSTEMTIME 結構的時間成員。 其中包括 wHour、 wMinute、 wSecond 和 wMilliseconds。
如果 lpFormat 參數包含不正確的格式字串，則函式不會傳回任何錯誤，但只會形成最佳的可能日期字串。 例如，有效的唯一年份圖片是 L“yyyy” 和 L“yy”，其中 “L” 表示 Unicode (16 位字元) 字串。 如果傳入 L“y” ，函式會假設 L“yy”。 如果傳入 L“yyy”，函式會假設 L“yyyy”。 如果傳入四個以上的日期 (L“dddd”) 或四個月 (L“MMMM”) 圖片，則函式預設為 L“dddd” 或 L“MMMM”。
應用程式應該以日期格式圖片中的單引弧括住任何文字，該文字應該以其確切格式括住日期字串。 單引號也可以用來做為逸出字元，以允許在日期字串中顯示單引號本身。 不過，逸出序列必須括在兩個單引號內。 例如，若要將日期顯示為 “May '93”，格式字元串為：L“MMMM ''''yy”。 第一個和最後一個單引號是括住的引號。 第二個和第三個單引號是逸出序列，允許在百年之前顯示單引號。
當日期圖片同時包含日期格式 (d 或 dd) ，以及 MMMM) 的完整月份 (名稱，則會在日期字串串中擷取月份名稱的世代形式。
若要取得預設的簡短和完整日期格式，而不執行任何實際格式設定，應用程式應該使用 GetLocaleInfoEx 搭配 LOCALE_SSHORTDATE 或 LOCALE_SLONGDATE 常數。 若要取得替代行事曆的日期格式，應用程式會使用 GetLocaleInfoEx 搭配 LOCALE_IOPTIONALCALENDAR 常數。 若要取得特定行事曆的日期格式，應用程式會使用 GetCalendarInfoEx，傳遞適當的 行事曆標識符。 它可以呼叫 EnumCalendarInfoEx 或 EnumDateFormatsEx 來擷取特定行事曆的日期格式。
此函式可以從 自定義地區設定擷取數據。 數據不保證從計算機到計算機或在應用程式執行之間相同。 如果您的應用程式必須保存或傳輸數據，請參閱 使用持續性地區設定數據。
DATE_LONGDATE格式包含兩種日期模式：包含星期數的模式，以及不包含星期數的模式。 例如，「星期二，2016 年 10 月 18 日」或「2016 年 10 月 18 日」。 如果您的應用程式需要確保日期使用下列其中一種模式，而不是其他類型的模式，您的應用程式應該執行下列動作：
- 呼叫 EnumDateFormatsExEx 函 式，以取得DATE_LONGDATE格式的所有日期格式。
- 尋找傳遞至您為 EnumDateFormatsExEx 所指定之回呼函式的第一個日期格式，其符合您要求的行事曆標識符，並具有符合您應用程式需求的日期格式字符串。 例如，如果您的應用程式要求日期包含星期數的完整名稱，則尋找包含 「dddd」 的第一個日期格式，或尋找不包含 「d」 或 「dd」 的第一個日期格式，如果您的應用程式要求日期包含縮寫名稱或周日的完整名稱。
- 呼叫 GetDateFormatEx 函式，並將 lpFormat 參數設定為回呼函式中識別為適當格式的日期格式字串。
如果長時間日期格式的星期數是否存在與應用程式無關，您的應用程式可以直接呼叫 GetDateFormatEx ，而不需要先呼叫 EnumDateFormatsEx 來列舉所有長日期格式。
從 Windows 8 開始：如果您的 app 從 Windows.Globalization 命名空間將語言標記傳遞至此函式，則必須先呼叫 ResolveLocaleName 來轉換標記。
從 Windows 8 開始：GetDateFormatEx 會在 Datetimeapi.h 中宣告。 在 Windows 8 之前，它會在 Winnls.h 中宣告。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | datetimeapi.h |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |