Función IdnToAscii (winnls.h)

  • Artículo

Convierte un nombre de dominio internacionalizado (IDN) u otra etiqueta internacionalizada en una representación Unicode (carácter ancho) de la cadena ASCII que representa el nombre en la sintaxis de codificación de transferencia punycode.

Precaución Esta función implementa el algoritmo estándar RFC 3490: Internationalizing Domain Names in Applications (IDNA) para convertir un IDN en Punycode. El estándar presenta algunos problemas de seguridad. Un problema es que los glifos que representan determinados caracteres de scripts diferentes pueden parecerse o incluso idénticos. Por ejemplo, en muchas fuentes, el A cirílico en minúsculaS ("а") es indistinguible de la letra A minúscula latina ("a"). No hay ninguna manera de indicar visualmente que "example.com" y "exа mple.com" son dos nombres de dominio diferentes, uno con una letra A minúscula latina en el nombre, la otra con un A cirílico en minúsculas. Para obtener más información sobre los problemas de seguridad relacionados con IDN, consulte Control de nombres de dominio internacionalizados (IDN).

 

Sintaxis

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

Parámetros

[in] dwFlags

Marcas que especifican opciones de conversión. En la tabla siguiente se enumeran los valores posibles.

Valor Significado
IDN_ALLOW_UNASSIGNED
Nota Una aplicación puede establecer este valor si simplemente usa una cadena de consulta para la búsqueda normal, como en una operación de comparación. Sin embargo, la aplicación no debe establecer este valor para una cadena almacenada, que es una cadena que se está preparando para el almacenamiento.
 
Permitir que los puntos de código sin asignar se incluyan en la cadena de entrada. El valor predeterminado es no permitir puntos de código sin asignar y producir un error extendido de ERROR_INVALID_NAME.

Esta marca permite que la función procese caracteres que no son legales actualmente en idN, pero que podrían ser legales en versiones posteriores del estándar IDNA. Si la aplicación codifica puntos de código sin asignar como Punycode, los nombres de dominio resultantes deben ser ilegales. La seguridad se puede poner en peligro si una versión posterior de IDNA hace que estos nombres sean legales o si una aplicación filtra los caracteres no válidos para intentar crear un nombre de dominio legal. Para obtener más información, consulte Control de nombres de dominio internacionalizados (IDN).
IDN_USE_STD3_ASCII_RULES
 Filtre los caracteres ASCII que no están permitidos en nombres STD3. Los únicos caracteres ASCII permitidos en la cadena Unicode de entrada son letras, dígitos y guiones menos. La cadena no puede comenzar ni terminar con el guion menos. La función produce un error si la cadena Unicode de entrada contiene caracteres ASCII, como "[", "]" o "/", que no se pueden producir en nombres de dominio.
Nota Algunas redes locales pueden permitir algunos de estos caracteres en nombres de equipo.
 

La función produce un error si la cadena Unicode de entrada contiene caracteres de control (U+0001 a U+0020) o el carácter "delete" (U+007F). En cualquier caso, esta marca no tiene ningún efecto en los caracteres no ASCII permitidos en la cadena Unicode.
IDN_EMAIL_ADDRESS
 A partir de Windows 8: habilite la reserva algorítmica de EAI para las partes locales de direcciones de correo electrónico (como <local>@microsoft.com). El valor predeterminado es que esta función produzca un error cuando una dirección de correo electrónico tenga una sintaxis o una dirección no válidas.

Una aplicación puede establecer esta marca para habilitar Email Internacionalización de direcciones (EAI) para devolver una dirección de reserva detectable, si es posible. Para obtener más información, consulte la Carta de internacionalización de direcciones (eai) de IETF Email.
IDN_RAW_PUNYCODE
 A partir de Windows 8: deshabilite la validación y asignación de Punycode.

[in] lpUnicodeCharStr

Puntero a una cadena Unicode que representa un IDN u otra etiqueta internacionalizada.

[in] cchUnicodeChar

Recuento de caracteres de la cadena Unicode de entrada indicada por lpUnicodeCharStr.

[out, optional] lpASCIICharStr

Puntero a un búfer que recibe una cadena Unicode que consta solo de caracteres en el juego de caracteres ASCII. Al devolver de esta función, el búfer contiene la cadena ASCII equivalente de la cadena proporcionada en lpUnicodeCharStr en Punycode. Como alternativa, la función puede recuperar NULL para este parámetro, si cchASCIIChar está establecido en 0. En este caso, la función devuelve el tamaño necesario para este búfer.

[in] cchASCIIChar

Tamaño del búfer indicado por lpASCIICharStr. La aplicación puede establecer el parámetro en 0 para recuperar NULL en lpASCIICharStr.

Valor devuelto

Devuelve el número de caracteres recuperados en lpASCIICharStr si se ejecuta correctamente. La cadena recuperada solo termina en null si la cadena Unicode de entrada está terminada en null.

Si la función se ejecuta correctamente y el valor de cchASCIIChar es 0, la función devuelve el tamaño necesario, en caracteres, incluido un carácter nulo de terminación si formaba parte del búfer de entrada.

La función devuelve 0 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

  • ERROR_INSUFFICIENT_BUFFER. Un tamaño de búfer proporcionado no era lo suficientemente grande o se estableció incorrectamente en NULL.
  • ERROR_INVALID_FLAGS. Los valores proporcionados para las marcas no eran válidos.
  • ERROR_INVALID_NAME. Se proporcionó un nombre no válido a la función . Tenga en cuenta que este código de error detecta todos los errores de sintaxis.
  • ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.
  • ERROR_NO_UNICODE_TRANSLATION. Se encontró unicode no válido en una cadena.

Comentarios

La función no termina en null una cadena de salida si la longitud de la cadena de entrada se especifica explícitamente sin un carácter nulo de terminación. Para finalizar null una cadena de salida para esta función, la aplicación debe proporcionar -1 para el parámetro cchUnicodeChar o contar explícitamente el carácter nulo de terminación para la cadena de entrada.

Tenga en cuenta que la función siempre produce un error si la cadena de entrada contiene caracteres de control (U+0001 a U+0020) o el carácter "delete" (U+007F). Dado que el carácter U+0000 solo puede aparecer como carácter nulo de terminación, la función siempre produce un error si U+0000 aparece en cualquier otro lugar de la cadena de entrada.

Windows XP, Windows Server 2003:

Ya no se admite.

El archivo de encabezado y dll necesarios forman parte de las API de mitigación de nombres de dominio internacionalizados (IDN) de Microsoft, que ya no están disponibles para su descarga.

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado winnls.h (incluya Windows.h)
Library Normaliz.lib
Archivo DLL Normaliz.dll
Redistribuible API de mitigación de nombres de dominio internacionalizados (IDN) de Microsoft enWindows XP con SP2 y versiones posteriores, Windows Server 2003 con SP1

Consulte también

Control de nombres de dominio internacionalizados (IDN)

IdnToNameprepUnicode

IdnToUnicode

Compatibilidad con idiomas nacionales

Funciones de compatibilidad con idiomas nacionales