다음을 통해 공유


LCMapStringEx 함수(winnls.h)

이름으로 지정된 로캘의 경우 지정된 변환을 사용하여 입력 문자 문자열을 다른 에 매핑하거나 입력 문자열에 대한 정렬 키를 생성합니다.

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

 

구문

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

매개 변수

[in, optional] lpLocaleName

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

[in] dwMapFlags

문자열 매핑 중에 사용할 변환 유형 또는 생성할 정렬 키의 형식을 지정하는 플래그입니다. 이 매개 변수에는 다음 값이 있을 수 있습니다.

플래그 의미
LCMAP_BYTEREV 바이트 반전을 사용합니다. 예를 들어 애플리케이션이 0x3450 0x4822 통과하면 결과가 0x5034 0x2248.
LCMAP_FULLWIDTH 해당하는 경우 유니코드(와이드) 문자를 사용합니다. 이 플래그와 LCMAP_HALFWIDTH 함께 사용할 수 없습니다. 이 플래그를 사용하면 입력 문자가 이미 전체 너비인 경우에도 매핑에서 정규화 양식 C를 사용할 수 있습니다. 예를 들어 문자열 "は゛"(전자임)는 "ば"로 표준화됩니다. 유니코드 정규화 형식을 참조하세요.
LCMAP_HALFWIDTH 해당하는 경우 좁은 문자를 사용합니다. 이 플래그와 LCMAP_FULLWIDTH 함께 사용할 수 없습니다.
LCMAP_HIRAGANA 모든 가타카나 문자를 히라가나에 매핑합니다. 이 플래그와 LCMAP_KATAKANA 함께 사용할 수 없습니다.
LCMAP_KATAKANA 모든 히라가나 문자를 가타카나에 매핑합니다. 이 플래그와 LCMAP_HIRAGANA 함께 사용할 수 없습니다.
LCMAP_LINGUISTIC_CASING 파일 시스템 규칙(기본값) 대신 대/소문자 구분에 언어 규칙을 사용합니다. 이 플래그는 LCMAP_LOWERCASE 또는 LCMAP_UPPERCASE 경우에만 유효합니다.
LCMAP_LOWERCASE 대문자와 소문자를 처리할 수 있는 로캘 및 스크립트의 경우 모든 문자를 소문자로 매핑합니다.
LCMAP_HASH 문자열의 원시 정렬 가중치 해시를 반환합니다.

동일하게 표시되는 문자열은 일반적으로 동일한 해시(예: "hello" 및 "HELLO"와 LCMAP_IGNORECASE)를 반환합니다. 그러나 동아시아 언어와 같은 일부 복잡한 경우는 동일한 가중치를 가진 유사한 문자열을 가질 수 있지만 동일한 해시를 반환하지는 않습니다.

LCMAP_HASH 출력 버퍼의 sizeof(int)
LCMAP_SIMPLIFIED_CHINESE 중국어 번체 문자를 간소화된 중국어 문자에 매핑합니다. 이 플래그와 LCMAP_TRADITIONAL_CHINESE 함께 사용할 수 없습니다.
LCMAP_SORTHANDLE
정렬 핸들을 사용하면 성능이 최소로 향상되며 권장되지 않습니다.
로캘에 대해 확인된 정렬 매개 변수(예: 로캘 이름)를 나타내는 토큰을 반환하므로 이후 호출은 정렬 이름에 전달 NULL 하고 CompareStringEx 또는 LCMapStringEx에 대한 후속 호출에서 이전에 쿼리한 정렬 핸들을 마지막 매개 변수(sortHandle)로 전달할 수 있습니다.

LCMAP_SORTHANDLE 출력 버퍼의 sizeof(lparam)
LCMAP_SORTKEY 정규화된 정렬 키를 생성합니다. LCMAP_SORTKEY 플래그를 지정하지 않으면 함수는 문자열 매핑을 수행합니다. 정렬 키 생성 및 문자열 매핑에 대한 자세한 내용은 설명 섹션을 참조하세요.
LCMAP_TITLECASE Windows 7: 각 주요 단어의 첫 글자가 대문자로 표시되는 제목 대/소문자에 모든 문자를 매핑합니다.
LCMAP_TRADITIONAL_CHINESE 중국어 간체 문자를 기존 중국어 문자에 매핑합니다. 이 플래그와 LCMAP_SIMPLIFIED_CHINESE 함께 사용할 수 없습니다.
LCMAP_UPPERCASE 대문자와 소문자를 처리할 수 있는 로캘 및 스크립트의 경우 모든 문자를 대문자로 매핑합니다.

