LCMapStringEx, fonction (winnls.h)

Article
08/27/2023

Pour un paramètre régional spécifié par nom, 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 L’application doit appeler cette fonction de préférence à LCMapString si elle est conçue pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Syntaxe

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Paramètres

[in, optional] lpLocaleName

Pointeur vers un nom de paramètres régionaux ou l’une des valeurs prédéfinies suivantes.

[in] dwMapFlags

Indicateur spécifiant le type de transformation à utiliser pendant le mappage de chaînes ou le type de clé de tri à générer. Ce paramètre peut avoir les valeurs suivantes.

Indicateur	Signification
LCMAP_BYTEREV	Utilisez l’inversion d’octets. Par exemple, si l’application passe 0x3450 0x4822, le résultat est 0x5034 0x2248.
LCMAP_FULLWIDTH	Utilisez des caractères Unicode (larges), le cas échéant. Cet indicateur et ce LCMAP_HALFWIDTH s’excluent mutuellement. Avec cet indicateur, le mappage peut utiliser le formulaire de normalisation C même si un caractère d’entrée est déjà en pleine largeur. Par exemple, la chaîne « は゛ » (qui est déjà en pleine chasse) est normalisée en « ば ». Consultez Unicode normalization forms.
LCMAP_HALFWIDTH	Utilisez des caractères étroits le cas échéant. Cet indicateur et LCMAP_FULLWIDTH s’excluent mutuellement.
LCMAP_HIRAGANA	Mapper tous les caractères katakana à hiragana. Cet indicateur et LCMAP_KATAKANA s’excluent mutuellement.
LCMAP_KATAKANA	Mapper tous les caractères hiragana aux katakana. Cet indicateur et LCMAP_HIRAGANA s’excluent mutuellement.
LCMAP_LINGUISTIC_CASING	Utilisez des règles linguistiques pour la casse au lieu des règles de système de fichiers (par défaut). Cet indicateur est valide avec LCMAP_LOWERCASE ou LCMAP_UPPERCASE uniquement.
LCMAP_LOWERCASE	Pour les paramètres régionaux et les scripts capables de gérer les majuscules et minuscules, mappez tous les caractères en minuscules.
LCMAP_HASH	Retourne un hachage des poids de tri brut d’une chaîne. Les chaînes qui apparaissent comme équivalentes retournent généralement le même hachage (par exemple, « hello » et « HELLO » avec LCMAP_IGNORECASE). Toutefois, certains cas complexes, comme les langues d’Asie de l’Est, peuvent avoir des chaînes similaires avec des pondérations identiques qui se comparent comme étant égales, mais ne retournent pas le même hachage. LCMAP_HASH nécessite que la mémoire tampon de sortie soit de taille sizeof(int)
LCMAP_SIMPLIFIED_CHINESE	Mapper les caractères chinois traditionnels aux caractères chinois simplifiés. Cet indicateur et LCMAP_TRADITIONAL_CHINESE s’excluent mutuellement.
LCMAP_SORTHANDLE L’utilisation d’un handle de tri entraîne des améliorations minimales des performances et est déconseillée.	Retournez un jeton représentant les paramètres de tri résolus pour les paramètres régionaux (comme le nom des paramètres régionaux), afin que les `NULL` appels futurs puissent passer pour le nom de tri et passer le handle de tri précédemment interrogé comme dernier paramètre (sortHandle) dans les appels suivants à CompareStringEx ou LCMapStringEx. LCMAP_SORTHANDLE nécessite que la mémoire tampon de sortie soit de taille sizeof(lparam)
LCMAP_SORTKEY	Produire une clé de tri normalisée. Si l’indicateur LCMAP_SORTKEY n’est pas spécifié, la fonction effectue le mappage de chaînes. Pour plus d’informations sur la génération de clé de tri et le mappage de chaînes, consultez la section Remarques.
LCMAP_TITLECASE	Windows 7 : Mapper tous les caractères à la casse du titre, dans laquelle la première lettre de chaque mot principal est mise en majuscule.
LCMAP_TRADITIONAL_CHINESE	Mapper les caractères chinois simplifiés aux caractères chinois traditionnels. Cet indicateur et ce LCMAP_SIMPLIFIED_CHINESE s’excluent mutuellement.
LCMAP_UPPERCASE	Pour les paramètres régionaux et les scripts capables de gérer les majuscules et minuscules, mappez tous les caractères en majuscules.

Les indicateurs suivants peuvent être utilisés seuls, entre eux, ou avec les indicateurs LCMAP_SORTKEY et/ou LCMAP_BYTEREV. Toutefois, ils ne peuvent pas être combinés avec les autres indicateurs répertoriés ci-dessus.

Indicateur	Signification
NORM_IGNORENONSPACE	Ignorer les caractères sans espacement. Pour de nombreux scripts (notamment les scripts latins), NORM_IGNORENONSPACE coïncide avec LINGUISTIC_IGNOREDIACRITIC. Note NORM_IGNORENONSPACE ignore toute distinction secondaire, qu’elle soit diacritique ou non. Les scripts pour le coréen, le japonais, le chinois et les langues indiciques, entre autres, utilisent cette distinction à des fins autres que diacritiques. LINGUISTIC_IGNOREDIACRITIC fait en sorte que la fonction ignore uniquement les signes diacritiques réels, au lieu d’ignorer la deuxième pondération de tri.
NORM_IGNORESYMBOLS	Ignorer les symboles et la ponctuation.

