Partager via


WideCharToMultiByte, fonction (stringapiset.h)

Mappe une chaîne UTF-16 (caractères larges) à une nouvelle chaîne de caractères. La nouvelle chaîne de caractères ne provient pas nécessairement d’un jeu de caractères multioctets.

Attention L’utilisation incorrecte de la fonction WideCharToMultiByte peut compromettre la sécurité de votre application. L’appel de cette fonction peut facilement entraîner un dépassement de mémoire tampon, car la taille de la mémoire tampon d’entrée indiquée par lpWideCharStr est égale au nombre de caractères dans la chaîne Unicode, tandis que la taille de la mémoire tampon de sortie indiquée par lpMultiByteStr est égale au nombre d’octets. Pour éviter un dépassement de mémoire tampon, votre application doit spécifier une taille de mémoire tampon appropriée pour le type de données que la mémoire tampon reçoit.

Les données converties d’UTF-16 en encodages non Unicode sont sujettes à une perte de données, car une page de codes peut ne pas être en mesure de représenter tous les caractères utilisés dans les données Unicode spécifiques. Pour plus d’informations, consultez Considérations relatives à la sécurité : fonctionnalités internationales.

 
Note Les pages de codes ANSI peuvent être différentes sur différents ordinateurs ou être modifiées pour un seul ordinateur, ce qui entraîne une altération des données. Pour obtenir les résultats les plus cohérents, les applications doivent utiliser Unicode, par exemple UTF-8 ou UTF-16, au lieu d’une page de codes spécifique, sauf si des normes ou des formats de données hérités empêchent l’utilisation d’Unicode. Si l’utilisation d’Unicode n’est pas possible, les applications doivent baliser le flux de données avec le nom d’encodage approprié lorsque les protocoles l’autorisent. Les fichiers HTML et XML autorisent l’étiquetage, mais pas les fichiers texte.
 

Syntaxe

int WideCharToMultiByte(
  [in]            UINT                               CodePage,
  [in]            DWORD                              dwFlags,
  [in]            _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
  [in]            int                                cchWideChar,
  [out, optional] LPSTR                              lpMultiByteStr,
  [in]            int                                cbMultiByte,
  [in, optional]  LPCCH                              lpDefaultChar,
  [out, optional] LPBOOL                             lpUsedDefaultChar
);

Paramètres

[in] CodePage

Page de codes à utiliser pour effectuer la conversion. Ce paramètre peut être défini sur la valeur de n’importe quelle page de codes installée ou disponible dans le système d’exploitation. Pour obtenir la liste des pages de codes, consultez Identificateurs de page de codes. Votre application peut également spécifier l’une des valeurs indiquées dans le tableau suivant.

Valeur Signification
CP_ACP
Page de codes WINDOWS ANSI par défaut.
Note Cette valeur peut être différente sur différents ordinateurs, même sur le même réseau. Il peut être modifié sur le même ordinateur, ce qui entraîne une corruption irrécupérable des données stockées. Cette valeur est uniquement destinée à une utilisation temporaire et le stockage permanent doit utiliser UTF-16 ou UTF-8 si possible.
 
CP_MACCP
Page de codes Macintosh du système actuel.
Note Cette valeur peut être différente sur différents ordinateurs, même sur le même réseau. Il peut être modifié sur le même ordinateur, ce qui entraîne une corruption irrécupérable des données stockées. Cette valeur est uniquement destinée à une utilisation temporaire et le stockage permanent doit utiliser UTF-16 ou UTF-8 si possible.
 
Note Cette valeur est principalement utilisée dans le code hérité et ne doit généralement pas être nécessaire, car les ordinateurs Macintosh modernes utilisent Unicode pour l’encodage.
 
CP_OEMCP
Page de codes OEM du système actuel.
Note Cette valeur peut être différente sur différents ordinateurs, même sur le même réseau. Il peut être modifié sur le même ordinateur, ce qui entraîne une corruption irrécupérable des données stockées. Cette valeur est uniquement destinée à une utilisation temporaire et le stockage permanent doit utiliser UTF-16 ou UTF-8 si possible.
 
CP_SYMBOL
Windows 2000 : Page de codes symboles (42).
CP_THREAD_ACP
Windows 2000 : Page de codes Windows ANSI pour le thread actuel.
Note Cette valeur peut être différente sur différents ordinateurs, même sur le même réseau. Il peut être modifié sur le même ordinateur, ce qui entraîne une corruption irrécupérable des données stockées. Cette valeur est uniquement destinée à une utilisation temporaire et le stockage permanent doit utiliser UTF-16 ou UTF-8 si possible.
 
