GetThreadPreferredUILanguages 함수(winnls.h)

아티클
03/08/2023

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

구문

BOOL GetThreadPreferredUILanguages(
  [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_MERGE_USER_FALLBACK.

값	의미
MUI_MERGE_SYSTEM_FALLBACK	시스템 대체를 사용하여 리소스 로더에서 사용하는 언어 목록에 정확히 해당하는 목록을 검색합니다. 이 플래그는 MUI_MERGE_USER_FALLBACK 함께 사용할 수 있습니다. 플래그를 조합하여 사용하면 대체 및 중립 언어를 목록에 포함시켜 MUI_MERGE_USER_FALLBACK 일반적인 효과를 변경합니다.
MUI_MERGE_USER_FALLBACK	스레드 기본 설정 UI 언어로 구성된 복합 목록과 프로세스 기본 설정 UI 언어로 구성된 복합 목록을 검색한 다음, 해당 언어와 구별되는 사용자 기본 UI 언어와 시스템 기본 UI 언어(아직 목록에 없는 경우)를 검색합니다. 사용자가 선호하는 UI 언어 목록이 비어 있으면 함수는 시스템 기본 설정 UI 언어를 검색합니다. 이 플래그는 MUI_THREAD_LANGUAGES 함께 사용할 수 없습니다.
MUI_THREAD_LANGUAGES	현재 스레드에 대한 스레드 기본 설정 UI 언어만 검색하거나 현재 스레드에 대해 기본 설정 언어가 설정되지 않은 경우 빈 목록을 검색합니다. 이 플래그는 MUI_MERGE_USER_FALLBACK 또는 MUI_MERGE_SYSTEM_FALLBACK 결합할 수 없습니다.
MUI_UI_FALLBACK	연결된 대체 및 중립 언어와 함께 전체 스레드 기본 설정 UI 언어 목록을 검색합니다. 이 플래그의 사용은 MUI_MERGE_SYSTEM_FALLBACK MUI_MERGE_USER_FALLBACK 결합하는 것과 같습니다. (Windows 7 이상에만 적용됨).

[out] pulNumLanguages

pwszLanguagesBuffer에서 검색된 언어 수에 대한 포인터입니다.

[out, optional] pwszLanguagesBuffer

선택 사항입니다. 이 함수가 dwFlags로 지정된 형식으로 정렬된 null로 구분된 스레드 기본 설정 UI 언어 목록을 검색하는 버퍼에 대한 포인터입니다. 이 목록은 두 개의 null 문자로 끝납니다.

또는 이 매개 변수가 NULL 로 설정되고 pcchLanguagesBuffer 가 0으로 설정된 경우 함수는 pcchLanguagesBuffer에서 필요한 언어 버퍼 크기를 검색합니다. 필요한 크기에는 두 개의 null 문자가 포함됩니다.

[in, out] pcchLanguagesBuffer

pwszLanguagesBuffer로 표시된 언어 버퍼의 크기(문자)에 대한 포인터입니다. 함수에서 성공적으로 반환되면 매개 변수에 검색된 언어 버퍼의 크기가 포함됩니다.

또는 이 매개 변수가 0으로 설정되고 pwszLanguagesBuffer 가 NULL로 설정된 경우 함수는 pcchLanguagesBuffer에서 필요한 언어 버퍼 크기를 검색합니다.

반환 값

성공하면 TRUE를 반환하고 그렇지 않으면 FALSE를 반환합니다. 확장된 오류 정보를 가져오기 위해 애플리케이션은 GetLastError를 호출할 수 있습니다. 이 오류 코드는 다음 오류 코드 중 하나를 반환합니다.

ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.

다른 이유로 인해 함수가 실패하면 pulNumLanguages 및 pcchLanguagesBuffer 매개 변수가 정의되지 않습니다.

설명

애플리케이션에서 지정한 플래그에 따라 이 함수는 스레드 기본 설정 UI 언어, 프로세스 기본 설정 UI 언어, 사용자 기본 UI 언어 또는 시스템 기본 UI 언어 및 시스템 기본 UI 언어로 구성된 복합 목록을 검색할 수 있습니다. 중복 언어가 발견되면 함수는 첫 번째 언어만 검색합니다.

애플리케이션이 MUI_CONSOLE_FILTER 또는 MUI_COMPLEX_SCRIPT_FILTER 플래그를 사용하여 SetThreadPreferredUILanguages 를 호출한 경우 GetThreadPreferredUILanguages 는 결과 목록의 언어를 필터링합니다. 함수는 콘솔에서 표시할 수 없는 언어를 대체 언어로 바꿉니다. 언어의 대체는 언어에 대한 LOCALE_SCONSOLEFALLBACKNAME 값에서 결정됩니다. 자세한 콘솔 정보는 SetThreadUILanguage에 대한 설명을 참조하세요.

MUI_LANGUAGE_NAME 플래그가 추가 로캘에 해당하는 LIP(언어 인터페이스 팩) 언어를 더 잘 처리할 수 있으므로 MUI_LANGUAGE_ID MUI_LANGUAGE_NAME 사용하는 것이 좋습니다.

MUI_LANGUAGE_ID 지정하면 검색된 언어 문자열은 16진수 언어 식별자가 됩니다.

앞에 오는 0x를 포함하지 않으며 길이는 4자입니다. 예를 들어 en-US가 반환됩니다.

"0409"로, en을 "0009"로 지정합니다.

애플리케이션이 MUI_LANGUAGE_ID 플래그를 설정하는 경우 스레드 기본 설정 UI 언어에는 추가 로캘에 해당하는 하나 이상의 언어가 포함될 수 있습니다. 함수에서 성공적으로 반환되면 언어 버퍼에는 추가 로캘에 해당하는 모든 언어에 대해 "1400"이 포함됩니다. 이 목록에는 이러한 언어가 하나만 있을 수 있습니다. 문자열 "1400"은 LOCALE_CUSTOM_UI_DEFAULT 16진수 값에 해당합니다. 또한 함수에서 성공적으로 반환되면 pwszLanguagesBuffer 는 추가 로캘에 해당하는 다른 언어에 대해 "1000"을 포함합니다. 문자열 "1000"은 LOCALE_CUSTOM_UNSPECIFIED 16진수 값에 해당하며, 추가 로캘을 구분할 수 없으므로 함수에 대한 입력으로는 유용하지 않습니다.

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
헤더	winnls.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll