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

Статья
07/16/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) + ОБЪЕДИНЕНИЕ DIAERESIS (U+0308). Обратите внимание, что этот флаг нельзя использовать с MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	Сбой, если обнаружен недопустимый входной символ. Начиная с Windows Vista функция не удаляет незаконные точки кода, если приложение не устанавливает этот флаг, но вместо этого заменяет незаконные последовательности на U+FFFD (закодировано соответствующим образом для указанной кодовой страницы). Windows 2000 с пакетом обновления 4 (SP4) и более поздних версий Windows XP: Если этот флаг не задан, функция автоматически удаляет незаконные кодовые точки. Вызов GetLastError возвращает ERROR_NO_UNICODE_TRANSLATION.

Ценность

Значение

MB_COMPOSITE

Всегда используйте декомпозированные символы, то есть символы, в которых базовый символ и один или несколько неспакционных символов имеют отдельные значения точек кода. Например, Ä представленА A + Ä: LATIN CAPITAL LETTER A (U+0041) + ОБЪЕДИНЕНИЕ DIAERESIS (U+0308). Обратите внимание, что этот флаг нельзя использовать с MB_PRECOMPOSED.

MB_ERR_INVALID_CHARS

Сбой, если обнаружен недопустимый входной символ.

Начиная с Windows Vista функция не удаляет незаконные точки кода, если приложение не устанавливает этот флаг, но вместо этого заменяет незаконные последовательности на U+FFFD (закодировано соответствующим образом для указанной кодовой страницы).

Windows 2000 с пакетом обновления 4 (SP4) и более поздних версий Windows XP: Если этот флаг не задан, функция автоматически удаляет незаконные кодовые точки. Вызов GetLastError возвращает ERROR_NO_UNICODE_TRANSLATION.

MB_PRECOMPOSED

По умолчанию; не используйте MB_COMPOSITE. Всегда используйте предварительно композированные символы, т. е. символы, имеющие одно символьное значение для базовой или неспециационной комбинации символов. Например, в символе è значение e является базовым символом, а знак акцента — неспециационным символом. Если для символа определена одна кодовая точка Юникода, приложение должно использовать его вместо отдельного базового и неспакционного символа. Например, Ä представлена одной точкой кода Юникода LATIN CAPITAL LETTER A WITH DIAERESIS (U+00C4).

MB_USEGLYPHCHARS

Используйте глифы вместо символов управления.

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

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

Заметка

Для UTF-8 или кодовой страницы 54936 (GB18030, начиная с Windows Vista), dwFlags должны иметь значение 0 или MB_ERR_INVALID_CHARS. В противном случае функция завершается ошибкой с ERROR_INVALID_FLAGS.

[in] lpMultiByteStr

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

[in] cbMultiByte

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

Если этот параметр равен -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: в строке найден недопустимый Юникод.

Замечания

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

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

Как упоминалось выше, выходной буфер можно легко перезагрузить, если эта функция не вызывается с cchWideChar значение 0, чтобы получить требуемый размер. Если используется флаг 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.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows 2000 Server [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	stringapiset.h (include Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

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

WideCharToMultiByte

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

Поделиться через