IdnToAscii, fonction (winnls.h)
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.
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 |
|---|---|
|
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.
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). |
|
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. |
|
À 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). |
|
À 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)