LCMapStringEx, fonction (winnls.h)
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.
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.
Les indicateurs répertoriés ci-dessous sont utilisés uniquement avec l’indicateur LCMAP_SORTKEY.
[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 |
Voir aussi
Gestion du tri dans vos applications