WideCharToMultiByte 함수(stringapiset.h)
UTF-16(와이드 문자) 문자열을 새 문자열에 매핑합니다. 새 문자열이 반드시 멀티바이트 문자 집합에서 온 것은 아닙니다.
UTF-16에서 비유니코드 인코딩으로 변환된 데이터는 코드 페이지가 특정 유니코드 데이터에 사용되는 모든 문자를 나타내지 못할 수 있으므로 데이터가 손실될 수 있습니다. 자세한 내용은 보안 고려 사항: 국가별 기능을 참조하세요.
구문
int WideCharToMultiByte(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
[in] int cchWideChar,
[out, optional] LPSTR lpMultiByteStr,
[in] int cbMultiByte,
[in, optional] LPCCH lpDefaultChar,
[out, optional] LPBOOL lpUsedDefaultChar
);
매개 변수
[in] CodePage
변환을 수행하는 데 사용할 코드 페이지입니다. 이 매개 변수는 운영 체제에 설치되거나 사용 가능한 모든 코드 페이지의 값으로 설정할 수 있습니다. 코드 페이지 목록은 코드 페이지 식별자를 참조하세요. 애플리케이션은 다음 표에 표시된 값 중 하나를 지정할 수도 있습니다.
[in] dwFlags
변환 유형을 나타내는 플래그입니다. 애플리케이션은 다음 값의 조합을 지정할 수 있습니다. 이러한 플래그가 설정되지 않은 경우 함수가 더 빠르게 수행됩니다. 애플리케이션은 가능한 모든 변환 결과를 검색하기 위해 특정 값 WC_DEFAULTCHAR WC_NO_BEST_FIT_CHARS 및 WC_COMPOSITECHECK 지정해야 합니다. 세 값이 모두 제공되지 않으면 일부 결과가 누락됩니다.
| 값 | 의미 | ||||||
|---|---|---|---|---|---|---|---|
|
기본 문자와 간격이 없는 문자로 구성된 복합 문자를 각각 서로 다른 문자 값으로 변환합니다. 이러한 문자를 기본 공백이 아닌 문자 조합에 대한 단일 문자 값이 있는 미리 구성된 문자로 변환합니다. 예를 들어 문자 è에서 e는 기본 문자이고 악센트 그레이브 마크는 간격이 없는 문자입니다. 참고 Windows는 일반적으로 미리 구성된 데이터가 있는 유니코드 문자열을 나타내므로 WC_COMPOSITECHECK 플래그를 사용할 필요가 없습니다.
애플리케이션은 WC_COMPOSITECHECK 다음 플래그 중 하나와 결합할 수 있으며 기본값은 WC_SEPCHARS. 이러한 플래그는 유니코드 문자열의 기본 비스페이스 문자 조합에 대한 사전 구성 매핑을 사용할 수 없는 경우 함수의 동작을 결정합니다. 이러한 플래그를 제공하지 않으면 함수는 WC_SEPCHARS 플래그가 설정된 것처럼 동작합니다. 자세한 내용은 설명 섹션의 WC_COMPOSITECHECK 및 관련 플래그 를 참조하세요 .
|
||||||
|
Windows Vista 이상: 잘못된 입력 문자가 발견되면 0을 반환하고 마지막 오류 코드를 ERROR_NO_UNICODE_TRANSLATION 설정하여 실패합니다. GetLastError를 호출하여 마지막 오류 코드를 검색할 수 있습니다. 이 플래그가 설정되지 않은 경우 함수는 잘못된 시퀀스를 U+FFFD(지정된 코드 페이지에 적절하게 인코딩됨)로 바꾸고 변환된 문자열의 길이를 반환하여 성공합니다. 이 플래그는 CodePage 가 CP_UTF8 또는 54936으로 지정된 경우에만 적용됩니다. 다른 코드 페이지 값과 함께 사용할 수 없습니다. | ||||||
|
직접 변환되지 않는 유니코드 문자를 lpDefaultChar로 지정된 기본 문자에 해당하는 멀티바이트 문자로 변환합니다. 즉, 유니코드에서 멀티바이트로 변환하고 유니코드로 다시 변환해도 동일한 유니코드 문자가 생성되지 않는 경우 함수는 기본 문자를 사용합니다. 이 플래그는 단독으로 또는 정의된 다른 플래그와 함께 사용할 수 있습니다.
파일, 리소스 및 사용자 이름과 같은 유효성 검사가 필요한 문자열의 경우 애플리케이션은 항상 WC_NO_BEST_FIT_CHARS 플래그를 사용해야 합니다. 이 플래그는 함수가 유사하지만 의미 체계가 매우 다른 문자에 문자를 매핑하는 것을 방지합니다. 경우에 따라 의미 체계 변경이 극단적일 수 있습니다. 예를 들어 "∞"(무한대)의 기호는 일부 코드 페이지에서 8(8)에 매핑됩니다. |
아래에 나열된 코드 페이지의 경우 dwFlags는 0이어야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_FLAGS 실패합니다.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002~57011
- 65000(UTF-7)
- 42(기호)
[in] lpWideCharStr
변환할 유니코드 문자열에 대한 포인터입니다.
[in] cchWideChar
lpWideCharStr로 표시된 문자열의 크기(문자)입니다. 또는 문자열이 null로 종료된 경우 이 매개 변수를 -1로 설정할 수 있습니다. cchWideChar를 0으로 설정하면 함수가 실패합니다.
이 매개 변수가 -1이면 함수는 종료 null 문자를 포함하여 전체 입력 문자열을 처리합니다. 따라서 결과 문자열에는 종료 null 문자가 있으며 함수에서 반환되는 길이에는 이 문자가 포함됩니다.
이 매개 변수가 양의 정수로 설정된 경우 함수는 지정된 문자 수를 정확하게 처리합니다. 제공된 크기에 종료 null 문자가 포함되지 않은 경우 결과 문자열은 null로 종료되지 않으며 반환된 길이에는 이 문자가 포함되지 않습니다.
[out, optional] lpMultiByteStr
변환된 문자열을 수신하는 버퍼에 대한 포인터입니다.
[in] cbMultiByte
lpMultiByteStr로 표시된 버퍼의 크기(바이트)입니다. 이 값이 0이면 함수는 종료되는 null 문자를 포함하여 필요한 버퍼 크기(바이트)를 반환하고 lpMultiByteStr 버퍼를 사용하지 않습니다.
[in, optional] lpDefaultChar
지정된 코드 페이지에서 문자를 나타낼 수 없는 경우 사용할 문자에 대한 포인터입니다. 함수가 시스템 기본값을 사용하는 경우 애플리케이션은 이 매개 변수를 NULL 로 설정합니다. 시스템 기본 문자를 가져오기 위해 애플리케이션은 GetCPInfo 또는 GetCPInfoEx 함수를 호출할 수 있습니다.
CodePage에 대한 CP_UTF7 및 CP_UTF8 설정의 경우 이 매개 변수를 NULL로 설정해야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_PARAMETER 실패합니다.
[out, optional] lpUsedDefaultChar
함수가 변환에서 기본 문자를 사용했는지를 나타내는 플래그에 대한 포인터입니다. 원본 문자열에서 하나 이상의 문자를 지정된 코드 페이지에 나타낼 수 없는 경우 플래그가 TRUE 로 설정됩니다. 그렇지 않으면 플래그가 FALSE로 설정됩니다. 이 매개 변수는 NULL로 설정할 수 있습니다.
CodePage에 대한 CP_UTF7 및 CP_UTF8 설정의 경우 이 매개 변수를 NULL로 설정해야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_PARAMETER 실패합니다.
반환 값
성공하면 lpMultiByteStr가 가리키는 버퍼에 기록된 바이트 수를 반환합니다. 함수가 성공하고 cbMultiByte 가 0이면 반환 값은 lpMultiByteStr로 표시된 버퍼에 필요한 크기(바이트)입니다. 또한 잘못된 시퀀스가 입력된 경우 WC_ERR_INVALID_CHARS 플래그가 반환 값에 미치는 영향에 대한 자세한 내용은 dwFlags 를 참조하세요.
함수가 성공하지 못하면 0을 반환합니다. 확장 오류 정보를 가져오기 위해 애플리케이션은 GetLastError를 호출할 수 있으며, 다음 오류 코드 중 하나를 반환할 수 있습니다.
- ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.
- ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
- ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.
- ERROR_NO_UNICODE_TRANSLATION. 문자열에서 잘못된 유니코드가 발견되었습니다.
설명
lpMultiByteStr 및 lpWideCharStr 포인터는 동일하지 않아야 합니다. 동일한 경우 함수가 실패하고 GetLastError 가 ERROR_INVALID_PARAMETER 반환합니다.
입력 문자열 길이가 종료 null 문자 없이 명시적으로 지정된 경우 WideCharToMultiByte는 출력 문자열을 null로 종료하지 않습니다. 이 함수에 대한 출력 문자열을 null로 종료하려면 애플리케이션이 -1을 전달하거나 입력 문자열의 종료 null 문자를 명시적으로 계산해야 합니다.
cbMultiByte가 cchWideChar보다 작은 경우 이 함수는 cbMultiByte로 지정된 문자 수를 lpMultiByteStr로 표시된 버퍼에 씁니다. 그러나 CodePage 가 CP_SYMBOL 로 설정되고 cbMultiByte 가 cchWideChar 보다 작은 경우 함수는 lpMultiByteStr에 문자를 쓰지 않습니다.
WideCharToMultiByte 함수는 lpDefaultChar와 lpUsedDefaultChar가 모두 NULL로 설정된 경우 가장 효율적으로 작동합니다. 다음 표에서는 이러한 매개 변수의 가능한 네 가지 조합에 대한 함수의 동작을 보여 줍니다.
| lpDefaultChar | lpUsedDefaultChar | 결과 |
|---|---|---|
| NULL | NULL | 기본 검사는 없습니다. 이러한 매개 변수 설정은 이 함수에 사용할 수 있는 가장 효율적인 설정입니다. |
| null이 아닌 문자 | NULL | 지정된 기본 문자를 사용하지만 lpUsedDefaultChar를 설정하지는 않습니다. |
| NULL | null이 아닌 문자 | 시스템 기본 문자를 사용하고 필요한 경우 lpUsedDefaultChar 를 설정합니다. |
| null이 아닌 문자 | null이 아닌 문자 | 지정된 기본 문자를 사용하고 필요한 경우 lpUsedDefaultChar 를 설정합니다. |
Windows Vista부터 이 함수는 UTF-8 및 UTF-16에 대한 유니코드 4.1 사양을 완전히 준수합니다. 이전 운영 체제에서 사용된 함수는 고독한 서로게이트 반쪽 또는 일치하지 않는 서로게이트 쌍을 인코딩하거나 디코딩합니다. 이 동작을 사용하여 임의의 텍스트가 아닌 이진 데이터를 인코딩하는 이전 버전의 Windows에서 작성된 코드에 문제가 발생할 수 있습니다. 그러나 이 함수를 사용하여 유효한 UTF-8 문자열을 생성하는 코드는 이전 Windows 운영 체제와 동일한 방식으로 동작합니다.
Windows 8 시작: WideCharToMultiByte는 Stringapiset.h에서 선언됩니다. Windows 8 전에 Winnls.h에서 선언되었습니다.
WC_COMPOSITECHECK 및 관련 플래그
유니코드 정규화를 사용하여 문자열을 나타내는 데 설명된 대로 유니코드는 동일한 문자열의 여러 표현을 허용합니다(언어적으로 해석됨). 예를 들어 dieresis(umlaut)가 있는 대문자 A는 단일 유니코드 코드 포인트 "Ä"(U+00C4)로 미리 구성되거나 대문자 A와 결합된 다이어시스 문자(U+0041 U+0308)의 조합으로 분해될 수 있습니다. 그러나 대부분의 코드 페이지는 구성된 문자만 제공합니다.WC_COMPOSITECHECK 플래그를 사용하면 WideCharToMultiByte 함수가 분해된 유니코드 문자를 테스트하고 요청된 코드 페이지로 변환하기 전에 작성을 시도합니다. 이 플래그는 SBCS(단일 바이트) 또는 DBCS(더블 바이트) 코드 페이지(코드 페이지 < 42 제외) 50000으로 변환하는 경우에만 사용할 수 있습니다. 애플리케이션이 분해된 유니코드 데이터를 단일 바이트 또는 더블 바이트 코드 페이지로 변환해야 하는 경우 이 플래그가 유용할 수 있습니다. 그러나 모든 문자를 이러한 방식으로 변환할 수 있는 것은 아니며 유니코드와 같은 데이터를 저장하고 저장하는 것이 더 안정적입니다.
애플리케이션에서 WC_COMPOSITECHECK 사용하는 경우 일부 문자 조합은 불완전하게 유지되거나 추가 비공유 문자가 남아 있을 수 있습니다. 예를 들어 A + + 은 Ä + 으로 결합됩니다. WC_DISCARDNS 플래그를 사용하면 함수가 추가 비공유 문자를 삭제합니다. WC_DEFAULTCHAR 플래그를 사용하면 함수에서 기본 대체 문자(일반적으로 "?")를 대신 사용합니다. WC_SEPCHARS 플래그를 사용하면 함수가 각 추가 비공유 문자를 대상 코드 페이지로 변환하려고 시도합니다. 일반적으로 이 플래그는 대체 문자("?")를 사용하게 합니다. 그러나 코드 페이지 1258(베트남어) 및 20269의 경우 비공간 문자가 존재하며 사용할 수 있습니다. 이러한 코드 페이지의 변환은 완벽하지 않습니다. 일부 조합은 코드 페이지 1258로 올바르게 변환되지 않으며 WC_COMPOSITECHECK 코드 페이지 20269의 데이터가 손상됩니다. 앞에서 설명한 것처럼 유니코드와 같은 데이터를 저장하고 저장하도록 애플리케이션을 디자인하는 것이 더 안정적입니다.
예제
ISDSC_STATUS DiscpUnicodeToAnsiSize(
IN __in PWCHAR UnicodeString,
OUT ULONG *AnsiSizeInBytes
)
/*++
Routine Description:
This routine will return the length needed to represent the unicode
string as ANSI
Arguments:
UnicodeString is the unicode string whose ansi length is returned
*AnsiSizeInBytes is number of bytes needed to represent unicode
string as ANSI
Return Value:
ERROR_SUCCESS or error code
--*/
{
_try
{
*AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
0,
UnicodeString,
-1,
NULL,
0, NULL, NULL);
} _except(EXCEPTION_EXECUTE_HANDLER) {
return(ERROR_NOACCESS);
}
return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | stringapiset.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |