getThreadPreferredUILanguages 函数 (winnls.h)

  • 项目

检索当前线程的线程首选 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

可选。 指向缓冲区的指针，在此缓冲区中，此函数以 dwFlags 指定的格式检索有序的、以 null 分隔的线程首选 UI 语言列表。 此列表以两个空字符结尾。

或者，如果此参数设置为 NULL 且 pcchLanguagesBuffer 设置为 0，则该函数在 pcchLanguagesBuffer 中检索语言缓冲区的所需大小。 所需大小包括两个 null 字符。

[in, out] pcchLanguagesBuffer

指向 pwszLanguagesBuffer 指示的语言缓冲区的大小（以字符为单位）的指针。 从函数成功返回后， 参数包含检索到的语言缓冲区的大小。

或者，如果将此参数设置为 0 并且 pwszLanguagesBuffer 设置为 NULL，则该函数在 pcchLanguagesBuffer 中检索语言缓冲区的所需大小。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。 若要获取扩展的错误信息，应用程序可以调用 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_ID上使用MUI_LANGUAGE_NAME，因为MUI_LANGUAGE_NAME标志可以更好地处理语言接口包 (LIP) 与补充区域设置对应的语言。

指定MUI_LANGUAGE_ID时，检索到的语言字符串将是十六进制语言标识符

不包括前导 0x 且长度为 4 个字符的 。 例如，将返回 en-US

为“0409”，en 为“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)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

GetThreadUILanguage

多语言用户界面

多语言用户界面函数

SetThreadPreferredUILanguages

SetThreadUILanguage