다음 플래그는 단독으로, 서로 사용하거나, LCMAP_SORTKEY 및/또는 LCMAP_BYTEREV 플래그와 함께 사용할 수 있습니다. 그러나 위에 나열된 다른 플래그와 결합할 수는 없습니다.

플래그 의미
NORM_IGNORENONSPACE
비스페이스 문자를 무시합니다. 많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORENONSPACE LINGUISTIC_IGNOREDIACRITIC 일치합니다.
참고 NORM_IGNORENONSPACE 분음 부호인지 여부에 관계없이 보조 구분을 무시합니다. 한국어, 일본어, 중국어 및 인덱스 언어에 대한 스크립트는 분음 부호 이외의 용도로 이 구분을 사용합니다. LINGUISTIC_IGNOREDIACRITIC 두 번째 정렬 가중치를 무시하는 대신 함수가 실제 분음 부호만 무시하게 합니다.
 
NORM_IGNORESYMBOLS
기호 및 문장 부호를 무시합니다.
 

아래에 나열된 플래그는 LCMAP_SORTKEY 플래그와 함께만 사용됩니다.

플래그 의미
LINGUISTIC_IGNORECASE
언어적으로 적절한 대/소문자를 무시합니다.
LINGUISTIC_IGNOREDIACRITIC
비스페이스 문자를 언어적으로 적절하게 무시합니다.
참고 이 플래그는 분해된 문자와 함께 사용할 때 항상 예측 가능한 결과를 생성하지는 않습니다. 즉, 기본 문자와 하나 이상의 불투명 문자가 각각 고유한 코드 포인트 값을 갖는 문자입니다.
 
NORM_IGNORECASE
대/소문자를 무시합니다. 많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORECASE LINGUISTIC_IGNORECASE 일치합니다.
참고 NORM_IGNORECASE 실제로 언어적 사례인지 여부에 관계없이 3차 구분을 무시합니다. 예를 들어 아랍어 및 인딕 스크립트에서 이 플래그는 문자의 대체 형식을 구분하지만 차이점은 언어 사례에 해당하지 않습니다. LINGUISTIC_IGNORECASE 함수는 세 번째 정렬 가중치를 무시하는 대신 실제 언어 대/소문자만 무시합니다.
 
참고 DBCS(더블 바이트 문자 집합) 로캘의 경우 NORM_IGNORECASE 모든 유니코드 문자와 그리스어 및 키릴 자모 문자를 포함한 좁은(1 바이트) 문자에 영향을 줍니다.
 
NORM_IGNOREKANATYPE
히라가나와 가타카나 문자를 구분하지 마세요. 해당 히라가나와 가타카나 문자는 같음으로 비교합니다.
NORM_IGNOREWIDTH
반자 문자와 전체 너비 문자(예: C a t == cat)의 차이를 무시합니다. 전체 너비 형식은 중국어 및 일본어 스크립트에서 사용되는 서식 구분입니다.
NORM_LINGUISTIC_CASING
파일 시스템 규칙(기본값) 대신 대/소문자 구분에 언어 규칙을 사용합니다.
SORT_DIGITSASNUMBERS
Windows 7: 정렬하는 동안 숫자를 숫자로 처리합니다. 예를 들어 "10" 앞에 "2"를 정렬합니다.
SORT_STRINGSORT
문장 부호를 기호와 동일하게 처리합니다.

[in] lpSrcStr

함수가 정렬 키 생성을 위해 매핑하거나 사용하는 소스 문자열에 대한 포인터입니다. 이 문자열의 크기는 0일 수 없습니다.

[in] cchSrc

lpSrcStr로 표시된 원본 문자열의 크기(문자)입니다. 원본 문자열의 크기에는 종료 null 문자가 포함될 수 있지만, 그렇지 않아도 됩니다. 종료 null 문자가 포함된 경우 종료 null 문자는 정렬할 수 없는 것으로 간주되고 항상 자체에 매핑되므로 함수의 매핑 동작은 큰 영향을 받지 않습니다.

애플리케이션은 이 매개 변수를 음수 값으로 설정하여 원본 문자열이 null로 종료되도록 지정할 수 있습니다. 이 경우 LCMapStringEx 가 문자열 매핑 모드에서 사용되는 경우 함수는 문자열 길이 자체를 계산하고 lpDestStr로 표시된 매핑된 문자열을 null로 종료합니다.

애플리케이션에서 이 매개 변수를 0으로 설정할 수 없습니다.

[out, optional] lpDestStr

이 함수가 매핑된 문자열 또는 정렬 키를 검색하는 버퍼에 대한 포인터입니다.

