FoldStringW, fonction (stringapiset.h)

Article
08/26/2023

Mappe une chaîne Unicode à une autre, en effectuant la transformation spécifiée. Pour obtenir une vue d’ensemble de l’utilisation des fonctions de chaîne, consultez Chaînes.

AttentionL’utilisation incorrecte de FoldString peut compromettre la sécurité de votre application. Les chaînes qui ne sont pas mappées correctement peuvent produire une entrée non valide. Testez les chaînes pour vous assurer qu’elles sont valides avant de les utiliser et fournir des gestionnaires d’erreurs. Pour plus d’informations, consultez Considérations relatives à la sécurité : fonctionnalités internationales.

Syntaxe

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Paramètres

[in] dwMapFlags

Indicateurs spécifiant le type de transformation à utiliser pendant le mappage de chaînes. Ce paramètre peut être une combinaison des valeurs suivantes.

Indicateur	Signification
MAP_COMPOSITE	Mapper les caractères accentués aux caractères décomposés, c’est-à-dire les caractères dans lesquels un caractère de base et un ou plusieurs caractères sans espacement ont chacun des valeurs de point de code distinctes. Par exemple, Ä est représenté par A + ̈ : LETTRE MAJUSCULE LATINE A (U+0041) + DIAERESIS COMBINANTE (U+0308). Cet indicateur équivaut au formulaire de normalisation D dans Windows Vista. Notez que cet indicateur ne peut pas être utilisé avec MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Développez tous les caractères de ligature afin qu’ils soient représentés par leur équivalent à deux caractères. Par exemple, la ligature « æ » (U+00e6) est étendue aux deux caractères « a » (U+0061) + « e » (U+0065). Cette valeur ne peut pas être combinée avec MAP_PRECOMPOSED ou MAP_COMPOSITE.
MAP_FOLDCZONE	Pliez les caractères de zone de compatibilité dans des équivalents Unicode standard. Cet indicateur équivaut au KD du formulaire de normalisation dans Windows Vista, si l’indicateur MAP_COMPOSITE est également défini. Si l’indicateur composite n’est pas défini (valeur par défaut), cet indicateur équivaut au formulaire de normalisation KC dans Windows Vista.
MAP_FOLDDIGITS	Mapper tous les chiffres aux caractères Unicode compris entre 0 et 9.
MAP_PRECOMPOSED	Mappez les caractères accentués aux caractères précomposés, dans lesquels l’accentuation et le caractère de base sont combinés en une seule valeur de caractère. Cet indicateur équivaut à la forme de normalisation C dans Windows Vista. Cette valeur ne peut pas être combinée avec MAP_COMPOSITE.

[in] lpSrcStr

Pointeur vers une chaîne source que la fonction mappe.

[in] cchSrc

Taille, en caractères, de la chaîne source indiquée par lpSrcStr, à l’exclusion du caractère null de fin. L’application peut définir le paramètre sur n’importe quelle valeur négative pour spécifier que la chaîne source se termine par un caractère Null. Dans ce cas, la fonction calcule automatiquement la longueur de chaîne et termine la chaîne mappée indiquée par lpDestStr.

[out, optional] lpDestStr

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère la chaîne mappée.

[in] cchDest

Taille, en caractères, de la chaîne de destination indiquée par lpDestStr. Si l’espace d’un caractère null de fin est inclus dans cchSrc, cchDest doit également inclure de l’espace pour un caractère null de fin.

L’application peut définir cchDest sur 0. Dans ce cas, la fonction n’utilise pas le paramètre lpDestStr et retourne la taille de mémoire tampon requise pour la chaîne mappée. Si l’indicateur MAP_FOLDDIGITS est spécifié, la valeur de retour correspond à la taille maximale requise, même si le nombre réel de caractères requis est inférieur à la taille maximale. Si la taille maximale n’est pas passée, la fonction échoue avec ERROR_INSUFFICIENT_BUFFER.

Valeur retournée

Retourne le nombre de caractères dans la chaîne traduite, y compris un caractère null de fin, en cas de réussite. Si la fonction réussit et que la valeur de cchDest est 0, la valeur de retour correspond à la taille de la mémoire tampon requise pour contenir la chaîne traduite, y compris un caractère null de fin.

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_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas suffisamment grande ou a été incorrectement définie sur NULL.
ERROR_INVALID_DATA. Les données n’étaient pas valides.
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.
ERROR_MOD_NOT_FOUND. Le module est introuvable.
ERROR_OUTOFMEMORY. L’espace de stockage disponible n’était pas suffisant pour effectuer cette opération.
ERROR_PROC_NOT_FOUND. La procédure requise est introuvable.

Remarques

Les valeurs des paramètres lpSrcStr et lpDestStr ne doivent pas être identiques. Si elles sont identiques, la fonction échoue avec ERROR_INVALID_PARAMETER.

La zone de compatibilité dans Unicode se compose de caractères de la plage 0xF900 par 0xFFEF qui sont affectés à des caractères d’autres normes d’encodage pour les caractères, mais qui sont en fait des variantes de caractères déjà dans Unicode. La zone de compatibilité est utilisée pour prendre en charge le mappage aller-retour à ces normes. Les applications peuvent utiliser l’indicateur MAP_FOLDCZONE pour éviter la prise en charge de la duplication de caractères dans la zone de compatibilité.

À compter de Windows Vista : Cette fonction prend en charge la normalisation Unicode. Tous les caractères de compatibilité Unicode sont mappés.

À compter de Windows Vista : Les transformations indiquées par les indicateurs MAP_FOLDCZONE, MAP_PRECOMPOSED et MAP_COMPOSITE utilisent les formulaires de normalisation Unicode KC, C et D (via la fonction NormalizeString ) pour effectuer les mappages.

À compter de Windows 8 : la version ANSI de la fonction est déclarée dans Winnls.h et la version Unicode est déclarée dans Stringapiset.h. Avant Windows 8, les deux versions étaient déclarées dans Winnls.h.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	stringapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll