LCMapStringEx 함수(winnls.h)
이름으로 지정된 로캘의 경우 지정된 변환을 사용하여 입력 문자 문자열을 다른 에 매핑하거나 입력 문자열에 대한 정렬 키를 생성합니다.
구문
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 플래그와 함께 사용할 수 있습니다. 그러나 위에 나열된 다른 플래그와 결합할 수는 없습니다.
아래에 나열된 플래그는 LCMAP_SORTKEY 플래그와 함께만 사용됩니다.
[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이어야 합니다.
참고
CompareStringEx 및 LCMapStringEx 는 정렬 핸들을 지정할 수 있습니다(로캘 이름이 null인 경우). 대부분의 앱에서는 이 사용을 권장하지 않습니다.
반환 값
문자열 매핑에 사용할 때 함수가 성공하면 변환된 문자열의 문자 수를 반환합니다(자세한 내용은 cchSrc 및 cchDest 참조).
정렬 키를 생성하는 데 사용할 때 함수가 성공하면 정렬 키의 바이트 수를 반환합니다.
이 함수는 성공하지 못하면 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 |