GetThreadPreferredUILanguages 函式 (winnls.h)

發行項
08/27/2023

擷取目前線程的執行緒慣用 UI 語言。如需詳細資訊，請參閱使用者介面語言管理。

語法

BOOL GetThreadPreferredUILanguages(
  [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_MERGE_USER_FALLBACK。

值	意義
MUI_MERGE_SYSTEM_FALLBACK	使用系統後援來擷取對應至資源載入器所使用的語言清單。此旗標只能與MUI_MERGE_USER_FALLBACK搭配使用。結合使用旗標可藉由在清單中加入後援和中性語言，來改變MUI_MERGE_USER_FALLBACK的一般效果。
MUI_MERGE_USER_FALLBACK	擷取複合清單，其中包含執行緒慣用 UI 語言，後面接著程式慣用 UI 語言，後面接著與這些語言不同的使用者慣用 UI 語言，如果清單中還沒使用，則擷取包含系統預設 UI 語言的複合清單。如果使用者慣用的 UI 語言清單是空的，函式會擷取系統慣用的 UI 語言。此旗標無法與MUI_THREAD_LANGUAGES結合。
MUI_THREAD_LANGUAGES	只擷取目前線程的執行緒慣用 UI 語言，如果沒有針對目前線程設定慣用的語言，則擷取空白清單。此旗標無法與MUI_MERGE_USER_FALLBACK或MUI_MERGE_SYSTEM_FALLBACK結合。
MUI_UI_FALLBACK	擷取完整的執行緒慣用 UI 語言清單，以及相關聯的後援和中性語言。使用此旗標相當於合併MUI_MERGE_SYSTEM_FALLBACK和MUI_MERGE_USER_FALLBACK。 (僅適用于 Windows 7 和更新版本) 。

[out] pulNumLanguages

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

[out, optional] pwszLanguagesBuffer

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

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

[in, out] pcchLanguagesBuffer

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

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

傳回值

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

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

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

備註

根據應用程式指定的旗標，此函式可以擷取複合清單，其中包含執行緒慣用 UI 語言、處理慣用 UI 語言、使用者慣用 UI 語言或系統慣用 UI 語言，以及系統預設 UI 語言。如果遇到重複的語言，函式只會擷取第一種語言。

如果應用程式已使用 MUI_CONSOLE_FILTER 或 MUI_COMPLEX_SCRIPT_FILTER 旗標呼叫 SetThreadPreferredUILanguages ， GetThreadPreferredUILanguages 會篩選結果清單中的語言。函式會取代主控台無法以替代語言顯示的語言。語言的替代是由語言的 LOCALE_SCONSOLEFALLBACKNAME 值所決定。如需詳細資訊，請參閱 SetThreadUILanguage的描述。

建議使用MUI_LANGUAGE_NAME而非MUI_LANGUAGE_ID，因為MUI_LANGUAGE_NAME旗標可以更妥善地處理對應至補充地區設定的語言介面套件 (LIP) 語言。

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

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

as 「0409」 and en as 「0009」。

如果應用程式設定MUI_LANGUAGE_ID旗標，執行緒慣用 UI 語言可以包含一或多個對應至補充地區設定的語言。從函式成功傳回時，語言緩衝區會針對對應至補充地區設定的任何語言包含「1400」。此清單中只能有一種這類語言。字串「1400」會對應至 LOCALE_CUSTOM_UI_DEFAULT的十六進位值。此外，從函式成功傳回時， pwszLanguagesBuffer 包含任何其他對應至補充地區設定的語言「1000」。字串「1000」會對應至 LOCALE_CUSTOM_UNSPECIFIED的十六進位值，因為無法區分補充地區設定，因此無法區分任何函式的輸入。

C# 簽章

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetThreadPreferredUILanguages(
            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