다음을 통해 공유


WideCharToMultiByte 함수(stringapiset.h)

UTF-16(와이드 문자) 문자열을 새 문자열에 매핑합니다. 새 문자열이 반드시 멀티바이트 문자 집합에서 온 것은 아닙니다.

주의WideCharToMultiByte 함수를 잘못 사용하면 애플리케이션의 보안이 손상됩니다. lpWideCharStr로 표시된 입력 버퍼의 크기가 유니코드 문자열의 문자 수와 같고 lpMultiByteStr로 표시된 출력 버퍼의 크기는 바이트 수와 같기 때문에 이 함수를 호출하면 버퍼 오버런이 쉽게 발생할 수 있습니다. 버퍼 오버런을 방지하려면 애플리케이션에서 버퍼가 수신하는 데이터 형식에 적합한 버퍼 크기를 지정해야 합니다.

UTF-16에서 비유니코드 인코딩으로 변환된 데이터는 코드 페이지가 특정 유니코드 데이터에 사용되는 모든 문자를 나타내지 못할 수 있으므로 데이터가 손실될 수 있습니다. 자세한 내용은 보안 고려 사항: 국가별 기능을 참조하세요.

 
참고 ANSI 코드 페이지는 다른 컴퓨터에서 다를 수 있거나 단일 컴퓨터에 대해 변경되어 데이터가 손상될 수 있습니다. 가장 일관된 결과를 위해 애플리케이션은 레거시 표준 또는 데이터 형식이 유니코드 사용을 차단하지 않는 한 특정 코드 페이지 대신 UTF-8 또는 UTF-16과 같은 유니코드를 사용해야 합니다. 유니코드를 사용할 수 없는 경우 애플리케이션은 프로토콜이 허용하는 경우 적절한 인코딩 이름으로 데이터 스트림에 태그를 지정해야 합니다. HTML 및 XML 파일은 태그 지정을 허용하지만 텍스트 파일은 태그 지정을 허용하지 않습니다.
 

구문

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

변환을 수행하는 데 사용할 코드 페이지입니다. 이 매개 변수는 운영 체제에 설치되거나 사용 가능한 모든 코드 페이지의 값으로 설정할 수 있습니다. 코드 페이지 목록은 코드 페이지 식별자를 참조하세요. 애플리케이션은 다음 표에 표시된 값 중 하나를 지정할 수도 있습니다.

의미
CP_ACP
시스템 기본 Windows ANSI 코드 페이지입니다.
참고 이 값은 동일한 네트워크에서도 서로 다른 컴퓨터에서 다를 수 있습니다. 동일한 컴퓨터에서 변경하여 저장된 데이터가 복구할 수 없게 손상될 수 있습니다. 이 값은 임시 용도로만 사용되며 영구 스토리지는 가능한 경우 UTF-16 또는 UTF-8을 사용해야 합니다.
 
CP_MACCP
현재 시스템 Macintosh 코드 페이지입니다.
참고 이 값은 동일한 네트워크에서도 서로 다른 컴퓨터에서 다를 수 있습니다. 동일한 컴퓨터에서 변경하여 저장된 데이터가 복구할 수 없게 손상될 수 있습니다. 이 값은 임시 용도로만 사용되며 영구 스토리지는 가능한 경우 UTF-16 또는 UTF-8을 사용해야 합니다.
 
참고 이 값은 주로 레거시 코드에서 사용되며, 최신 Macintosh 컴퓨터는 인코딩에 유니코드를 사용하기 때문에 일반적으로 필요하지 않습니다.
 
CP_OEMCP
현재 시스템 OEM 코드 페이지입니다.
참고 이 값은 동일한 네트워크에서도 서로 다른 컴퓨터에서 다를 수 있습니다. 동일한 컴퓨터에서 변경하여 저장된 데이터가 복구할 수 없게 손상될 수 있습니다. 이 값은 임시 용도로만 사용되며 영구 스토리지는 가능한 경우 UTF-16 또는 UTF-8을 사용해야 합니다.
 
CP_SYMBOL
Windows 2000: 기호 코드 페이지(42).
CP_THREAD_ACP
Windows 2000: 현재 스레드에 대한 Windows ANSI 코드 페이지입니다.
참고 이 값은 동일한 네트워크에서도 서로 다른 컴퓨터에서 다를 수 있습니다. 동일한 컴퓨터에서 변경하여 저장된 데이터가 복구할 수 없게 손상될 수 있습니다. 이 값은 임시 용도로만 사용되며 영구 스토리지는 가능한 경우 UTF-16 또는 UTF-8을 사용해야 합니다.
 
CP_UTF7
UTF-7. 7비트 전송 메커니즘에 의해 강제 적용된 경우에만 이 값을 사용합니다. UTF-8을 사용하는 것이 좋습니다. 이 값을 설정하면 lpDefaultCharlpUsedDefaultChar를NULL로 설정해야 합니다.
CP_UTF8
UTF-8. 이 값을 설정하면 lpDefaultCharlpUsedDefaultChar를NULL로 설정해야 합니다.

[in] dwFlags

변환 유형을 나타내는 플래그입니다. 애플리케이션은 다음 값의 조합을 지정할 수 있습니다. 이러한 플래그가 설정되지 않은 경우 함수가 더 빠르게 수행됩니다. 애플리케이션은 가능한 모든 변환 결과를 검색하기 위해 특정 값 WC_DEFAULTCHAR WC_NO_BEST_FIT_CHARS 및 WC_COMPOSITECHECK 지정해야 합니다. 세 값이 모두 제공되지 않으면 일부 결과가 누락됩니다.

의미
WC_COMPOSITECHECK
기본 문자와 간격이 없는 문자로 구성된 복합 문자를 각각 서로 다른 문자 값으로 변환합니다. 이러한 문자를 기본 공백이 아닌 문자 조합에 대한 단일 문자 값이 있는 미리 구성된 문자로 변환합니다. 예를 들어 문자 è에서 e는 기본 문자이고 악센트 그레이브 마크는 간격이 없는 문자입니다.
참고 Windows는 일반적으로 미리 구성된 데이터가 있는 유니코드 문자열을 나타내므로 WC_COMPOSITECHECK 플래그를 사용할 필요가 없습니다.
 

애플리케이션은 WC_COMPOSITECHECK 다음 플래그 중 하나와 결합할 수 있으며 기본값은 WC_SEPCHARS. 이러한 플래그는 유니코드 문자열의 기본 비스페이스 문자 조합에 대한 사전 구성 매핑을 사용할 수 없는 경우 함수의 동작을 결정합니다. 이러한 플래그를 제공하지 않으면 함수는 WC_SEPCHARS 플래그가 설정된 것처럼 동작합니다. 자세한 내용은 설명 섹션의 WC_COMPOSITECHECK 및 관련 플래그 를 참조하세요 .

WC_DEFAULTCHAR 변환 중에 예외를 기본 문자로 바꿉니다.
WC_DISCARDNS 변환하는 동안 간격이 없는 문자를 삭제합니다.
WC_SEPCHARS 기본값 변환하는 동안 별도의 문자를 생성합니다.
 
WC_ERR_INVALID_CHARS
Windows Vista 이상: 잘못된 입력 문자가 발견되면 0을 반환하고 마지막 오류 코드를 ERROR_NO_UNICODE_TRANSLATION 설정하여 실패합니다. GetLastError를 호출하여 마지막 오류 코드를 검색할 수 있습니다. 이 플래그가 설정되지 않은 경우 함수는 잘못된 시퀀스를 U+FFFD(지정된 코드 페이지에 적절하게 인코딩됨)로 바꾸고 변환된 문자열의 길이를 반환하여 성공합니다. 이 플래그는 CodePage 가 CP_UTF8 또는 54936으로 지정된 경우에만 적용됩니다. 다른 코드 페이지 값과 함께 사용할 수 없습니다.
WC_NO_BEST_FIT_CHARS
직접 변환되지 않는 유니코드 문자를 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(기호)
참고 코드 페이지 65001(UTF-8) 또는 코드 페이지 54936(GB18030, Windows Vista 이상)의 경우 dwFlags 를 0 또는 WC_ERR_INVALID_CHARS 설정해야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_FLAGS 실패합니다.
 

[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. 문자열에서 잘못된 유니코드가 발견되었습니다.

설명

lpMultiByteStrlpWideCharStr 포인터는 동일하지 않아야 합니다. 동일한 경우 함수가 실패하고 GetLastError 가 ERROR_INVALID_PARAMETER 반환합니다.

입력 문자열 길이가 종료 null 문자 없이 명시적으로 지정된 경우 WideCharToMultiByte는 출력 문자열을 null로 종료하지 않습니다. 이 함수에 대한 출력 문자열을 null로 종료하려면 애플리케이션이 -1을 전달하거나 입력 문자열의 종료 null 문자를 명시적으로 계산해야 합니다.

cbMultiBytecchWideChar보다 작은 경우 이 함수는 cbMultiByte로 지정된 문자 수를 lpMultiByteStr로 표시된 버퍼에 씁니다. 그러나 CodePage 가 CP_SYMBOL 로 설정되고 cbMultiBytecchWideChar 보다 작은 경우 함수는 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

참고 항목

MultiByteToWideChar

유니코드 및 문자 집합 함수

유니코드 및 문자 집합

VBS Enclave에서 사용할 수 있는 Vertdll API