NormalizeString, fonction (winnls.h)

Normalise les caractères d’une chaîne de texte en fonction d’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 doit être 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. Vous pouvez également définir ce paramètre sur NULL si cwDstLength a la valeur 0.

[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 est défini sur 0, la fonction retourne la longueur estimée de la mémoire tampon requise pour effectuer la conversion réelle.

Si la chaîne de 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 suffisamment grande, ou elle était incorrectement définie sur NULL .
• ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’est 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 de jeux de caractères Unicode combinés et/ou composites. La norme Unicode définit un processus appelé normalisation qui retourne une représentation binaire en fonction de 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 :

Non pris en charge.

Le fichier d’en-tête et la DLL requis font partie des API d’atténuation idN (Microsoft Internationalized Domain Name), qui ne sont plus disponibles pour le téléchargement.

Examples

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

Spécifications

Voir aussi

IsNormalizedString

NORM_FORM

prise en charge des langues nationales

fonctions de prise en charge des langues nationales

Utilisation de la normalisation Unicode pour représenter des chaînes