CP_UTF7
UTF-7. Utilisez cette valeur uniquement lorsque vous êtes forcé par un mécanisme de transport 7 bits. L’utilisation d’UTF-8 est recommandée. Une fois cette valeur définie, lpDefaultChar et lpUsedDefaultChar doivent avoir la valeur NULL.
CP_UTF8
UTF-8. Une fois cette valeur définie, lpDefaultChar et lpUsedDefaultChar doivent avoir la valeur NULL.

[in] dwFlags

Indicateurs indiquant le type de conversion. L’application peut spécifier une combinaison des valeurs suivantes. La fonction s’exécute plus rapidement lorsqu’aucun de ces indicateurs n’est défini. L’application doit spécifier WC_NO_BEST_FIT_CHARS et WC_COMPOSITECHECK avec la valeur spécifique WC_DEFAULTCHAR pour récupérer tous les résultats de conversion possibles. Si les trois valeurs ne sont pas fournies, certains résultats sont manquants.

Valeur Signification
WC_COMPOSITECHECK
Convertir des caractères composites, constitués d’un caractère de base et d’un caractère sans espacement, chacun avec des valeurs de caractères différentes. Traduisez ces caractères en caractères précomposés, qui ont une valeur de caractère unique pour une combinaison de caractères de base sans espacement. Par exemple, dans le caractère è, le e est le caractère de base et la marque grave d’accentuation est le caractère sans espacement.
Note Windows représente normalement des chaînes Unicode avec des données précomposées, ce qui rend inutile l’utilisation de l’indicateur WC_COMPOSITECHECK.
 

Votre application peut combiner WC_COMPOSITECHECK avec l’un des indicateurs suivants, la valeur par défaut étant WC_SEPCHARS. Ces indicateurs déterminent le comportement de la fonction lorsqu’aucun mappage précomposé pour une combinaison de caractères de base sans espacement dans une chaîne Unicode n’est disponible. Si aucun de ces indicateurs n’est fourni, la fonction se comporte comme si l’indicateur WC_SEPCHARS était défini. Pour plus d’informations, consultez WC_COMPOSITECHECK et indicateurs associés dans la section Remarques .

WC_DEFAULTCHAR Remplacez les exceptions par le caractère par défaut pendant la conversion.
WC_DISCARDNS Supprimez les caractères non espacés pendant la conversion.
WC_SEPCHARS Par défaut. Générer des caractères distincts pendant la conversion.
 
WC_ERR_INVALID_CHARS
Windows Vista et versions ultérieures : Échec (en retournant 0 et en définissant le code de la dernière erreur sur ERROR_NO_UNICODE_TRANSLATION) si un caractère d’entrée non valide est rencontré. Vous pouvez récupérer le code de la dernière erreur avec un appel à GetLastError. Si cet indicateur n’est pas défini, la fonction remplace les séquences non conformes par U+FFFD (encodées en fonction de la page de codes spécifiée) et réussit en retournant la longueur de la chaîne convertie. Notez que cet indicateur s’applique uniquement lorsque CodePage est spécifié comme CP_UTF8 ou 54936. Il ne peut pas être utilisé avec d’autres valeurs de page de codes.
WC_NO_BEST_FIT_CHARS
Traduisez tous les caractères Unicode qui ne se traduisent pas directement en équivalents multioctets au caractère par défaut spécifié par lpDefaultChar. En d’autres termes, si la traduction d’Unicode en multioctets et de nouveau en Unicode ne génère pas le même caractère Unicode, la fonction utilise le caractère par défaut. Cet indicateur peut être utilisé seul ou en combinaison avec les autres indicateurs définis.

Pour les chaînes qui nécessitent une validation, telles que les noms de fichier, de ressource et d’utilisateur, l’application doit toujours utiliser l’indicateur WC_NO_BEST_FIT_CHARS. Cet indicateur empêche la fonction de mapper des caractères à des caractères qui semblent similaires, mais qui ont une sémantique très différente. Dans certains cas, le changement sémantique peut être extrême. Par exemple, le symbole « ∞ » (infini) est mappé à 8 (huit) dans certaines pages de codes.

 

Pour les pages de codes répertoriées ci-dessous, dwFlags doit être 0. Sinon, la fonction échoue avec ERROR_INVALID_FLAGS.

  • 50220
  • 50221
  • 50222
  • 50225
  • 50227
  • 50229
  • 57002 à 57011
  • 65000 (UTF-7)
  • 42 (Symbole)
Note Pour la page de code 65001 (UTF-8) ou la page de code 54936 (GB18030, Windows Vista et versions ultérieures), dwFlags doit être défini sur 0 ou WC_ERR_INVALID_CHARS. Sinon, la fonction échoue avec ERROR_INVALID_FLAGS.
 

[in] lpWideCharStr

Pointeur vers la chaîne Unicode à convertir.

[in] cchWideChar

Taille, en caractères, de la chaîne indiquée par lpWideCharStr. Vous pouvez également définir ce paramètre sur -1 si la chaîne est terminée par null. Si cchWideChar a la valeur 0, la fonction échoue.

Si ce paramètre a la valeur -1, la fonction traite la chaîne d’entrée entière, y compris le caractère null de fin. Par conséquent, la chaîne de caractères résultante a un caractère null de fin, et la longueur retournée par la fonction inclut ce caractère.

Si ce paramètre est défini sur un entier positif, la fonction traite exactement le nombre de caractères spécifié. Si la taille fournie n’inclut pas de caractère null de fin, la chaîne de caractères résultante n’est pas terminée par null et la longueur retournée n’inclut pas ce caractère.

[out, optional] lpMultiByteStr

Pointeur vers une mémoire tampon qui reçoit la chaîne convertie.

[in] cbMultiByte

Taille, en octets, de la mémoire tampon indiquée par lpMultiByteStr. Si cette valeur est 0, la fonction retourne la taille de mémoire tampon requise, en octets, y compris tout caractère null de fin, et n’utilise pas la mémoire tampon lpMultiByteStr .

[in, optional] lpDefaultChar

Pointeur vers le caractère à utiliser si un caractère ne peut pas être représenté dans la page de code spécifiée. L’application définit ce paramètre sur NULL si la fonction doit utiliser une valeur système par défaut. Pour obtenir le caractère par défaut du système, l’application peut appeler la fonction GetCPInfo ou GetCPInfoEx .

Pour les paramètres CP_UTF7 et CP_UTF8 pour CodePage, ce paramètre doit avoir la valeur NULL. Sinon, la fonction échoue avec ERROR_INVALID_PARAMETER.

[out, optional] lpUsedDefaultChar

Pointeur vers un indicateur qui indique si la fonction a utilisé un caractère par défaut dans la conversion. L’indicateur a la valeur TRUE si un ou plusieurs caractères de la chaîne source ne peuvent pas être représentés dans la page de code spécifiée. Sinon, l’indicateur est défini sur FALSE. Ce paramètre peut être défini sur NULL.

Pour les paramètres CP_UTF7 et CP_UTF8 pour CodePage, ce paramètre doit avoir la valeur NULL. Sinon, la fonction échoue avec ERROR_INVALID_PARAMETER.

Valeur retournée

En cas de réussite, retourne le nombre d’octets écrits dans la mémoire tampon pointée par lpMultiByteStr. Si la fonction réussit et que cbMultiByte est 0, la valeur de retour est la taille requise, en octets, pour la mémoire tampon indiquée par lpMultiByteStr. Consultez également dwFlags pour plus d’informations sur la façon dont l’indicateur WC_ERR_INVALID_CHARS affecte la valeur de retour lorsque des séquences non valides sont entrées.

La 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 assez grande ou elle 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_NO_UNICODE_TRANSLATION. Unicode non valide a été trouvé dans une chaîne.

Remarques

Les pointeurs lpMultiByteStr et lpWideCharStr ne doivent pas être identiques. S’ils sont identiques, la fonction échoue et GetLastError retourne ERROR_INVALID_PARAMETER.

WideCharToMultiByte n’arrête pas null une chaîne de sortie si la longueur de chaîne d’entrée est spécifiée explicitement sans caractère null de fin. Pour terminer null une chaîne de sortie pour cette fonction, l’application doit passer -1 ou compter explicitement le caractère null de fin pour la chaîne d’entrée.

Si cbMultiByte est inférieur à cchWideChar, cette fonction écrit le nombre de caractères spécifié par cbMultiByte dans la mémoire tampon indiquée par lpMultiByteStr. Toutefois, si CodePage a la valeur CP_SYMBOL et que cbMultiByte est inférieur à cchWideChar, la fonction n’écrit aucun caractère dans lpMultiByteStr.

La fonction WideCharToMultiByte fonctionne plus efficacement lorsque lpDefaultChar et lpUsedDefaultChar sont définis sur NULL. Le tableau suivant montre le comportement de la fonction pour les quatre combinaisons possibles de ces paramètres.

lpDefaultChar lpUsedDefaultChar Résultats
NULL NULL Aucune vérification par défaut. Ces paramètres sont les plus efficaces pour une utilisation avec cette fonction.
Caractère non null NULL Utilise le caractère par défaut spécifié, mais ne définit pas lpUsedDefaultChar.
NULL Caractère non null Utilise le caractère par défaut du système et définit lpUsedDefaultChar si nécessaire.
Caractère non null Caractère non null Utilise le caractère par défaut spécifié et définit lpUsedDefaultChar si nécessaire.

À compter de Windows Vista, cette fonction est entièrement conforme à la spécification Unicode 4.1 pour UTF-8 et UTF-16. La fonction utilisée sur les systèmes d’exploitation antérieurs encode ou décode des moitiés de substitution solitaires ou des paires de substitution incompatibles. Le code écrit dans des versions antérieures de Windows qui s’appuie sur ce comportement pour encoder des données binaires aléatoires non textuelles peut rencontrer des problèmes. Toutefois, le code qui utilise cette fonction pour produire des chaînes UTF-8 valides se comporte de la même façon que sur les systèmes d’exploitation Windows antérieurs.

À compter de Windows 8 : WideCharToMultiByte est déclaré dans Stringapiset.h. Avant Windows 8, elle était déclarée dans Winnls.h.

WC_COMPOSITECHECK et indicateurs associés

Comme indiqué dans Utilisation de la normalisation Unicode pour représenter des chaînes, Unicode autorise plusieurs représentations de la même chaîne (interprétées linguistiquement). Par exemple, capital A avec dieresis (umlaut) peut être représenté soit précomposé comme un seul point de code Unicode « Ä » (U+00C4), soit décomposé en tant que combinaison de capital A et du caractère de dieresis combinant (« A » + « ̈ », c’est-à-dire U+0041 U+0308). Toutefois, la plupart des pages de code fournissent uniquement des caractères composés.

L’indicateur WC_COMPOSITECHECK permet à la fonction WideCharToMultiByte de tester les caractères Unicode décomposés et tente de les composer avant de les convertir en page de code demandée. Cet indicateur est disponible uniquement pour la conversion en pages de code sBCS (single octet) ou double octet (DBCS) (pages < de code 50000, à l’exclusion de la page de code 42). Si votre application doit convertir des données Unicode décomposées en pages de code à un ou deux octets, cet indicateur peut être utile. Toutefois, tous les caractères ne peuvent pas être convertis de cette façon et il est plus fiable d’enregistrer et de stocker des données telles qu’Unicode.

Lorsqu’une application utilise WC_COMPOSITECHECK, certaines combinaisons de caractères peuvent rester incomplètes ou contenir des caractères de non-espacement supplémentaires. Par exemple, A + ̈ + ̈ se combine à Ä + ̈. L’utilisation de l’indicateur WC_DISCARDNS entraîne l’abandon de caractères non interlignes supplémentaires par la fonction. L’utilisation de l’indicateur WC_DEFAULTCHAR entraîne l’utilisation du caractère de remplacement par défaut (généralement « ? »). L’utilisation de l’indicateur WC_SEPCHARS entraîne la tentative de conversion de chaque caractère de non-espace supplémentaire dans la page de code cible. Généralement, cet indicateur entraîne également l’utilisation du caractère de remplacement (« ? »). Toutefois, pour les pages de code 1258 (vietnamien) et 20269, des caractères non espacés existent et peuvent être utilisés. Les conversions de ces pages de code ne sont pas parfaites. Certaines combinaisons ne sont pas converties correctement en page de code 1258 et WC_COMPOSITECHECK endommage les données de la page de code 20269. Comme mentionné précédemment, il est plus fiable de concevoir votre application pour enregistrer et stocker des données telles que Unicode.

Exemples

ISDSC_STATUS DiscpUnicodeToAnsiSize(
    IN __in PWCHAR UnicodeString,
    OUT ULONG *AnsiSizeInBytes
    )
/*++
Routine Description:
    This routine will return the length needed to represent the unicode
    string as ANSI
Arguments:
    UnicodeString is the unicode string whose ansi length is returned
    *AnsiSizeInBytes is number of bytes needed to represent unicode
        string as ANSI
Return Value:
    ERROR_SUCCESS or error code
--*/
{
    _try
    {
        *AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
                                               0,
                                               UnicodeString,
                                               -1,
                                               NULL,
                                               0, NULL, NULL);
    } _except(EXCEPTION_EXECUTE_HANDLER) {
        return(ERROR_NOACCESS);
    }
    return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête stringapiset.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

MultiByteToWideChar

Fonctions Unicode et jeu de caractères

Unicode et jeux de caractères

API Vertdll disponibles dans les enclaves VBS