애플리케이션이 함수를 사용하여 정렬 키(LCMAP_SORTKEY)를 생성하는 경우:

  • 정렬 키는 버퍼에 저장되고 불투명한 바이트 배열로 처리됩니다. 저장된 값은 임의 위치에 포함된 0바이트를 포함할 수 있습니다.
  • 대상 문자열에는 홀수 바이트 수가 포함될 수 있습니다. LCMAP_BYTEREV 플래그는 짝수 바이트만 역방향으로 설정합니다. 정렬 키의 마지막 바이트(홀수 위치)는 반전되지 않습니다.

호출자가 문자열의 하위 집합을 명시적으로 요청하는 경우 호출자가 cchDest에 지정하지 않는 한 대상 문자열에는 종료 null 문자가 포함되지 않습니다.

이 함수가 실패하면 대상 버퍼에 부분 결과 또는 결과가 전혀 포함되지 않을 수 있습니다. 이 경우 모든 결과가 잘못된 것으로 간주되어야 합니다.

참고

LCMAP_UPPERCASE 또는 LCMAP_LOWERCASE 설정할 때 대상 문자열은 원본 문자열과 동일한 버퍼를 사용할 수 있습니다. 그러나 일부 조건에서는 반환된 대/소문자 문자열의 길이가 다를 수 있으므로 권장되지 않습니다.

[in] cchDest

lpDestStr로 표시된 대상 문자열의 크기(문자)입니다. 애플리케이션에서 문자열 매핑에 함수를 사용하는 경우 이 매개 변수에 대한 문자 수를 제공합니다. 종료 null 문자의 공간이 cchSrc에 포함된 경우 cchDest 는 종료 null 문자에 대한 공간도 포함해야 합니다.

애플리케이션에서 함수를 사용하여 정렬 키를 생성하는 경우 크기에 대한 바이트 수를 제공합니다. 이 바이트 수에는 정렬 키 0x00 종결자에 대한 공간이 포함되어야 합니다.

애플리케이션은 cchDest 를 0으로 설정할 수 있습니다. 이 경우 함수는 lpDestStr 매개 변수를 사용하지 않고 매핑된 문자열 또는 정렬 키에 필요한 버퍼 크기를 반환합니다.

[in, optional] lpVersionInformation

관련 NLS 기능에 대한 버전 정보를 포함하는 NLSVERSIONINFOEX 구조체에 대한 포인터입니다. 일반적으로 GetNLSVersionEx에서 검색됩니다.

Windows Vista, Windows 7: 예약; 은 NULL로 설정해야 합니다.

[in, optional] lpReserved

예약; 은 NULL이어야 합니다.

[in, optional] sortHandle

예약되었습니다. 0이어야 합니다.

참고

CompareStringExLCMapStringEx 는 정렬 핸들을 지정할 수 있습니다(로캘 이름이 null인 경우). 대부분의 앱에서는 이 사용을 권장하지 않습니다.

반환 값

문자열 매핑에 사용할 때 함수가 성공하면 변환된 문자열의 문자 수를 반환합니다(자세한 내용은 cchSrccchDest 참조).

정렬 키를 생성하는 데 사용할 때 함수가 성공하면 정렬 키의 바이트 수를 반환합니다.

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

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

설명

애플리케이션은 LCMapString 또는 LCMapStringEx를 사용하여 정렬 키를 생성할 수 있습니다. 이를 위해 애플리케이션은 dwMapFlags 매개 변수에 대한 LCMAP_SORTKEY 지정합니다. 자세한 내용은 애플리케이션에서 정렬 처리를 참조하세요.

참고

정렬 키는 불투명 바이트 스트림입니다. 호출자는 API에서 반환된 길이의 바이트 배열로 처리해야 하며, 있는 것처럼 보일 수 있는 내부 구조에 의존하지 않아야 합니다. 0, 반환된 정렬 키의 바이트 중 하나 이상이 0일 수 있습니다. 0 바이트의 부재 또는 존재는 예상할 수 없습니다.

애플리케이션에서 LCMapString 또는 LCMapStringEx를 사용하는 또 다른 방법은 매핑 문자열입니다. 이 경우 애플리케이션은 dwMapFlags 매개 변수에 대한 LCMAP_SORTKEY 지정하지 않지만 플래그의 다른 조합을 제공합니다. 자세한 내용은 애플리케이션에서 정렬 처리를 참조하세요.

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

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

요구 사항

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

참고 항목

CompareString

FindNLSStringEx

GetNLSVersionEx

애플리케이션에서 정렬 처리

LCMapString

국가 언어 지원

국가 언어 지원 함수