共用方式為


GetLocaleInfoEx 函式 (winnls.h)

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

注意 如果設計為只在 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_ILANGUAGELOCALE_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

另請參閱

GetLocaleInfo

GetSystemDefaultLocaleName

GetUserDefaultLocaleName

國家語言支援

國家語言支援函式

擷取和設定地區設定資訊

SetLocaleInfo