GetLocaleInfoA 函式 (winnls.h)

發行項
08/27/2023

擷取識別碼所指定地區設定的相關資訊。

注意基於互通性考慮，應用程式應該偏好 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

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

注意針對 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 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll