Функция IdnToUnicode (winnls.h)

Статья
08/27/2023

Преобразует форму Punycode международного доменного имени (IDN) или другой международной метки в обычный синтаксис кодировки Юникод UTF-16.

Осторожностью Эта функция реализует стандартные алгоритмы RFC 3490: Internationalizing Domain Names in Applications (IDNA) для кодировки Юникода в Punycode. В стандарте возникают некоторые проблемы с безопасностью. Одна из проблем заключается в том, что глифы, представляющие определенные символы из разных скриптов, могут казаться похожими или даже идентичными. Например, во многих шрифтах кириллица нижнего регистра A ("а") неотличима от латинского нижнего регистра A ("a"). Невозможно визуально сказать, что "example.com" и "exа mple.com" являются двумя разными доменными именами, одно с латинским строчным регистром A в имени, другое с кириллицей строчной буквы A. Дополнительные сведения о проблемах безопасности, связанных с IDN, см. в разделе Обработка международных доменных имен (IDN).

Синтаксис

int IdnToUnicode(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpASCIICharStr,
  [in]            int     cchASCIIChar,
  [out, optional] LPWSTR  lpUnicodeCharStr,
  [in]            int     cchUnicodeChar
);

Параметры

[in] dwFlags

Флаги, указывающие параметры преобразования. Подробные определения см. в параметре dwFlagsidnToAscii.

[in] lpASCIICharStr

Указатель на строку, представляющую кодировку Punycode idN или другой международной метки. Эта строка должна состоять только из символов ASCII и может включать Юникод в кодировке Punycode. Функция декодирует значения Punycode в значения UTF-16.

[in] cchASCIIChar

Количество символов во входной строке, указанной lpASCIICharStr.

[out, optional] lpUnicodeCharStr

Указатель на буфер, который получает обычную кодировку Юникода UTF-16, эквивалентную значению Punycode входной строки. Кроме того, функция может получить значение NULL для этого параметра, если для параметра cchUnicodeChar задано значение 0. В этом случае функция возвращает размер, необходимый для этого буфера.

[in] cchUnicodeChar

Размер буфера в символах, указанный lpUnicodeCharStr. Приложение может задать размер равным 0, чтобы получить значение NULL в lpUnicodeCharStr , а функция возвращает требуемый размер буфера.

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

Возвращает количество символов, полученных в lpUnicodeCharStr в случае успешного выполнения. Полученная строка завершается null, только если входная строка завершается null.

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

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

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или неправильно задано значение NULL.
ERROR_INVALID_FLAGS. Значения, предоставленные для флагов, были недопустимыми.
ERROR_INVALID_NAME. Для функции было предоставлено недопустимое имя. Обратите внимание, что этот код ошибки перехватывает все синтаксические ошибки.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
ERROR_NO_UNICODE_TRANSLATION. В строке обнаружен недопустимый Юникод.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
Библиотека	Normaliz.lib
DLL	Normaliz.dll
Распространяемые компоненты	API-интерфейсы устранения международных доменных имен (IDN) в Windows XP с пакетом обновления 2 (SP2) или Windows Server 2003 с пакетом обновления 1 (SP1)

См. также раздел

Обработка международных доменных имен (IDN)

IdnToAscii

IdnToNameprepUnicode

Поддержка национальных языков

Функции поддержки национальных языков