LCMapStringW, fonction (winnls.h)
Pour les paramètres régionaux spécifiés 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.
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
[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é 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’a pas besoin 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 modifiable et est toujours mappé à 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 est terminée par null. Dans ce cas, si LCMapString est utilisé en mode de mappage de chaînes, la fonction calcule la longueur de la chaîne elle-même et met fin à 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 octets incorporés à 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é impair) 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.
Note
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 casée 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, 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 de retour
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 elle était 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’est pas valide.
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 elle était 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’est pas valide.
Remarques
Consultez les remarques pour LCMapStringEx.
La version ANSI de LCMapString mappe des 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 ANSI Windows 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 forme de point d’interrogation ( ?).
Note
L’en-tête winnls.h définit LCMapString comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winnls.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
gestion du tri dans vos applications