MultiByteToWideChar 함수(stringapiset.h)

아티클
02/05/2024

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

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

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

구문

int MultiByteToWideChar(
  [in]            UINT                              CodePage,
  [in]            DWORD                             dwFlags,
  [in]            _In_NLS_string_(cbMultiByte)LPCCH lpMultiByteStr,
  [in]            int                               cbMultiByte,
  [out, optional] LPWSTR                            lpWideCharStr,
  [in]            int                               cchWideChar
);

매개 변수

[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	기호 코드 페이지(42).
CP_THREAD_ACP	현재 스레드에 대한 Windows ANSI 코드 페이지입니다. 참고 이 값은 동일한 네트워크에서도 서로 다른 컴퓨터에서 다를 수 있습니다. 동일한 컴퓨터에서 변경하여 저장된 데이터가 복구할 수 없게 손상될 수 있습니다. 이 값은 임시 용도로만 사용되며 영구 스토리지는 가능한 경우 UTF-16 또는 UTF-8을 사용해야 합니다.
CP_UTF7	UTF-7. 7비트 전송 메커니즘에 의해 강제 적용된 경우에만 이 값을 사용합니다. UTF-8을 사용하는 것이 좋습니다.
CP_UTF8	UTF-8.

[in] dwFlags

변환 형식을 나타내는 플래그입니다. 애플리케이션은 다음 값의 조합을 지정할 수 있으며 MB_PRECOMPOSED 기본값입니다. MB_PRECOMPOSED 및 MB_COMPOSITE 함께 사용할 수 없습니다. MB_USEGLYPHCHARS 및 MB_ERR_INVALID_CHARS 다른 플래그의 상태에 관계없이 설정할 수 있습니다.

값	의미
MB_COMPOSITE	항상 분해된 문자, 즉 기본 문자와 하나 이상의 간격이 없는 문자에 각각 고유한 코드 포인트 값이 있는 문자를 사용합니다. 예를 들어 Ä는 A + 으로 표시됩니다. LATIN CAPITAL LETTER A(U+0041) + COMBINING DIAERESIS(U+0308). 이 플래그는 MB_PRECOMPOSED 사용할 수 없습니다.
MB_ERR_INVALID_CHARS	잘못된 입력 문자가 발견되면 실패합니다. Windows Vista부터 애플리케이션이 이 플래그를 설정하지 않은 경우 함수는 잘못된 코드 포인트를 삭제하지 않고 대신 잘못된 시퀀스를 U+FFFD(지정된 코드 페이지에 적절하게 인코딩됨)로 바꿉니다. Windows 2000 SP4 이상, Windows XP: 이 플래그가 설정되지 않은 경우 함수는 잘못된 코드 포인트를 자동으로 삭제합니다. GetLastError 호출은 ERROR_NO_UNICODE_TRANSLATION 반환합니다.

값

의미

MB_COMPOSITE

항상 분해된 문자, 즉 기본 문자와 하나 이상의 간격이 없는 문자에 각각 고유한 코드 포인트 값이 있는 문자를 사용합니다. 예를 들어 Ä는 A + 으로 표시됩니다. LATIN CAPITAL LETTER A(U+0041) + COMBINING DIAERESIS(U+0308). 이 플래그는 MB_PRECOMPOSED 사용할 수 없습니다.

MB_ERR_INVALID_CHARS

잘못된 입력 문자가 발견되면 실패합니다.

Windows Vista부터 애플리케이션이 이 플래그를 설정하지 않은 경우 함수는 잘못된 코드 포인트를 삭제하지 않고 대신 잘못된 시퀀스를 U+FFFD(지정된 코드 페이지에 적절하게 인코딩됨)로 바꿉니다.

Windows 2000 SP4 이상, Windows XP: 이 플래그가 설정되지 않은 경우 함수는 잘못된 코드 포인트를 자동으로 삭제합니다. GetLastError 호출은 ERROR_NO_UNICODE_TRANSLATION 반환합니다.

MB_PRECOMPOSED

기본; MB_COMPOSITE 사용하지 마세요. 항상 미리 컴파일된 문자( 즉, 기본 또는 불투명 문자 조합에 대한 단일 문자 값이 있는 문자)를 사용합니다. 예를 들어 문자 è에서 e는 기본 문자이고 악센트 그레이브 마크는 비스페이스 문자입니다. 단일 유니코드 코드 포인트가 문자에 대해 정의된 경우 애플리케이션은 별도의 기본 문자와 비스페이스 문자 대신 이를 사용해야 합니다. 예를 들어 Ä는 단일 유니코드 코드 포인트 LATIN CAPITAL LETTER A WITH DIAERESIS(U+00C4)로 표시됩니다.

MB_USEGLYPHCHARS

컨트롤 문자 대신 문자 모양을 사용합니다.

아래에 나열된 코드 페이지의 경우 dwFlags를 로 0설정해야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_FLAGS 실패합니다.

50220
50221
50222
50225
50227
50229
57002~57011
65000(UTF-7)
42(기호)

참고

UTF-8 또는 코드 페이지 54936(windows Vista부터 GB18030)의 경우 dwFlags 를 또는 0MB_ERR_INVALID_CHARS 설정해야 합니다. 그렇지 않으면 함수가 ERROR_INVALID_FLAGS 실패합니다.

[in] lpMultiByteStr

변환할 문자열에 대한 포인터입니다.

[in] cbMultiByte

lpMultiByteStr 매개 변수로 표시된 문자열의 크기(바이트)입니다. 또는 문자열이 null로 종료된 경우 이 매개 변수를 -1로 설정할 수 있습니다. cbMultiByte가 이0면 함수가 실패합니다.

이 매개 변수가 -1이면 함수는 종료 null 문자를 포함하여 전체 입력 문자열을 처리합니다. 따라서 결과 유니코드 문자열에는 종료 null 문자가 있으며 함수에서 반환되는 길이에는 이 문자가 포함됩니다.

이 매개 변수가 양의 정수로 설정된 경우 함수는 지정된 바이트 수를 정확하게 처리합니다. 제공된 크기에 종료 null 문자가 포함되지 않은 경우 결과 유니코드 문자열은 null로 종료되지 않으며 반환된 길이에는 이 문자가 포함되지 않습니다.

[out, optional] lpWideCharStr

변환된 문자열을 수신하는 버퍼에 대한 포인터입니다.

[in] cchWideChar

lpWideCharStr로 표시된 버퍼의 크기(문자)입니다. 이 값이 이면 함수는 0종료되는 null 문자를 포함하여 필요한 버퍼 크기를 문자로 반환하고 lpWideCharStr 버퍼를 사용하지 않습니다.

반환 값

성공하면 lpWideCharStr 로 표시된 버퍼에 기록된 문자 수를 반환합니다. 함수가 성공하고 cchWideChar 가 이 0면 반환 값은 lpWideCharStr로 표시된 버퍼에 필요한 크기(문자)입니다. 또한 잘못된 시퀀스가 입력된 경우 MB_ERR_INVALID_CHARS 플래그가 반환 값에 미치는 영향에 대한 자세한 내용은 dwFlags를 참조하세요.

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

ERROR_INSUFFICIENT_BUFFER: 제공된 버퍼 크기가 충분히 크지 않거나 로 잘못 설정 NULL되었습니다.
ERROR_INVALID_FLAGS: 플래그에 제공된 값이 잘못되었습니다.
ERROR_INVALID_PARAMETER: 매개 변수 값이 잘못되었습니다.
ERROR_NO_UNICODE_TRANSLATION: 문자열에서 잘못된 유니코드가 발견되었습니다.

설명

이 함수의 기본 동작은 입력 문자 문자열의 미리 컴파일된 형식으로 변환하는 것입니다. 미리 컴파일된 양식이 없는 경우 함수는 복합 양식으로 변환하려고 시도합니다.

대부분의 입력 데이터가 이미 구성되어 있기 때문에 MB_PRECOMPOSED 플래그의 사용은 대부분의 코드 페이지에 거의 영향을 미치지 않습니다. MultiByteToWideChar로 변환한 후 NormalizeString을 호출하는 것이 좋습니다. NormalizeString 은 더 정확하고 표준적이고 일관된 데이터를 제공하며 더 빠를 수도 있습니다. NormalizeString에 전달되는 NORM_FORM 열거형의 경우 NormalizationC는 MB_PRECOMPOSED 해당하고 NormalizationD는 MB_COMPOSITE 해당합니다.

위의 주의 사항에서 설명한 것처럼 이 함수가 cchWideChar 를 로 설정 0 하여 먼저 호출되지 않은 경우 출력 버퍼를 쉽게 오버런하여 필요한 크기를 얻을 수 있습니다. MB_COMPOSITE 플래그를 사용하는 경우 출력은 각 입력 문자에 대해 세 개 이상의 문자가 될 수 있습니다.

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

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

MB_ERR_INVALID_CHARS 설정되고 원본 문자열에서 잘못된 문자가 발견되면 함수가 실패합니다. 잘못된 문자는 다음 중 하나입니다.

원본 문자열의 기본 문자는 아니지만 MB_ERR_INVALID_CHARS 설정되지 않은 경우 기본 문자로 변환되는 문자입니다.
DBCS 문자열의 경우 리드 바이트가 있지만 유효한 내역 바이트가 없는 문자입니다.

Windows Vista부터 이 함수는 UTF-8 및 UTF-16에 대한 유니코드 4.1 사양을 완전히 준수합니다. 이전 운영 체제에서 사용된 함수는 고독한 서로게이트 반쪽 또는 일치하지 않는 서로게이트 쌍을 인코딩하거나 디코딩합니다. 이 동작을 사용하여 임의의 텍스트가 아닌 이진 데이터를 인코딩하는 이전 버전의 Windows에서 작성된 코드에 문제가 발생할 수 있습니다. 그러나 유효한 UTF-8 문자열에서 이 함수를 사용하는 코드는 이전 Windows 운영 체제와 동일한 방식으로 동작합니다.

Windows XP: UTF-8 문자의 가장 짧은 형식이 아닌 버전의 보안 문제를 방지하기 위해 MultiByteToWideChar 는 이러한 문자를 삭제합니다.

Windows 8:MultiByteToWideChar부터는 에 Stringapiset.h선언됩니다. Windows 8 전에 에서 Winnls.h선언되었습니다.

코드 예제

catch (std::exception e)
{
    // Save in-memory logging buffer to a log file on error.

    ::std::wstring wideWhat;
    if (e.what() != nullptr)
    {
        int convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), NULL, 0);
        if (convertResult <= 0)
        {
            wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
            wideWhat += convertResult.ToString()->Data();
            wideWhat += L"  GetLastError()=";
            wideWhat += GetLastError().ToString()->Data();
        }
        else
        {
            wideWhat.resize(convertResult + 10);
            convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), &wideWhat[0], (int)wideWhat.size());
            if (convertResult <= 0)
            {
                wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
                wideWhat += convertResult.ToString()->Data();
                wideWhat += L"  GetLastError()=";
                wideWhat += GetLastError().ToString()->Data();
            }
            else
            {
                wideWhat.insert(0, L"Exception occurred: ");
            }
        }
    }
    else
    {
        wideWhat = L"Exception occurred: Unknown.";
    }

    Platform::String^ errorMessage = ref new Platform::String(wideWhat.c_str());
    // The session added the channel at level Warning. Log the message at
    // level Error which is above (more critical than) Warning, which
    // means it will actually get logged.
    _channel->LogMessage(errorMessage, LoggingLevel::Error);
    SaveLogInMemoryToFileAsync().then([=](StorageFile^ logFile) {
        _logFileGeneratedCount++;
        StatusChanged(this, ref new LoggingScenarioEventArgs(LoggingScenarioEventType::LogFileGenerated, logFile->Path->Data()));
    }).wait();
}

GitHub의 Windows 유니버설 샘플 예제입니다.

요구 사항

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

참고 항목

유니코드 및 문자 집합 함수

유니코드 및 문자 집합

WideCharToMultiByte

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