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

Статья
08/27/2023

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

Примечание Эта функция также используется операционной системой для определения языков, которые являются безопасными для использования в консоли Windows.

Синтаксис

BOOL SetThreadPreferredUILanguages(
  [in]            DWORD    dwFlags,
  [in, optional]  PCZZWSTR pwszLanguagesBuffer,
  [out, optional] PULONG   pulNumLanguages
);

Параметры

[in] dwFlags

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

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

Вместо MUI_LANGUAGE_ID рекомендуется использовать MUI_LANGUAGE_NAME.

Значение	Значение
MUI_LANGUAGE_ID	Строки языка входного параметра имеют формат идентификатора языка .
MUI_LANGUAGE_NAME	Строки языка входных параметров имеют формат имени языка .

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

Значение	Значение
MUI_COMPLEX_SCRIPT_FILTER	GetThreadPreferredUILanguages должны заменить соответствующим резервным вариантом все языки со сложными скриптами. Если этот флаг указан, необходимо передать значение NULL для всех остальных параметров.
MUI_CONSOLE_FILTER	GetThreadPreferredUILanguages должны заменить соответствующим резервным вариантом все языки, которые не могут правильно отображаться в окне консоли с текущими параметрами операционной системы. Если этот флаг указан, необходимо передать значение NULL для всех остальных параметров.
MUI_RESET_FILTERS	Сбросьте фильтрацию для списка языков, удалив все другие параметры фильтра. Если этот флаг указан, необходимо передать значение NULL для всех остальных параметров. После установки этого флага приложение может вызвать Метод GetThreadPreferredUILanguages , чтобы получить полный нефильтрованный список.

[in, optional] pwszLanguagesBuffer

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

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

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

[out, optional] pulNumLanguages

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

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

Возвращает значение TRUE , если функция выполнена успешно, или false в противном случае.

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

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

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

передается как "0409" и en как "0009".

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

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

После возврата этой функции приложение может вызвать Метод GetThreadPreferredUILanguages для проверки и просмотра итогового списка языков. Если MUI_CONSOLE_FILTER или MUI_COMPLEX_FILTER задано командлетом SetThreadPreferredUILanguages, функция GetThreadPreferredUILanguages заменяет резервными языками, которые консоль не может отобразить с помощью текущего параметра языка операционной системы. Резервный вариант для языка определяется на основе значения LOCALE_SCONSOLEFALLBACKNAME для языка.

Установка флага MUI_COMPLEX_SCRIPT_FILTER в вызове SetThreadPreferredUILanguages приводит к тому, что getThreadPreferredUILanguages удаляет языки, которые консоль не может отображать с языками, которые можно отрисовывать только с помощью Uniscribe, и вставляет резервный язык в качестве конечного резервного. Примерами таких языков являются арабский или различные индийские языки.

Установка флага MUI_CONSOLE_FILTER в вызове SetThreadPreferredUILanguages приводит к тому, что getThreadPreferredUILanguages удаляет языки, которые консоль не может отображать с текущим системным параметром, и вставляет резервный язык в качестве конечного резервного, так как консоль ограничена отображением символов из одной кодовой страницы. Например, если пользовательский язык — японский (Япония), а текущая кодовая страница консоли — кодовая страница для русского языка (Россия), в консоли текст на японском языке отображается в основном как ряд символов, не найденных. GetThreadPreferredUILanguages выбирает язык из резервного списка, который будет читаемым в консоли.

Примечание Функции загрузки ресурсов, такие как LoadString, LoadImage и FindResource, также выполняют вызовы GetThreadPreferredUILanguages.

Чтобы изменить кодовую страницу, приложение использует функцию setlocale или эквивалентную.

Подпись C#

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll