GetStringScripts, fonction (winnls.h)

Article
08/27/2023

Fournit la liste des scripts utilisés dans la chaîne Unicode spécifiée.

Syntaxe

int GetStringScripts(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpString,
  [in]            int     cchString,
  [out, optional] LPWSTR  lpScripts,
  [in]            int     cchScripts
);

Paramètres

[in] dwFlags

Indicateurs spécifiant des options pour la récupération de script.

Valeur	Signification
GSS_ALLOW_INHERITED_COMMON	Récupérez les informations de script « Qaii » (INHERITED) et « Zyyy » (COMMON). Cet indicateur n’affecte pas le traitement des caractères non attribués. Ces caractères dans la chaîne d’entrée entraînent toujours l’apparition d’un « Zzzz » (script UNASSIGNED) dans la chaîne de script.

Note Par défaut, GetStringScripts ignore tous les caractères hérités ou communs dans la chaîne d’entrée indiquée par lpString. Si GSS_ALLOW_INHERITED_COMMON n’est pas défini, ni « Qaii » ni « Zyyy » n’apparaissent dans la chaîne de script, même si la chaîne d’entrée contient de tels caractères. Si GSS_ALLOW_INHERITED_COMMON est défini et si la chaîne d’entrée contient des caractères hérités et/ou communs, « Qaii » et/ou « Zyyy », respectivement, apparaissent dans la chaîne de script. Consultez la section Notes.

[in] lpString

Pointeur vers la chaîne Unicode à analyser.

[in] cchString

Taille, en caractères, de la chaîne Unicode indiquée par lpString. L’application définit ce paramètre sur -1 si la chaîne Unicode se termine par une valeur Null. Si l’application définit ce paramètre sur 0, la fonction récupère une chaîne Unicode null (L"\0 ») dans lpScripts et retourne 1.

[out, optional] lpScripts

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère une chaîne terminée par un caractère Null représentant une liste de scripts, à l’aide de la notation à 4 caractères utilisée dans la norme ISO 15924. Chaque nom de script se compose de quatre caractères latins, et les noms sont récupérés par ordre alphabétique. Chaque nom, y compris le dernier, est suivi d’un point-virgule.

Ce paramètre contient également la valeur NULL si cchScripts a la valeur 0. Dans ce cas, la fonction retourne la taille requise pour la mémoire tampon de script.

[in] cchScripts

Taille, en caractères, de la mémoire tampon de script indiquée par lpScripts.

L’application peut également définir ce paramètre sur 0. Dans ce cas, la fonction récupère NULL en lpScripts et retourne la taille requise pour la mémoire tampon de script.

Valeur retournée

Retourne le nombre de caractères récupérés dans la mémoire tampon de sortie, y compris un caractère null de fin, si réussite et cchScripts est défini sur une valeur différente de zéro. La fonction retourne 1 pour indiquer qu’aucun script n’a été trouvé, par exemple, lorsque la chaîne d’entrée contient uniquement des caractères COMMON ou INHERITED et que GSS_ALLOW_INHERITED_COMMON n’est pas défini. Étant donné que chaque script trouvé ajoute cinq caractères (quatre caractères + délimiteur), une opération mathématique simple fournit le nombre de scripts sous la forme (return_code - 1) / 5.

Si la fonction réussit et que la valeur de cchScripts est 0, la fonction retourne la taille requise, en caractères, y compris un caractère null de fin, pour la mémoire tampon de script. Le nombre de scripts est décrit ci-dessus.

Cette 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_BADDB. La fonction n’a pas pu accéder aux données. Cette situation ne doit normalement pas se produire et indique généralement une installation incorrecte, un problème de disque, ou autres.
ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas suffisamment grande ou a été incorrectement définie sur NULL.
ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

Cette fonction est utile dans le cadre d’une stratégie pour atténuer les problèmes de sécurité liés aux noms de domaine internationalisés (IDN).

La détermination du script est basée sur les valeurs de script publiées par le Consortium Unicode dans http://www.unicode.org/Public/4.1.0/ucd/Scripts.txt, sauf que les caractères non attribués ont la valeur « Zzzz » (UNASSIGNED) au lieu de « Zyyy » (COMMON).

Voici quelques exemples de comportement de cette fonction :

Chaîne d’entrée		dwFlags	lpScripts	scripts ;
Microsoft.com		0	Latn;	Latin
Microsoft.com		GSS_ALLOW_INHERITED_COMMON	Latn; Zyyy ;	Latin + Commun
Niño	004E 0069 0241 006F	GSS_ALLOW_INHERITED_COMMON	Latn;	Latin
Niño	UTILISE LETTRE MINUSCULE LATINE N AVEC TILDE	GSS_ALLOW_INHERITED_COMMON	Latn;	Latin
Niño	004E 0069 006E 0303 006F	GSS_ALLOW_INHERITED_COMMON	Latn; Qaïi ;	Latin + Hérité
Niño	Utilise COMBINING TILDE	GSS_ALLOW_INHERITED_COMMON	Latn; Qaïi ;	Latin + Hérité
Spооf	0053 0070 043e 043e 0066	0	Latn; Cyrl ;	Latin + Cyrillique
Spооf	Utilise UNE LETTRE MINUSCULE CYRILLIQUE O	0	Latn; Cyrl ;	Latin + Cyrillique
	U+f000	0	Zzzz;	Non affecté
	U+f000	GSS_ALLOW_INHERITED_COMMON	Zzzz;	Non affecté

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	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

DownlevelGetStringScripts

Gestion des noms de domaine internationalisés (IDN)

Prise en charge des langues nationales

Fonctions de prise en charge des langues nationales

VerifyScripts