Функция GetThreadPreferredUILanguages (winnls.h)

Статья
08/27/2023

Извлекает предпочитаемые языки пользовательского интерфейса потока для текущего потока. Дополнительные сведения см. в разделе Управление языком пользовательского интерфейса.

Синтаксис

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

Параметры

[in] dwFlags

Флаги, определяющие языковой формат и фильтрацию. Следующие флаги определяют формат языка, который будет использоваться для предпочитаемых языков пользовательского интерфейса потока. Флаги являются взаимоисключающими, а значение по умолчанию — MUI_LANGUAGE_NAME.

Значение	Значение
MUI_LANGUAGE_ID	Получение строк языка в формате идентификатора языка .
MUI_LANGUAGE_NAME	Получение строк языка в формате имени языка .

Следующие флаги определяют фильтрацию для функции, используемой при извлечении предпочтительных языков пользовательского интерфейса потока. Флаг по умолчанию — MUI_MERGE_USER_FALLBACK.

Значение	Значение
MUI_MERGE_SYSTEM_FALLBACK	Используйте системный резервный вариант, чтобы получить список, который точно соответствует списку языков, используемому загрузчиком ресурсов. Этот флаг можно использовать только в сочетании с MUI_MERGE_USER_FALLBACK. Использование флагов в сочетании изменяет обычный эффект MUI_MERGE_USER_FALLBACK путем включения в список резервных и нейтральных языков.
MUI_MERGE_USER_FALLBACK	Получение составного списка, состоящего из предпочитаемых в потоке языков пользовательского интерфейса, за которым следуют предпочитаемые для процесса языки пользовательского интерфейса, а затем все языки пользовательского интерфейса, которые отличаются от них, а затем язык пользовательского интерфейса по умолчанию системы, если он еще не включен в список. Если список предпочитаемых пользователем языков пользовательского интерфейса пуст, функция извлекает предпочитаемые системой языки пользовательского интерфейса. Этот флаг нельзя сочетать с MUI_THREAD_LANGUAGES.
MUI_THREAD_LANGUAGES	Получение только предпочитаемых языков пользовательского интерфейса потока для текущего потока или пустого списка, если для текущего потока не заданы предпочитаемые языки. Этот флаг нельзя сочетать с MUI_MERGE_USER_FALLBACK или MUI_MERGE_SYSTEM_FALLBACK.
MUI_UI_FALLBACK	Получение полного списка предпочитаемых языков пользовательского интерфейса потока вместе со связанными резервными и нейтральными языками. Использование этого флага эквивалентно объединению MUI_MERGE_SYSTEM_FALLBACK и MUI_MERGE_USER_FALLBACK. (Применимо только для Windows 7 и более поздних версий).

[out] pulNumLanguages

Указатель на количество языков, полученных в pwszLanguagesBuffer.

[out, optional] pwszLanguagesBuffer

Необязательный элемент. Указатель на буфер, в котором эта функция извлекает упорядоченный список языков пользовательского интерфейса с разделителями NULL потоками в формате, определенном dwFlags. Этот список заканчивается двумя символами NULL.

Кроме того, если для этого параметра задано значение NULL , а для pcchLanguagesBuffer задано значение 0, функция извлекает требуемый размер буфера языка в pcchLanguagesBuffer. Требуемый размер включает два символа NULL.

[in, out] pcchLanguagesBuffer

Указатель на размер (в символах) для буфера языка, указанного pwszLanguagesBuffer. При успешном возвращении из функции параметр содержит размер извлеченного языкового буфера.

Кроме того, если для этого параметра задано значение 0, а для pwszLanguagesBuffer задано значение NULL, функция получает требуемый размер буфера языка в pcchLanguagesBuffer.

Возвращаемое значение

Возвращает значение TRUE в случае успешного выполнения или false в противном случае. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который возвращает один из следующих кодов ошибок:

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.

Если функция завершается сбоем по какой-либо другой причине, параметры pulNumLanguages и pcchLanguagesBuffer не определены.

В зависимости от флагов, заданных приложением, эта функция может получить составной список, состоящий из предпочитаемых в потоке языков пользовательского интерфейса, обработать предпочитаемые языки пользовательского интерфейса, предпочитаемые пользователем языки пользовательского интерфейса или системные языки пользовательского интерфейса, а также язык пользовательского интерфейса системы по умолчанию. Если встречается повторяющийся язык, функция извлекает только первый язык.

Если приложение вызывает SetThreadPreferredUILanguages с флагом MUI_CONSOLE_FILTER или MUI_COMPLEX_SCRIPT_FILTER, GetThreadPreferredUILanguages фильтрует языки в списке результатов. Функция заменяет языки, которые не могут отображаться в консоли, замещающим языком. Подстановка языка определяется на основе значения LOCALE_SCONSOLEFALLBACKNAME для языка. Дополнительные сведения о консоли см. в описании SetThreadUILanguage.

Рекомендуется использовать MUI_LANGUAGE_NAME по сравнению с MUI_LANGUAGE_ID, так как флаг MUI_LANGUAGE_NAME может улучшить работу с языками пакета интерфейса пользователя (LIP), соответствующим дополнительным языковым стандартом.

При указании MUI_LANGUAGE_ID извлекаемой строкой языка будут шестнадцатеричные идентификаторы языка.

не включают в себя 0x в начале и будут содержать 4 символа. Например, возвращается en-US

как "0409" и en как "0009".

Если приложение устанавливает флаг MUI_LANGUAGE_ID, предпочитаемые в потоке языки пользовательского интерфейса могут включать один или несколько языков, соответствующих дополнительным языковым параметрам. При успешном возвращении из функции буфер языка содержит "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
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll