Función IdnToAscii (winnls.h)
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.
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 |
|---|---|
|
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.
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). |
|
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. |
|
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. |
|
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)