GetLocaleInfoEx 함수(winnls.h)

아티클
03/13/2024

이름으로 지정된 로캘에 대한 정보를 검색합니다.

참고 애플리케이션은 Windows Vista 이상에서만 실행되도록 설계된 경우 GetLocaleInfo 에 대한 기본 설정으로 이 함수를 호출해야 합니다.

참고 이 함수는 예를 들어 사용자 지정 로캘로 인해 릴리스 간에 변경되는 데이터를 검색할 수 있습니다. 애플리케이션이 데이터를 유지하거나 전송해야 하는 경우 영구 로캘 데이터 사용을 참조하세요.

구문

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

매개 변수

[in, optional] lpLocaleName

로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.

[in] LCType

검색할 로캘 정보입니다. 가능한 값은 로캘 정보 상수의 "GetLocaleInfo, GetLocaleInfoEx 및 SetLocaleInfo의 LCType 매개 변수에 사용된 상수" 섹션을 참조하세요. 호출당 하나의 로캘 정보만 지정할 수 있습니다.

애플리케이션은 이진 OR 연산자를 사용하여 LOCALE_RETURN_NUMBER 허용되는 다른 상수와 결합할 수 있습니다. 이 경우 함수는 값을 문자열 대신 숫자로 검색합니다. 값을 받는 버퍼는 DWORD 값의 길이(2)여야 합니다.

주의LOCALE_NOUSEROVERRIDE 다른 상수와 결합할 수도 있습니다. 그러나 이 상수를 사용하는 것은 권장되지 않습니다. (현재 사용자 재정의를 사용하지 않더라도 데이터는 컴퓨터마다 다를 수 있으며 사용자 지정 로캘은 데이터를 변경할 수 있습니다. 예를 들어 월 또는 일 이름에도 맞춤법 개혁이 적용됩니다.)

LCType이 LOCALE_IOPTIONALCALENDAR 설정되면 함수는 첫 번째 대체 달력만 검색합니다.

참고 모든 대체 일정을 얻으려면 애플리케이션에서 EnumCalendarInfoEx를 사용해야 합니다.

Windows Vista부터 애플리케이션은 LCType 매개 변수의 LOCALE_ILANGUAGE 사용하여 예기치 않은 데이터의 오류 또는 검색을 방지해서는 안 됩니다. 대신 애플리케이션에서 GetLocaleInfoEx를 호출하는 것이 좋습니다.

[out, optional] lpLCData

이 함수가 요청된 로캘 정보를 검색하는 버퍼에 대한 포인터입니다. cchData가 0으로 설정된 경우 이 포인터는 사용되지 않습니다.

[in] cchData

lpLCData로 표시된 데이터 버퍼의 크기(문자)입니다. 또는 애플리케이션에서 이 매개 변수를 0으로 설정할 수 있습니다. 이 경우 함수는 lpLCData 매개 변수를 사용하지 않고 종료 null 문자를 포함하여 필요한 버퍼 크기를 반환합니다.

반환 값

성공하면 로캘 데이터 버퍼에서 검색된 문자 수를 반환하고 cchData 는 0이 아닌 값입니다. 함수가 성공하면 cchData 가 0이 아니고 LOCALE_RETURN_NUMBER 지정되면 반환 값은 데이터 버퍼에서 검색된 정수의 크기(즉, 2)입니다. 함수가 성공하고 cchData 값이 0이면 반환 값은 로캘 데이터 버퍼에 대해 null 문자를 포함한 문자의 필수 크기입니다.

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

ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.
ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.

설명

이 함수는 일반적으로 텍스트 형식으로 정보를 검색합니다. 정보가 숫자 값이고 LCType 값이 LOCALE_ILANGUAGE 또는 LOCALE_IDEFAULTLANGUAGE 경우 이 함수는 16진수가 포함된 문자열을 검색합니다. 그렇지 않으면 숫자 정보에 대해 검색된 텍스트가 10진수입니다.

이 규칙에는 두 가지 예외 사항이 있습니다. 먼저 애플리케이션은 LCType 매개 변수에 LOCALE_RETURN_NUMBER 지정하여 숫자 값을 정수로 검색할 수 있습니다. 두 번째 예외는 LOCALE_FONTSIGNATURE 다른 모든 로캘 정보 상수와 다르게 동작한다는 것입니다. 애플리케이션은 적어도 sizeof(LOCALESIGNATURE) 바이트의 데이터 버퍼를 제공해야 합니다. 함수에서 성공적으로 반환되면 버퍼가 LOCALESIGNATURE 구조체로 채워집니다.

참고LCType 매개 변수가 LOCALE_FONTSIGNATURE 지정된 경우에도 cchData 및 함수 반환은 여전히 문자 수입니다. 애플리케이션이 LOCALE_FONTSIGNATURE 지정된 LCType을 사용하여 GetLocaleInfoEx를 호출하는 경우 cchData를 sizeof(LOCALESIGNATURE) / sizeof(WCHAR)로 안전하게 지정할 수 있습니다.

다음 예제에서는 텍스트가 아닌 값의 버퍼 크기를 올바르게 처리합니다.

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

이 함수는 사용자 지정 로캘에서 데이터를 검색할 수 있습니다. 데이터가 컴퓨터에서 컴퓨터로 또는 애플리케이션 실행 간에 동일하지는 않습니다. 애플리케이션이 데이터를 유지하거나 전송해야 하는 경우 영구 로캘 데이터 사용을 참조하세요.

Windows 8 시작: 앱이Windows.Globalization 네임스페이스에서 이 함수에 언어 태그를 전달하는 경우 먼저 ResolveLocaleName을 호출하여 태그를 변환해야 합니다.

예제

이 함수의 사용을 보여 주는 예제는 NLS: 이름 기반 API 샘플 및 NLS: IDN(Internationalized Domain Name) 완화 샘플에서 찾을 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winnls.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll