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

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

Синтаксис

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

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

[in] dwFlags

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

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

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

[in] lpWideCharStr

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

[in] cchWideChar

Размер строки в символах, указанной lpWideCharStr. Кроме того, этот параметр может иметь значение -1, если строка завершается null. Если параметр cchWideChar имеет значение 0, функция завершается ошибкой.

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

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

[out, optional] lpMultiByteStr

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

[in] cbMultiByte

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

[in, optional] lpDefaultChar

Указатель на символ, используемый, если символ не может быть представлен на указанной кодовой странице. Приложение задает этому параметру значение NULL , если функция использует системное значение по умолчанию. Чтобы получить системный символ по умолчанию, приложение может вызвать функцию GetCPInfo или GetCPInfoEx .

Для параметров CP_UTF7 и CP_UTF8 для CodePage этот параметр должен иметь значение NULL. В противном случае функция завершается сбоем с ERROR_INVALID_PARAMETER.

[out, optional] lpUsedDefaultChar

Указатель на флаг, указывающий, использовала ли функция символ по умолчанию при преобразовании. Флаг имеет значение TRUE , если один или несколько символов в исходной строке не могут быть представлены на указанной кодовой странице. В противном случае флагу присваивается значение FALSE. Для этого параметра можно задать значение NULL.

Для параметров CP_UTF7 и CP_UTF8 для CodePage этот параметр должен иметь значение 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. В строке обнаружен недопустимый Юникод.

Комментарии

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

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

Если значение cbMultiByte меньше , чем cchWideChar, эта функция записывает количество символов, заданное параметром cbMultiByte, в буфер, указанный lpMultiByteStr. Однако если для CodePage задано значение CP_SYMBOL а cbMultiByte меньше , чем cchWideChar, функция не записывает символы в lpMultiByteStr.

Функция WideCharToMultiByte работает наиболее эффективно, если для lpDefaultChar и lpUsedDefaultChar задано значение NULL. В следующей таблице показано поведение функции для четырех возможных сочетаний этих параметров.

Начиная с Windows Vista эта функция полностью соответствует спецификации Юникода 4.1 для UTF-8 и UTF-16. Функция, используемая в более ранних операционных системах, кодирует или декодирует одинокие суррогатные половины или несовпадение суррогатных пар. Код, написанный в более ранних версиях Windows, который использует такое поведение для кодирования случайных нетекстовых двоичных данных, может столкнуться с проблемами. Однако код, использующий эту функцию для создания допустимых строк UTF-8, будет вести себя так же, как и в более ранних операционных системах Windows.

Начиная с Windows 8: WideCharToMultiByte объявляется в Stringapiset.h. До Windows 8 он был объявлен в Winnls.h.

WC_COMPOSITECHECK и связанные флаги

Флаг WC_COMPOSITECHECK приводит к тому, что функция WideCharToMultiByte проверяет наличие разложенных символов Юникода и пытается создать их перед преобразованием в запрошенную кодовую страницу. Этот флаг доступен только для преобразования в однобайтовые (SBCS) или двухбайтовые (DBCS) кодовые страницы (кодовые страницы < 50000, за исключением кодовой страницы 42). Если приложению необходимо преобразовать разложенные данные Юникода в однобайтовые или двойные кодовые страницы, этот флаг может оказаться полезным. Однако не все символы можно преобразовать таким образом, и это более надежно для сохранения и хранения таких данных, как Юникод.

Если приложение использует 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);
}

Требования

См. также

MultiByteToWideChar

Функции Юникода и кодировки

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

API-интерфейсы Vertdll, доступные в анклавах VBS