LCMapStringW, fonction (winnls.h)

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.

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.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

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

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

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

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 (?).

Configuration requise

Voir aussi

CompareString

FindNLSString

GetNLSVersion

Gestion du tri dans vos applications

LCMapStringEx

Prise en charge des langues nationales

Fonctions de prise en charge des langues nationales