IdnToAscii, fonction (winnls.h)

  • Article

Convertit un nom de domaine internationalisé (IDN) ou une autre étiquette internationalisée en une représentation Unicode (caractères larges) de la chaîne ASCII qui représente le nom dans la syntaxe d’encodage de transfert Punycode.

Attention Cette fonction implémente l’algorithme standard RFC 3490 : Internationalizing Domain Names in Applications (IDNA) pour convertir un IDN en Punycode. La norme introduit certains problèmes de sécurité. Un problème est que les glyphes représentant certains caractères de différents scripts peuvent apparaître similaires, voire identiques. Par exemple, dans de nombreuses polices, la minuscule cyrillique A (« а ») ne peut pas être déduite du minuscule latin A (« a »). Il n’existe aucun moyen de dire visuellement que « example.com » et « exа mple.com » sont deux noms de domaine différents, l’un avec un minuscule latin A dans le nom, l’autre avec une minuscule cyrillique A. Pour plus d’informations sur les problèmes de sécurité liés à l’IDN, consultez Gestion des noms de domaine internationalisés (IDN).

 

Syntaxe

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

Paramètres

[in] dwFlags

Indicateurs spécifiant les options de conversion. Le tableau suivant répertorie les valeurs possibles.

Valeur Signification
IDN_ALLOW_UNASSIGNED
Note Une application peut définir cette valeur si elle utilise simplement une chaîne de requête pour une recherche normale, comme dans une opération de comparaison. Toutefois, l’application ne doit pas définir cette valeur pour une chaîne stockée, qui est une chaîne en cours de préparation pour le stockage.
 
Autoriser l’inclusion de points de code non attribués dans la chaîne d’entrée. La valeur par défaut consiste à ne pas autoriser les points de code non attribués et à échouer avec un code d’erreur étendu de ERROR_INVALID_NAME.

Cet indicateur permet à la fonction de traiter des caractères qui ne sont pas actuellement légaux dans les IDN, mais qui peuvent être légaux dans les versions ultérieures de la norme IDNA. Si votre application encode des points de code non attribués en Tant que Punycode, les noms de domaine résultants doivent être non autorisés. La sécurité peut être compromise si une version ultérieure d’IDNA rend ces noms légaux ou si une application filtre les caractères non autorisés pour tenter de créer un nom de domaine légal. Pour plus d’informations, consultez Gestion des noms de domaine internationalisés (IDN).
IDN_USE_STD3_ASCII_RULES
 Filtrez les caractères ASCII qui ne sont pas autorisés dans les noms STD3. Les seuls caractères ASCII autorisés dans la chaîne Unicode d’entrée sont les lettres, les chiffres et le trait d’union-moins. La chaîne ne peut pas commencer ou se terminer par le trait d’union-moins. La fonction échoue si la chaîne Unicode d’entrée contient des caractères ASCII, tels que « [ », « ] » ou « / », qui ne peuvent pas se produire dans les noms de domaine.
Note Certains réseaux locaux peuvent autoriser certains de ces caractères dans les noms d’ordinateurs.
 

La fonction échoue si la chaîne Unicode d’entrée contient des caractères de contrôle (U+0001 à U+0020) ou le caractère « delete » (U+007F). Dans les deux cas, cet indicateur n’a aucun effet sur les caractères non ASCII autorisés dans la chaîne Unicode.
IDN_EMAIL_ADDRESS
 À compter de Windows 8 : activez le secours algorithmique EAI pour les parties locales des adresses e-mail (telles que <local>@microsoft.com). La valeur par défaut est que cette fonction échoue lorsqu’une adresse e-mail a une adresse ou une syntaxe non valide.

Une application peut définir cet indicateur pour permettre à Email’internationalisation d’adresses (EAI) de retourner une adresse de secours détectable, si possible. Pour plus d’informations, consultez la charte IETF Email Address Internationalization (eai).
IDN_RAW_PUNYCODE
 À compter de Windows 8 : désactivez la validation et le mappage de Punycode.

[in] lpUnicodeCharStr

Pointeur vers une chaîne Unicode représentant un IDN ou une autre étiquette internationalisée.

[in] cchUnicodeChar

Nombre de caractères dans la chaîne Unicode d’entrée indiquée par lpUnicodeCharStr.

[out, optional] lpASCIICharStr

Pointeur vers une mémoire tampon qui reçoit une chaîne Unicode composée uniquement de caractères dans le jeu de caractères ASCII. Au retour de cette fonction, la mémoire tampon contient la chaîne ASCII équivalente à la chaîne fournie dans lpUnicodeCharStr sous Punycode. La fonction peut également récupérer null pour ce paramètre, si cchASCIIChar a la valeur 0. Dans ce cas, la fonction retourne la taille requise pour cette mémoire tampon.

[in] cchASCIIChar

Taille de la mémoire tampon indiquée par lpASCIICharStr. L’application peut définir le paramètre sur 0 pour récupérer NULL dans lpASCIICharStr.

Valeur retournée

Retourne le nombre de caractères récupérés dans lpASCIICharStr en cas de réussite. La chaîne récupérée est terminée par null uniquement si la chaîne Unicode d’entrée est terminée par null.

Si la fonction réussit et que la valeur de cchASCIIChar est 0, la fonction retourne la taille requise, en caractères incluant un caractère null de fin s’il faisait partie de la mémoire tampon d’entrée.

La fonction retourne 0 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

  • ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas assez grande ou elle a été incorrectement définie sur NULL.
  • ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
  • ERROR_INVALID_NAME. Un nom non valide a été fourni à la fonction. Notez que ce code d’erreur intercepte toutes les erreurs de syntaxe.
  • ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.
  • ERROR_NO_UNICODE_TRANSLATION. Unicode non valide a été trouvé dans une chaîne.

Remarques

La fonction ne termine pas de chaîne de sortie par null si la longueur de la chaîne d’entrée est spécifiée explicitement sans caractère null de fin. Pour arrêter null une chaîne de sortie pour cette fonction, l’application doit fournir -1 pour le paramètre cchUnicodeChar ou compter explicitement le caractère null de fin pour la chaîne d’entrée.

Notez que la fonction échoue toujours si la chaîne d’entrée contient des caractères de contrôle (U+0001 à U+0020) ou le caractère « delete » (U+007F). Étant donné que le caractère U+0000 peut apparaître uniquement sous forme de caractère null de fin, la fonction échoue toujours si U+0000 apparaît ailleurs dans la chaîne d’entrée.

Windows XP, Windows Server 2003 :

N'est plus pris en charge.

Le fichier d’en-tête et la DLL requis font partie des API d’atténuation des noms de domaine internationalisés (IDN) Microsoft, qui ne sont plus disponibles en téléchargement.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête winnls.h (inclure Windows.h)
Bibliothèque Normaliz.lib
DLL Normaliz.dll
Composant redistribuable API d’atténuation des noms de domaine internationalisés (IDN) Microsoft surWindows XP avec SP2 et versions ultérieures, Windows Server 2003 avec SP1

Voir aussi

Gestion des noms de domaine internationalisés (IDN)

IdnToNameprepUnicode

IdnToUnicode

Prise en charge des langues nationales

Fonctions de prise en charge des langues nationales