LCMapStringW, fonction (winnls.h)

Article
08/27/2023

Pour un paramètre régional spécifié par l’identificateur, mappe une chaîne de caractères d’entrée à une autre à l’aide d’une transformation spécifiée, ou génère une clé de tri pour la chaîne d’entrée.

Note Pour des raisons d’interopérabilité, l’application doit préférer la fonction LCMapStringEx à la fonction LCMapString , car Microsoft migre vers l’utilisation de noms de paramètres régionaux au lieu d’identificateurs régionaux pour les nouveaux paramètres régionaux. Cette recommandation s’applique en particulier aux paramètres régionaux personnalisés, y compris ceux créés par Microsoft. Toute application qui sera exécutée uniquement sur Windows Vista et versions ultérieures doit utiliser LCMapStringEx.

Syntaxe

int LCMapStringW(
  [in]            LCID    Locale,
  [in]            DWORD   dwMapFlags,
  [in]            LPCWSTR lpSrcStr,
  [in]            int     cchSrc,
  [out, optional] LPWSTR  lpDestStr,
  [in]            int     cchDest
);

Paramètres

[in] Locale

Identificateur de paramètres régionaux qui spécifie les paramètres régionaux. Vous pouvez utiliser la macro MAKELCID pour créer un identificateur de paramètres régionaux ou utiliser l’une des valeurs prédéfinies suivantes.

Les identificateurs de paramètres régionaux personnalisés suivants sont également pris en charge.

[in] dwMapFlags

Indicateurs spécifiant le type de transformation à utiliser pendant le mappage de chaînes ou le type de clé de tri à générer. Pour obtenir des définitions détaillées, consultez le paramètre dwMapFlags de LCMapStringEx.

[in] lpSrcStr

Pointeur vers une chaîne source que la fonction mappe ou utilise pour la génération de clés de tri. Cette chaîne ne peut pas avoir une taille de 0.

[in] cchSrc

Taille, en caractères, de la chaîne source indiquée par lpSrcStr. La taille de la chaîne source peut inclure le caractère null de fin, mais n’est pas obligé de le faire. Si le caractère null de fin est inclus, le comportement de mappage de la fonction n’est pas considérablement affecté, car le caractère null de fin est considéré comme non triable et mappe toujours à lui-même.

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, si LCMapString est utilisé dans son mode de mappage de chaînes, la fonction calcule la longueur de chaîne elle-même et termine la chaîne mappée indiquée par lpDestStr.

L’application ne peut pas définir ce paramètre sur 0.

[out, optional] lpDestStr

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

Si l’application utilise la fonction pour générer une clé de tri (LCMAP_SORTKEY) :

La clé de tri est stockée dans la mémoire tampon et traitée comme un tableau opaque d’octets. Les valeurs stockées peuvent inclure 0 octet incorporé à n’importe quelle position.
La chaîne de destination peut contenir un nombre impair d’octets. L’indicateur LCMAP_BYTEREV inverse uniquement un nombre pair d’octets. Le dernier octet (placé en position impaire) dans la clé de tri n’est pas inversé.

Si l’appelant demande explicitement un sous-ensemble de la chaîne, la chaîne de destination n’inclut pas de caractère null de fin, sauf si l’appelant l’a spécifié dans cchDest.

Si cette fonction échoue, la mémoire tampon de destination peut contenir des résultats partiels ou aucun résultat du tout. Dans ce cas, tous les résultats doivent être considérés comme non valides.

Notes

Lorsque vous définissez LCMAP_UPPERCASE ou LCMAP_LOWERCASE, la chaîne de destination peut utiliser la même mémoire tampon que la chaîne source. Toutefois, cela est fortement déconseillé, car certaines conditions peuvent entraîner une longueur différente de la chaîne cased retournée.

[in] cchDest

Taille, en caractères, de la chaîne de destination indiquée par lpDestStr. Si l’application utilise la fonction pour le mappage de chaînes, elle fournit un nombre de caractères pour ce paramètre. 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.

Si l’application utilise la fonction pour générer une clé de tri, elle fournit un nombre d’octets pour la taille. Ce nombre d’octets doit inclure de l’espace pour la clé de tri 0x00 terminateur.

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 ou la clé de tri.

Valeur retournée

Si la fonction réussit lorsqu’elle est utilisée pour le mappage de chaînes, elle retourne le nombre de caractères dans la chaîne traduite (voir cchSrc et cchDest pour plus d’informations ).

Si la fonction réussit lorsqu’elle est utilisée pour le mappage de chaînes, elle retourne le nombre d’octets dans la clé de tri.

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_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_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

Consultez les remarques relatives à LCMapStringEx.

La version ANSI de LCMapString mappe les chaînes vers et depuis Unicode en fonction de la page de codes Windows (ANSI) par défaut associée aux paramètres régionaux spécifiés. Lorsque la version ANSI de cette fonction est utilisée avec des paramètres régionaux Unicode uniquement, la fonction peut réussir, car le système d’exploitation utilise la valeur CP_ACP, représentant la page de codes Windows ANSI par défaut du système. Toutefois, les caractères qui ne sont pas définis dans la page de codes système apparaissent dans la chaîne sous la forme d’un point d’interrogation (?).

Notes

L’en-tête winnls.h définit LCMapString en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


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	winnls.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll