Função IdnToAscii (winnls.h)
Converte um IDN (nome de domínio internacionalizado) ou outro rótulo internacionalizado em uma representação Unicode (caractere largo) da cadeia de caracteres ASCII que representa o nome na sintaxe de codificação de transferência punycode.
Sintaxe
int IdnToAscii(
[in] DWORD dwFlags,
[in] LPCWSTR lpUnicodeCharStr,
[in] int cchUnicodeChar,
[out, optional] LPWSTR lpASCIICharStr,
[in] int cchASCIIChar
);
Parâmetros
[in] dwFlags
Sinalizadores que especificam opções de conversão. A tabela a seguir lista os valores possíveis.
| Valor | Significado |
|---|---|
|
Nota Um aplicativo pode definir esse valor se estiver apenas usando uma cadeia de caracteres de consulta para pesquisa normal, como em uma operação de comparação. No entanto, o aplicativo não deve definir esse valor para uma cadeia de caracteres armazenada, que é uma cadeia de caracteres que está sendo preparada para armazenamento.
Esse sinalizador permite que a função processe caracteres que atualmente não são legais em IDNs, mas que podem ser legais em versões posteriores do padrão IDNA. Se o aplicativo codificar pontos de código não atribuídos como Punycode, os nomes de domínio resultantes deverão ser ilegais. A segurança poderá ser comprometida se uma versão posterior do IDNA tornar esses nomes legais ou se um aplicativo filtrar os caracteres ilegais para tentar criar um nome de domínio legal. Para obter mais informações, consulte Manipulando nomes de domínio internacionalizados (IDNs). |
|
Filtre caracteres ASCII que não são permitidos em nomes STD3. Os únicos caracteres ASCII permitidos na cadeia de caracteres Unicode de entrada são letras, dígitos e hífen-menos. A cadeia de caracteres não pode começar ou terminar com o hífen-menos. A função falhará se a cadeia de caracteres Unicode de entrada contiver caracteres ASCII, como "[", "]" ou "/", que não podem ocorrer em nomes de domínio. Nota Algumas redes locais podem permitir alguns desses caracteres em nomes de computador.
A função falhará se a cadeia de caracteres Unicode de entrada contiver caracteres de controle (U+0001 a U+0020) ou o caractere "delete" (U+007F). Em ambos os casos, esse sinalizador não tem efeito sobre os caracteres não ASCII permitidos na cadeia de caracteres Unicode. |
|
Começando com Windows 8: habilite o fallback algorítmico do EAI para as partes locais dos endereços de email (como <local>@microsoft.com). O padrão é que essa função falhe quando um endereço de email tiver um endereço ou sintaxe inválido.
Um aplicativo pode definir esse sinalizador para permitir que Email Address Internationalization (EAI) retorne um endereço de fallback detectável, se possível. Para obter mais informações, consulte a Carta IETF Email Address Internationalization (eai). |
|
Começando com Windows 8: desabilite a validação e o mapeamento do Punycode. |
[in] lpUnicodeCharStr
Ponteiro para uma cadeia de caracteres Unicode que representa um IDN ou outro rótulo internacionalizado.
[in] cchUnicodeChar
Contagem de caracteres na cadeia de caracteres Unicode de entrada indicada por lpUnicodeCharStr.
[out, optional] lpASCIICharStr
Ponteiro para um buffer que recebe uma cadeia de caracteres Unicode que consiste apenas em caracteres no conjunto de caracteres ASCII. No retorno dessa função, o buffer contém a cadeia de caracteres ASCII equivalente à cadeia de caracteres fornecida em lpUnicodeCharStr em Punycode. Como alternativa, a função poderá recuperar NULL para esse parâmetro, se cchASCIIChar estiver definido como 0. Nesse caso, a função retorna o tamanho necessário para esse buffer.
[in] cchASCIIChar
Tamanho do buffer indicado por lpASCIICharStr. O aplicativo pode definir o parâmetro como 0 para recuperar NULL em lpASCIICharStr.
Retornar valor
Retorna o número de caracteres recuperados em lpASCIICharStr se bem-sucedido. A cadeia de caracteres recuperada será terminada em nulo somente se a cadeia de caracteres Unicode de entrada for terminada em nulo.
Se a função for bem-sucedida e o valor de cchASCIIChar for 0, a função retornará o tamanho necessário, em caracteres, incluindo um caractere nulo de terminação se ele fizer parte do buffer de entrada.
A função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:
- ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou estava definido incorretamente como NULL.
- ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
- ERROR_INVALID_NAME. Um nome inválido foi fornecido à função. Observe que esse código de erro captura todos os erros de sintaxe.
- ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.
- ERROR_NO_UNICODE_TRANSLATION. Unicode inválido foi encontrado em uma cadeia de caracteres.
Comentários
A função não termina em nulo uma cadeia de caracteres de saída se o comprimento da cadeia de caracteres de entrada for especificado explicitamente sem um caractere nulo de terminação. Para encerrar nulo uma cadeia de caracteres de saída para essa função, o aplicativo deve fornecer -1 para o parâmetro cchUnicodeChar ou contar explicitamente o caractere nulo de terminação para a cadeia de caracteres de entrada.
Observe que a função sempre falhará se a cadeia de caracteres de entrada contiver caracteres de controle (U+0001 a U+0020) ou o caractere "delete" (U+007F). Como o caractere U+0000 pode aparecer apenas como um caractere nulo de terminação, a função sempre falhará se U+0000 aparecer em qualquer outro lugar na cadeia de caracteres de entrada.
Windows XP, Windows Server 2003:
Não tem mais suporte.
O arquivo de cabeçalho e a DLL necessários fazem parte das APIs de Mitigação de IDN (Nome de Domínio Internacionalizado) da Microsoft, que não estão mais disponíveis para download.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winnls.h (inclua Windows.h) |
| Biblioteca | Normaliz.lib |
| DLL | Normaliz.dll |
| Redistribuível | APIs de mitigação de IDN (Nome de Domínio Internacionalizado) da Microsoft noWindows XP com SP2 e posterior, Windows Server 2003 com SP1 |