GetCalendarInfoA 函式（winnls.h）

發行項
11/20/2024

擷取標識碼所指定地區設定之行事曆的相關信息。

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

語法

int GetCalendarInfoA(
  [in]            LCID    Locale,
  [in]            CALID   Calendar,
  [in]            CALTYPE CalType,
  [out, optional] LPSTR   lpCalData,
  [in]            int     cchData,
  [out, optional] LPDWORD lpValue
);

參數

[in] Locale

地區設定標識子，指定要擷取行事曆信息的地區設定。您可以使用 MAKELCID 巨集來建立地區設定識別碼，或使用下列其中一個預先定義的值。

[in] Calendar

行事曆識別碼。

[in] CalType

要擷取的信息類型。如需詳細資訊，請參閱行事曆類型資訊。

NoteGetCalendarInfo 如果此參數指定CAL_IYEAROFFSETRANGE或CAL_SERASTRING，則只會傳回一個字元串。在這兩種情況下，都會傳回目前的紀元。

CAL_USE_CP_ACP僅適用於此函式的 ANSI 版本。

針對CAL_NOUSEROVERRIDE，函式會忽略 setCalendarInfo 所設定的任何值，並使用目前系統預設地區設定的資料庫設定。此類型僅與組合CAL_NOUSEROVERRIDE相關 |CAL_ITWODIGITYEARMAX。 CAL_ITWODIGITYEARMAX是唯一可由 setCalendarInfo所設定的值。

[out, optional] lpCalData

緩衝區的指標，此函式會擷取要求的數據做為字串。如果在 CalType中指定CAL_RETURN_NUMBER，此參數必須擷取 NULL。

[in] cchData

大小，以字元為單位，lpCalData 緩衝區。應用程式可以將此參數設定為 0，以傳回行事曆數據緩衝區所需的大小。在此情況下，不會使用 lpCalData 參數。如果為 CalType指定CAL_RETURN_NUMBER，cchData 的值必須是 0。

[out, optional] lpValue

以數位的形式接收所要求數據的變數指標。如果在 CalType中指定CAL_RETURN_NUMBER，則 lpValue 不得 NULL。如果未在 CalType中指定CAL_RETURN_NUMBER，則 lpValue 必須 NULL。

傳回值

傳回在 lpCalData 緩衝區中擷取的字元數，如果成功，cchData 設為非零值。如果函式成功，cchData 設定為 0，且未指定CAL_RETURN_NUMBER，傳回值是保存行事曆資訊所需的緩衝區大小。如果函式成功，cchData 設定為 0，且指定CAL_RETURN_NUMBER，則傳回值是 lpValue中擷取的值大小，也就是 2 代表函式的 Unicode 版本，或 ANSI 版本的 4。

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

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

言論

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

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winnls.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll