GetLocaleInfoEx 函式 (winnls.h)

發行項
03/13/2024

擷取名稱所指定地區設定的相關信息。

注意如果設計為只在 Windows Vista 和更新版本上執行，應用程式應該優先呼叫此函式給 GetLocaleInfo 。

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

語法

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

參數

[in, optional] lpLocaleName

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

[in] LCType

要擷取的地區設定資訊。 For possible values, see the "Constants Used in the LCType Parameter of GetLocaleInfo, GetLocaleInfoEx, and SetLocaleInfo" section in Locale Information Constants. 請注意，每個呼叫只能指定一個地區設定資訊。

應用程式可以使用二進位 OR 運算元，將 LOCALE_RETURN_NUMBER 與其他允許的常數結合。在此情況下，函式會將值擷取為數位，而不是字串。接收值的緩衝區必須至少是 DWORD 值的長度，也就是 2。

謹慎您也可以將 LOCALE_NOUSEROVERRIDE 與其他任何常數結合。不過，強烈建議不要使用此常數。 (即使不使用目前的使用者覆寫，數據可能不同於計算機到計算機，而自定義地區設定可以變更數據。例如，偶數月或日名稱會受限於拼字重寫 reforms.)

如果 LCType 設定為 LOCALE_IOPTIONALCALENDAR，則函式只會擷取第一個替代行事曆。

注意若要取得所有替代的行事曆，應用程式應該使用 EnumCalendarInfoEx。

從 Windows Vista 開始，您的應用程式不應該在 LCType 參數中使用LOCALE_ILANGUAGE，以避免發生非預期的數據失敗或擷取。相反地，建議您讓應用程式呼叫 GetLocaleInfoEx。

[out, optional] lpLCData

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

[in] cchData

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

傳回值

如果成功且 cchData 為非零值，則會傳回地區設定數據緩衝區中擷取的字元數。如果函式成功， cchData 是非零值，而且指定LOCALE_RETURN_NUMBER ，則傳回值是數據緩衝區中擷取的整數大小，也就是 2。如果函式成功，且 cchData 的值為 0，則傳回值會是地區設定數據緩衝區的必要大小，以包含 Null 字元的字元為單位。

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

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

備註

此函式通常會以文字格式擷取資訊。如果資訊是數值，且 LCType 的值是LOCALE_ILANGUAGE 或 LOCALE_IDEFAULTLANGUAGE，則此函式會擷取包含十六進位數位的字串。否則，數值資訊的擷取文字是十進位數。

這項規則有兩個例外。首先，應用程式可以在 LCType 參數中指定LOCALE_RETURN_NUMBER，以整數的形式擷取數值。第二個例外狀況是 LOCALE_FONTSIGNATURE 與所有其他地區設定資訊常數的行為不同。應用程式必須至少提供大小為 (LOCALESIGNATURE) 位元組的數據緩衝區。從函式成功傳回時，緩衝區會填入為 LOCALESIGNATURE 結構。

注意即使 LCType 參數指定為 LOCALE_FONTSIGNATURE，cchData 和函式傳回仍是字元計數。當應用程式呼叫指定為 LOCALE_FONTSIGNATURE 的 LCType的 GetLocaleInfoEx 時，cchData 可以安全地指定為 sizeof (LOCALESIGNATURE) / sizeof (WCHAR) 。

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

此函式可以從自定義地區設定擷取數據。數據不保證從計算機到計算機或在應用程式執行之間相同。如果您的應用程式必須保存或傳輸數據，請參閱使用持續性地區設定數據。

從 Windows 8 開始：如果您的 app 從 Windows.Globalization 命名空間將語言標記傳遞至此函式，則必須先呼叫 ResolveLocaleName 來轉換標記。

範例

此函式的使用範例可在 NLS：名稱型 API 範例和 NLS：國際化功能變數名稱 (IDN) 風險降低範例中找到。

規格需求

需求	值
最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll