Função IdnToAscii (winnls.h)

  • Artigo

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.

Cuidado Essa função implementa o algoritmo padrão RFC 3490: Internationalizing Domain Names in Applications (IDNA) para converter um IDN em Punycode. O padrão apresenta alguns problemas de segurança. Um problema é que os glifos que representam determinados caracteres de scripts diferentes podem parecer semelhantes ou até mesmo idênticos. Por exemplo, em muitas fontes, a letra minúscula cirílico A ("а") é indistinguível do latim minúsculo A ("a"). Não há como dizer visualmente que "example.com" e "exа mple.com" são dois nomes de domínio diferentes, um com um latino em letras minúsculas A no nome, o outro com uma letra minúscula cirílico A. Para obter mais informações sobre questões de segurança relacionadas a IDN, consulte Manipulando IDNs (nomes de domínio internacionalizados).

 

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
IDN_ALLOW_UNASSIGNED
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.
 
Permitir que pontos de código não atribuídos sejam incluídos na cadeia de caracteres de entrada. O padrão é não permitir pontos de código não atribuídos e falhar com um código de erro estendido de ERROR_INVALID_NAME.

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).
IDN_USE_STD3_ASCII_RULES
 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.
IDN_EMAIL_ADDRESS
 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).
IDN_RAW_PUNYCODE
 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

Confira também

Manipulando IDNs (nomes de domínio internacionalizados)

IdnToNameprepUnicode

IdnToUnicode

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional