Функция MultiByteToWideChar (stringapiset.h)

Сопоставляет символьную строку со строкой UTF-16 (широкий символ). Строка символов не обязательно из многобайтового набора символов.

Синтаксис

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

Кодовая страница, используемая при выполнении преобразования. Этот параметр можно задать для значения любой кодовой страницы, установленной или доступной в операционной системе. Список кодовых страниц см. в разделе "Идентификаторы кодовой страницы". Приложение также может указать одно из значений, показанных в следующей таблице.

[in] dwFlags

Флаги, указывающие тип преобразования. Приложение может указать сочетание следующих значений, MB_PRECOMPOSED быть значением по умолчанию. MB_PRECOMPOSED и MB_COMPOSITE являются взаимоисключающими. MB_USEGLYPHCHARS и MB_ERR_INVALID_CHARS можно задать независимо от состояния других флагов.

Для приведенных ниже кодовых страниц необходимо задать 0для dwFlags значение . В противном случае функция завершается ошибкой с ERROR_INVALID_FLAGS.

• 50220
• 50221
• 50222
• 50225
• 50227
• 50229
• 57002–57011
• 65000 (UTF-7)
• 42 (символ)

[in] lpMultiByteStr

Указатель на строку символа для преобразования.

[in] cbMultiByte

Размер в байтах строки, указанной параметром lpMultiByteStr . Кроме того, этот параметр можно задать для -1, если строка завершается значением NULL. Обратите внимание, что если cbMultiByte имеет значение, функция завершается 0ошибкой.

Если этот параметр равен -1, функция обрабатывает всю входную строку, включая завершающий символ NULL. Поэтому результирующая строка Юникода имеет конечный символ NULL, а длина, возвращаемая функцией, включает этот символ.

Если этот параметр имеет положительное целое число, функция обрабатывает точно указанное число байтов. Если указанный размер не включает завершающий символ NULL, результирующая строка Юникода не завершается null, а возвращаемая длина не включает этот символ.

[out, optional] lpWideCharStr

Указатель на буфер, получающий преобразованную строку.

[in] cchWideChar

Размер буфера в символах, указанный lpWideCharStr. Если это значение равно 0, функция возвращает требуемый размер буфера в символах, включая символы, завершающие значение NULL, и не использует буфер lpWideCharStr .

Возвращаемое значение

Возвращает число символов, записанных в буфер, указанное lpWideCharStr в случае успешного выполнения. Если функция выполнена успешно, а cchWideChar0— это возвращаемое значение требуемого размера в символах для буфера, указанного lpWideCharStr. См. также dwFlags для получения сведений о том, как флаг MB_ERR_INVALID_CHARS влияет на возвращаемое значение при входе недопустимых последовательностей.

Функция возвращается 0 , если она не выполнена. Чтобы получить расширенные сведения об ошибке, приложение может вызвать GetLastError, который может возвращать один из следующих кодов ошибок:

• ERROR_INSUFFICIENT_BUFFER: предоставленный размер буфера был недостаточно велик или неправильно задан NULL.
• ERROR_INVALID_FLAGS. Значения, указанные для флагов, недопустимы.
• ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
• ERROR_NO_UNICODE_TRANSLATION. Недопустимый Юникод найден в строке.

Замечания

Поведение этой функции по умолчанию заключается в переводе в предварительно композитированную форму входной символьной строки. Если предварительно композированная форма не существует, функция пытается преобразовать в составную форму.

Кодовые страницы ANSI могут отличаться на разных компьютерах или могут быть изменены для одного компьютера, что приводит к повреждению данных. Для наиболее согласованных результатов приложения должны использовать Юникод, например UTF-8 или UTF-16, вместо определенной кодовой страницы, если устаревшие стандарты или форматы данных не препятствуют использованию Юникода. Если использование Юникода невозможно, приложения должны пометить поток данных соответствующим именем кодировки, если протоколы позволяют ему. HTML-файлы и XML позволяют добавлять теги, но текстовые файлы не выполняются.

Выходной буфер можно легко перезапустить, если эта функция не сначала вызывается с набором cchWideChar0, чтобы получить требуемый размер. Если используется флаг MB_COMPOSITE, выходные данные могут содержать три или более символов для каждого входного символа.

Использование флага MB_PRECOMPOSED очень мало влияет на большинство кодовых страниц, так как большинство входных данных уже составлены. Рассмотрите возможность вызова NormalizeString после преобразования с помощью MultiByteToWideChar. NormalizeString обеспечивает более точные, стандартные и согласованные данные, а также может быть быстрее. Обратите внимание, что для перечисления NORM_FORM , передаваемого в NormalizeString, NormalizationC соответствует MB_PRECOMPOSED и NormalizationD соответствует MB_COMPOSITE.

Указатели lpMultiByteStr и lpWideCharStr не должны совпадать. Если они одинаковы, функция завершается ошибкой, и GetLastError возвращает значение ERROR_INVALID_PARAMETER.

MultiByteToWideChar не завершает выходную строку, если длина входной строки явно указана без завершающего символа NULL. Чтобы завершить выходную строку для этой функции, приложение должно передать -1 или явно подсчитать завершающий символ NULL для входной строки.

Функция завершается ошибкой, если задано MB_ERR_INVALID_CHARS, и в исходной строке обнаружен недопустимый символ. Недопустимый символ является одним из следующих:

• Символ, который не является символом по умолчанию в исходной строке, но преобразуется в символ по умолчанию, если MB_ERR_INVALID_CHARS не задан.
• Для строк DBCS символ, имеющий байт свинца, но недопустимый байт следа.

Начиная с Windows Vista эта функция полностью соответствует спецификации Юникода 4.1 для UTF-8 и UTF-16. Функция, используемая в предыдущих операционных системах, кодирует или декодирует одинокие суррогатные половины или несовпадение суррогатных пар. Код, написанный в более ранних версиях 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();
}

Пример из универсальных примеров Windows на GitHub.

Требования

См. также

Функции Юникода и набора символов

Юникод и наборы символов

WideCharToMultiByte

API Vertdll, доступные в анклавах VBS