SetThreadPreferredUILanguages 함수(winnls.h)

아티클
08/27/2023

현재 스레드에 대한 스레드 기본 설정 UI 언어를 설정합니다. 자세한 내용은 사용자 인터페이스 언어 관리를 참조하세요.

참고 이 함수는 운영 체제에서 Windows 콘솔에서 사용하기에 안전한 언어를 식별하는 데도 사용됩니다.

구문

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

매개 변수

[in] dwFlags

설정할 언어의 형식 및 필터링을 식별하는 플래그입니다.

다음 형식 플래그 는 스레드 기본 설정 UI 언어에 사용할 언어 형식을 지정합니다. 플래그는 함께 사용할 수 없으며 기본값은 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

dwFlags에서 지정한 형식으로 정렬된 null로 구분된 목록을 포함하는 이중 null로 끝나는 다중 문자열 버퍼에 대한 포인터입니다.

스레드 기본 설정 UI 언어 목록을 지우기 위해 애플리케이션은 이 매개 변수를 null 문자열 또는 빈 이중 null로 끝나는 문자열로 설정합니다. 애플리케이션에서 언어 목록을 지우는 경우 dwFlags 매개 변수에 대해 형식 플래그 또는 0을 지정해야 합니다.

애플리케이션이 필터링 플래그 중 하나를 지정하는 경우 이 매개 변수를 NULL로 설정해야 합니다. 이 경우 함수는 성공하지만 스레드 기본 설정 언어를 다시 설정하지는 않습니다.

[out, optional] pulNumLanguages

스레드 기본 설정 UI 언어 목록에서 함수가 설정한 언어 수에 대한 포인터입니다. 애플리케이션이 필터링 플래그 중 하나를 지정하는 경우 함수는 이 매개 변수를 NULL로 설정해야 합니다.

반환 값

함수가 성공하면 TRUE 를 반환하고 그렇지 않으면 FALSE를 반환 합니다.

설명

애플리케이션이 이 함수를 호출한 후 리소스를 로드하는 경우 스레드별 기본 설정은 사용자가 선호하는 언어보다 우선합니다.

이 함수는 기본 설정 순서대로 스레드에 대해 최대 5개의 기본 설정 언어를 설정할 수 있습니다. 언어 버퍼에 5개 이상의 유효한 언어가 포함된 경우 함수는 처음 5개의 유효한 언어를 설정하고 나머지는 무시합니다.

애플리케이션이 MUI_LANGUAGE_ID 플래그 집합을 사용하여 이 함수를 호출하는 경우 언어 목록의 문자열은 16진수 언어를 사용해야 합니다.

앞에 오는 0x를 포함하지 않고 길이가 4자인 식별자입니다. 예를 들어 en-US는 여야 합니다.

"0409"로, en을 "0009"로 전달했습니다.

MUI_LANGUAGE_ID 지정하면 언어 목록의 16진수 값이 각각 실제 언어 식별자를 나타내야 합니다. 특히 다음 로캘 식별자 값은 언어 식별자에 해당하는 데 사용할 수 없습니다.

빈 언어 목록을 사용하여 이 함수를 호출하고 MUI_CONSOLE_FILTER 플래그를 설정하면 언어 식별자가 0으로 설정된 SetThreadUILanguage 를 호출하는 것과 동일한 효과가 있습니다. 언어는 콘솔 창에서 사용하기 위해 적절하게 설정됩니다.

이 함수가 반환된 후 애플리케이션은 GetThreadPreferredUILanguages 를 호출하여 결과 언어 목록을 확인하고 검사할 수 있습니다. SetThreadPreferredUILanguages에서 MUI_CONSOLE_FILTER 또는 MUI_COMPLEX_FILTER 설정한 경우 GetThreadPreferredUILanguages 함수는 현재 운영 체제 언어 설정을 사용하여 콘솔에서 표시할 수 없는 언어 대체로 바뀝니다. 언어의 대체는 언어에 대한 LOCALE_SCONSOLEFALLBACKNAME 값에 따라 결정됩니다.

SetThreadPreferredUILanguages 호출에서 MUI_COMPLEX_SCRIPT_FILTER 플래그를 설정하면 GetThreadPreferredUILanguages가 유니스크립트를 사용하여 렌더링할 수 있는 언어로만 콘솔에 표시할 수 없는 언어를 제거하고 대체 언어를 최종 대체 언어로 삽입합니다. 이러한 언어의 예로 아랍어 또는 다양한 인덱스 언어가 있습니다.

SetThreadPreferredUILanguages 호출에서 MUI_CONSOLE_FILTER 플래그를 설정하면 콘솔이 현재 시스템 설정과 함께 표시할 수 없는 언어를 제거하고 대체 언어를 최종 대체 언어로 삽입합니다. 콘솔은 단일 코드 페이지의 문자 표시로 제한되기 때문입니다. 예를 들어 사용자 언어가 일본어(일본)이지만 현재 콘솔 코드 페이지가 러시아어(러시아)의 코드 페이지인 경우 콘솔은 일본어 텍스트를 주로 일련의 문자 없는 기호로 표시합니다. 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
헤더	winnls.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll

참고 항목

GetThreadPreferredUILanguages

다국어 사용자 인터페이스

다국어 사용자 인터페이스 함수

SetThreadUILanguage

다음을 통해 공유