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 且 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 语言列表为空，则该函数在语言缓冲区中检索空字符串 (两个空字符，因为它是多字符串缓冲区) ，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)
Library	Kernel32.lib
DLL	Kernel32.dll