getSystemPreferredUILanguages 函式 (winnls.h)

發行項
08/27/2023

擷取系統慣用的 UI 語言。如需詳細資訊，請參閱使用者介面語言管理。

語法

BOOL GetSystemPreferredUILanguages(
  [in]            DWORD   dwFlags,
  [out]           PULONG  pulNumLanguages,
  [out, optional] PZZWSTR pwszLanguagesBuffer,
  [in, out]       PULONG  pcchLanguagesBuffer
);

參數

[in] dwFlags

識別語言格式和篩選的旗標。下列旗標會指定要用於系統慣用 UI 語言的格式。旗標互斥，預設值為 MUI_LANGUAGE_NAME。

值	意義
MUI_LANGUAGE_ID	擷取語言識別項格式的語言字串。
MUI_LANGUAGE_NAME	擷取語言名稱格式的語言字串。

下列旗標會指定函式是要驗證預設語言清單 (預設) ，還是擷取系統慣用 UI 語言清單，就像儲存在登錄中一樣。

值	意義
MUI_MACHINE_LANGUAGE_SETTINGS	擷取預存系統慣用 UI 語言清單，只檢查以確保每個語言名稱都對應至有效的 NLS 地區設定。如果未設定此旗標，則函式會擷取 pwszLanguagesBuffer中的系統慣用 UI 語言，只要清單不是空白且符合驗證準則。否則，函式會擷取語言緩衝區中的系統預設使用者介面語言。

[out] pulNumLanguages

pwszLanguagesBuffer中所擷取之語言數目的指標。

[out, optional] pwszLanguagesBuffer

選擇性。緩衝區的指標，此函式會擷取 dwFlags所指定格式的已排序、以 Null 分隔的系統慣用 UI 語言清單。此清單結尾為兩個 Null 字元。

或者，如果此參數設定為 Null ， 而 pcchLanguagesBuffer 設定為 0，函式會在 pcchLanguagesBuffer中擷取語言緩衝區的必要大小。所需的大小包含兩個 Null 字元

[in, out] pcchLanguagesBuffer

pwszLanguagesBuffer所指示之語言緩衝區的大小指標，以字元為單位。從函式成功傳回時，參數會包含所擷取語言緩衝區的大小。

或者，如果此參數設定為 0， 而 pwszLanguagesBuffer 設為 Null，函式會在 pcchLanguagesBuffer中擷取語言緩衝區的必要大小。

傳回值

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

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 Null不正確。

如果函式因任何其他原因而失敗，則未定義 pulNumLanguages 和 pcchLanguagesBuffer 參數 。

備註

指定MUI_LANGUAGE_ID時，擷取的語言字串將會是十六進位語言識別項

不包含前置 0x，且長度為 4 個字元。例如，將會傳回 en-US

為「0409」，en 為「0009」。

系統慣用的 UI 語言不能包含一個以上的語言介面套件， (LIP) 語言對應至補充地區設定。如果清單包含其中一個以上的語言，而且應用程式在呼叫函式時指定MUI_LANGUAGE_ID，語言緩衝區就會包含該語言的「1400」。此字串會對應至 LOCALE_CUSTOM_UI_DEFAULT的十六進位值。

如果已設定MUI_MACHINE_LANGUAGE_SETTINGS旗標，此函式會檢查清單中代表有效 NLS 地區設定的每個語言。擷取的清單可以包含下列專案：

系統未安裝的語言
重複的語言專案
空字串

如果已設定MUI_MACHINE_LANGUAGE_SETTINGS旗標，而且系統慣用的 UI 語言清單是空的，則函式會擷取語言緩衝區中的空字串， (兩個 Null 字元，因為它是多字串緩衝區) ，0 表示語言數目，而緩衝區大小為 2。

如果未設定MUI_MACHINE_LANGUAGE_SETTINGS旗標，擷取的語言清單具有下列特性：

每個語言都代表有效的 NLS 地區設定。
每種語言都會安裝在作業系統上。
此清單包含每個語言的一個專案，沒有重複的專案。

C# 簽章

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetSystemPreferredUILanguages(
            System.UInt32 dwFlags,
            ref System.UInt32 pulNumLanguages,
            System.IntPtr pwszLanguagesBuffer,
            ref System.UInt32 pcchLanguagesBuffer
            );

規格需求


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