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


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

Преобразует международное доменное имя (IDN) или другую интернационализированную метку в представление в Юникоде (широкое символьное) представление строки ASCII, представляющей имя в синтаксисе кодирования передачи Punycode.

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

 

Синтаксис

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

Параметры

[in] dwFlags

Флаги, указывающие параметры преобразования. В следующей таблице перечислены возможные значения.

Значение Значение
IDN_ALLOW_UNASSIGNED
Примечание Приложение может задать это значение, если оно просто использует строку запроса для обычного поиска, как в операции сравнения. Однако приложение не должно задавать это значение для хранимой строки, которая является строкой, подготавливаемой для хранения.
 
Разрешить включение неназначенных кодовых точек во входную строку. По умолчанию не разрешаются неназначенные кодовые точки и происходит сбой с расширенным кодом ошибки ERROR_INVALID_NAME.

Этот флаг позволяет функции обрабатывать символы, которые в настоящее время не являются легальными в IDN, но могут быть законными в более поздних версиях стандарта IDNA. Если приложение кодирует неназначенные кодовые точки как Punycode, полученные доменные имена должны быть недопустимыми. Безопасность может быть скомпрометирована, если более поздняя версия IDNA делает эти имена законными или приложение отфильтровывает недопустимые символы, чтобы попытаться создать юридическое доменное имя. Дополнительные сведения см. в разделе Обработка международных доменных имен (IDN).

IDN_USE_STD3_ASCII_RULES
Отфильтруйте символы ASCII, недопустимые в именах STD3. Во входной строке Юникода разрешены только символы ASCII: буквы, цифры и дефис-минус. Строка не может начинаться или заканчиваться дефисом-минусом. Функция завершается ошибкой, если входная строка Юникода содержит символы ASCII, такие как "[", "]" или "/", которые не могут встречаться в доменных именах.
Примечание Некоторые локальные сети могут разрешать некоторые из этих символов в именах компьютеров.
 

Функция завершается ошибкой, если входная строка Юникода содержит управляющие символы (от U+0001 до U+0020) или символ delete (U+007F). В любом случае этот флаг не влияет на символы, отличные от ASCII, которые разрешены в строке Юникода.

IDN_EMAIL_ADDRESS
Начиная с Windows 8: включите алгоритм EAI для локальных частей адресов электронной почты (например<, local>@microsoft.com). По умолчанию эта функция завершается сбоем, если адрес электронной почты имеет недопустимый адрес или синтаксис.

Приложение может установить этот флаг, чтобы разрешить Email адресной интернационализации (EAI) возвращать обнаруживаемый резервный адрес, если это возможно. Дополнительные сведения см. в уставе IETF Email адресной интернационализации (eai).

IDN_RAW_PUNYCODE
Начиная с Windows 8: отключите проверку и сопоставление Punycode.

[in] lpUnicodeCharStr

Указатель на строку Юникода, представляющую idN или другую международную метку.

[in] cchUnicodeChar

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

[out, optional] lpASCIICharStr

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

[in] cchASCIIChar

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

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

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

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

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

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

Комментарии

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

Обратите внимание, что функция всегда завершается ошибкой, если входная строка содержит управляющие символы (от U+0001 до U+0020) или символ delete (U+007F). Так как символ U+0000 может отображаться только как завершающий символ NULL, функция всегда завершается ошибкой, если U+0000 отображается в другом месте входной строки.

Windows XP, Windows Server 2003:

Больше не поддерживается.

Необходимый файл заголовка и библиотека DLL являются частью API-интерфейсов устранения международных доменных имен (IDN) Майкрософт, которые больше не доступны для скачивания.

Требования

Требование Значение
Минимальная версия клиента 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)

IdnToNameprepUnicode

IdnToUnicode

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

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