GetLocaleInfoA 函式（winnls.h）

發行項
11/20/2024

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

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

注意為了取得全域相容性，應用程式應該偏好 Unicode “W” API 窗體至 “A” 表單。 GetLocaleInfoA 會限制字元數據，並可能導致對用戶顯示損毀的結果，特別是在啟用全域的應用程式中。針對此 API，GetLocaleInfoEx 是慣用的，因為它是 Unicode，也支援新式地區設定名稱標準。

語法

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

參數

[in] Locale

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

[in] LCType

要擷取的地區設定資訊。如需詳細定義，請參閱 getLocaleInfoExLCType 參數。

Note For GetLocaleInfo，值LOCALE_USE_CP_ACP僅與 ANSI 版本相關。

[out, optional] lpLCData

這個函式擷取所要求地區設定資訊的緩衝區指標。如果 cchData 設為 0，則不會使用此指標。如需詳細資訊，請參閱一節。

[in] cchData

大小，以 TCHAR 值表示的數據緩衝區，lpLCData。或者，應用程式可以將此參數設定為 0。在此情況下，函式不會使用 lpLCData 參數，並傳回必要的緩衝區大小，包括終止的 Null 字元。

傳回值

如果成功且 cchData 為非零值，則傳回地區設定數據緩衝區中擷取的字元數。如果函式成功，cchData 為非零，且指定 LOCALE_RETURN_NUMBER，傳回值會是數據緩衝區中擷取的整數大小;也就是 2 表示函式的 Unicode 版本，或 ANSI 版本的 4。如果函式成功 ，且 cchData 的值為 0，則傳回值會是地區設定數據緩衝區的字元，包括 null 字元所需的大小。

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

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

言論

如需此函式的作業，請參閱 GetLocaleInfoEx的備註。

注意即使將 LCType 參數指定為 LOCALE_FONTSIGNATURE，cchData，且函式傳回仍然是 TCHAR 計數。此計數與 ANSI 和 Unicode 版本的函式不同。當應用程式使用 LOCALE_FONTSIGNATURE 呼叫 GetLocaleInfo 的泛型版本時，cchData 可以安全地指定為 sizeof（LOCALESIGNATURE） / sizeof（TCHAR）。

下列範例會正確處理非文字值的緩衝區大小：

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

此函式 ANSI 版本所擷取的 ANSI 字串會根據地區設定標識符的預設 ANSI 代碼頁，從 Unicode 轉譯為 ANSI。不過，如果指定 LOCALE_USE_CP_ACP，翻譯會以系統預設 ANSI 代碼頁為基礎。

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

注意

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

要求

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