Функция 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 можно задать независимо от состояния других флагов.
| Ценность | Значение |
|---|---|
| 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_USEGLYPHCHARS
Для приведенных ниже кодовых страниц
- 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 |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по