Indicateur

Signification

NORM_IGNORENONSPACE

Ignorer les caractères sans espacement. Pour de nombreux scripts (notamment les scripts latins), NORM_IGNORENONSPACE coïncide avec LINGUISTIC_IGNOREDIACRITIC.

Note NORM_IGNORENONSPACE ignore toute distinction secondaire, qu’elle soit diacritique ou non. Les scripts pour le coréen, le japonais, le chinois et les langues indiciques, entre autres, utilisent cette distinction à des fins autres que diacritiques. LINGUISTIC_IGNOREDIACRITIC fait en sorte que la fonction ignore uniquement les signes diacritiques réels, au lieu d’ignorer la deuxième pondération de tri.

NORM_IGNORESYMBOLS

Ignorer les symboles et la ponctuation.

Les indicateurs répertoriés ci-dessous sont utilisés uniquement avec l’indicateur LCMAP_SORTKEY.

Indicateur	Signification
LINGUISTIC_IGNORECASE	Ignorer la casse, selon le cas linguistiquement approprié.
LINGUISTIC_IGNOREDIACRITIC	Ignorez les caractères non espacés, selon le cas sur le plan linguistique. Note Cet indicateur ne produit pas toujours des résultats prévisibles lorsqu’il est utilisé avec des caractères décomposés, c’est-à-dire des 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.
NORM_IGNORECASE	Ignorer la casse. Pour de nombreux scripts (notamment latins), NORM_IGNORECASE coïncide avec LINGUISTIC_IGNORECASE. Note NORM_IGNORECASE ignore toute distinction tertiaire, qu’il s’agisse de cas linguistique ou non. Par exemple, dans les écritures arabe et indic, cet indicateur distingue d’autres formes d’un caractère, mais les différences ne correspondent pas à la casse linguistique. LINGUISTIC_IGNORECASE fait en sorte que la fonction ignore uniquement la casse linguistique réelle, au lieu d’ignorer la troisième pondération de tri. Note Pour les paramètres régionaux de jeu de caractères codés sur deux octets (DBCS), NORM_IGNORECASE a un effet sur tous les caractères Unicode, ainsi que sur les caractères étroits (un octet), y compris les caractères grecs et cyrilliques.
NORM_IGNOREKANATYPE	Ne faites pas la différence entre les caractères hiragana et katakana. Les caractères hiragana et katakana correspondants sont égaux.
NORM_IGNOREWIDTH	Ignorez la différence entre les caractères de demi-largeur et de pleine largeur, par exemple, C a t == cat. Le formulaire pleine largeur est une distinction de mise en forme utilisée dans les scripts chinois et japonais.
NORM_LINGUISTIC_CASING	Utilisez des règles linguistiques pour la casse au lieu des règles de système de fichiers (par défaut).
SORT_DIGITSASNUMBERS	Windows 7 : Traitez les chiffres comme des nombres pendant le tri, par exemple, triez « 2 » avant « 10 ».
SORT_STRINGSORT	Traitez la ponctuation de la même façon que les symboles.

[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 ce 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 LCMapStringEx 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.

[in, optional] lpVersionInformation

Pointeur vers une structure NLSVERSIONINFOEX qui contient les informations de version sur la fonctionnalité NLS appropriée ; généralement récupéré à partir de GetNLSVersionEx.

Windows Vista, Windows 7 : Réservés au; doit avoir la valeur NULL.

[in, optional] lpReserved

Réservés au; doit être NULL.

[in, optional] sortHandle

Réservés au; doit être 0.

Notes

CompareStringEx et LCMapStringEx peuvent spécifier un handle de tri (si le nom des paramètres régionaux est null). Cette utilisation est déconseillée pour la plupart des applications.

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 générer une clé de tri, 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.

Remarques

L’application peut utiliser LCMapString ou LCMapStringEx pour générer une clé de tri. Pour ce faire, l’application spécifie LCMAP_SORTKEY pour le paramètre dwMapFlags . Pour plus d’informations, consultez Gestion du tri dans vos applications.

Notes

Les clés de tri sont des flux d’octets opaques. Les appelants doivent les traiter comme un tableau d’octets de la longueur retournée par l’API et ne pas s’appuyer sur une structure interne qui peut sembler présente. Zéro, un ou plusieurs octets de la clé de tri retournée peuvent être 0. L’absence ou la présence d’un octet égal à zéro ne doit pas être attendue.

Une autre façon pour votre application d’utiliser LCMapString ou LCMapStringEx consiste à utiliser des chaînes de mappage. Dans ce cas, l’application ne spécifie pas LCMAP_SORTKEY pour le paramètre dwMapFlags , mais fournit une autre combinaison d’indicateurs. Pour plus d’informations, consultez Gestion du tri dans vos applications.

À partir de Windows Vista : Cette fonction peut gérer des données à partir de paramètres régionaux personnalisés. Il n’est pas garanti que les données soient identiques d’un ordinateur à l’autre ou entre les exécutions d’une application. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

À partir de Windows 8 : si votre application transmet des balises de langue à cette fonction à partir de l’espace de noms Windows.Globalization, elle doit d’abord convertir les balises en appelant ResolveLocaleName.

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