GetUserPreferredUILanguages function (winnls.h)

Article
10/13/2021

Retrieves information about the display language setting. For more information, see User Interface Language Management.

Syntax

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

Parameters

[in] dwFlags

Flags identifying language format and filtering. The following flags specify the language format to use for the display language list. The flags are mutually exclusive, and the default is MUI_LANGUAGE_NAME.

Value	Meaning
MUI_LANGUAGE_ID	Retrieve the language strings in language identifier
MUI_LANGUAGE_NAME	Retrieve the language strings in language name format.

[out] pulNumLanguages

Pointer to the number of languages retrieved in pwszLanguagesBuffer.

[out, optional] pwszLanguagesBuffer

Optional. Pointer to a buffer in which this function retrieves an ordered, null-delimited display language list, in the format specified by dwflags. This list ends with two null characters.

Alternatively if this parameter is set to NULL and pcchLanguagesBuffer is set to 0, the function retrieves the required size of the language buffer in pcchLanguagesBuffer. The required size includes the two null characters.

[in, out] pcchLanguagesBuffer

Pointer to the size, in characters, for the language buffer indicated by pwszLanguagesBuffer. On successful return from the function, the parameter contains the size of the retrieved language buffer.

Alternatively if this parameter is set to 0 and pwszLanguagesBuffer is set to NULL, the function retrieves the required size of the language buffer in pcchLanguagesBuffer.

Return value

Returns TRUE if successful or FALSE otherwise. To get extended error information, the application can call GetLastError function, which can return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.

If the function fails for any other reason, the values of pulNumLanguages and pcchLanguagesBuffer are undefined.

Remarks

When MUI_LANGUAGE_ID is specified, the language strings retrieved will be hexadecimal language identifiers that do not include the leading 0x, and will be 4 characters in length. For example, en-US will be returned as "0409" and en as "0009".

The display language cannot include more than one Language Interface Pack (LIP) language that corresponds to a supplemental locale. If the list includes more than one of these languages, and if the application specifies MUI_LANGUAGE_ID in the call to the function, the language buffer contains "1400" for that language. This string corresponds to the hexadecimal value of LOCALE_CUSTOM_UI_DEFAULT.

The language list retrieved by this function has the following characteristics:

Each language represents a valid NLS locale.
Each language is installed on the operating system.
The list contains one entry for each language, with no duplicate entries.
If the list is empty or does not meet these validation criteria, the system preferred UI languages list is used instead.

C# Signature

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

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	winnls.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

Share via