NormalizeString, fonction (winnls.h)

Article
08/27/2023

Normalise les caractères d’une chaîne de texte selon Unicode 4.0 TR#15. Pour plus d’informations, consultez Utilisation de la normalisation Unicode pour représenter des chaînes.

Syntaxe

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

Paramètres

[in] NormForm

Formulaire de normalisation à utiliser. NORM_FORM spécifie les formulaires de normalisation Unicode standard.

[in] lpSrcString

Pointeur vers la chaîne source non normalisée.

[in] cwSrcLength

Longueur, en caractères, de la mémoire tampon contenant la chaîne source. L’application peut définir ce paramètre sur -1 si la fonction doit supposer que la chaîne est terminée par null et calculer automatiquement la longueur.

[out, optional] lpDstString

Pointeur vers une mémoire tampon dans laquelle la fonction récupère la chaîne de destination. Ce paramètre contient également la valeur NULL si cwDstLength a la valeur 0.

Note La fonction n’arrête pas null la chaîne 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 la chaîne de sortie, l’application doit spécifier -1 ou compter explicitement le caractère null de fin pour la chaîne d’entrée.

[in] cwDstLength

Longueur, en caractères, de la mémoire tampon contenant la chaîne de destination. L’application peut également définir ce paramètre sur 0 pour demander à la fonction de retourner la taille requise pour la mémoire tampon de destination.

Valeur retournée

Retourne la longueur de la chaîne normalisée dans la mémoire tampon de destination. Si cwDstLength a la valeur 0, la fonction retourne la longueur estimée de la mémoire tampon nécessaire pour effectuer la conversion réelle.

Si la chaîne dans la mémoire tampon d’entrée est terminée par null ou si cwSrcLength a la valeur -1, la chaîne écrite dans la mémoire tampon de destination est terminée par null et la longueur de chaîne retournée inclut le caractère null de fin.

La fonction retourne une valeur inférieure ou égale à 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_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. La valeur de retour est la valeur négative de l’index de l’emplacement de l’erreur dans la chaîne d’entrée.
ERROR_SUCCESS. L’action s’est terminée avec succès, mais n’a produit aucun résultat.

Remarques

Certains caractères Unicode ont plusieurs représentations binaires équivalentes composées d’ensembles de caractères Unicode combinés et/ou composites. La norme Unicode définit un processus appelé normalisation qui retourne une représentation binaire lorsqu’elle est donnée à l’une des représentations binaires équivalentes d’un caractère. La normalisation peut être effectuée avec plusieurs algorithmes, appelés formulaires de normalisation, qui obéissent à différentes règles, comme décrit dans Utilisation de la normalisation Unicode pour représenter des chaînes. Win32 et .NET Framework prennent actuellement en charge les formulaires de normalisation C, D, KC et KD, comme défini dans l’annexe standard Unicode #15 : Formulaires de normalisation Unicode. Les chaînes normalisées sont généralement évaluées avec une comparaison ordinale.

Le code suivant illustre l’utilisation de l’estimation de la longueur de la mémoire tampon :

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

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.

Exemples

Vous trouverez un exemple montrant l’utilisation de cette fonction dans NLS : Exemple de normalisation Unicode.

Configuration requise


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)
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, ouWindows Server 2003 avec SP1