Fonction WideCharToMultiByte (stringapiset.h)

Mappe une chaîne UTF-16 (caractère large) à 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 qu’elle reçoit.

Les données converties d’UTF-16 vers des encodages non Unicode sont sujettes à une perte de données, car une page de code peut ne pas être en mesure de représenter chaque caractère utilisé 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 code 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, comme UTF-8 ou UTF-16, au lieu d’une page de code 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 marquer 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 code à utiliser pour effectuer la conversion. Ce paramètre peut être défini sur la valeur de n’importe quelle page de code installée ou disponible dans le système d’exploitation. Pour obtenir la liste des pages de code, consultez Identificateurs de page de code. Votre application peut également spécifier l’une des valeurs indiquées dans le tableau suivant.

Valeur Signification
CP_ACP
Page de code ANSI Windows 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 code 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 code 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 code de symbole (42).
CP_THREAD_ACP
Windows 2000 : Page de code ANSI Windows pour le thread actif.
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 quand un mécanisme de transport 7 bits est forcé. L’utilisation d’UTF-8 est recommandée. Avec cette valeur définie, lpDefaultChar et lpUsedDefaultChar doivent avoir la valeur NULL.
CP_UTF8
UTF-8. Avec 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 seront manquants.

Valeur Signification
WC_COMPOSITECHECK
Convertissez des caractères composites, composés d’un caractère de base et d’un caractère non espacé, 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 non espacé.
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-non-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 Ignorez les caractères non espacés pendant la conversion.
WC_SEPCHARS Par défaut. Générez 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 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 dernière erreur avec un appel à GetLastError. Si cet indicateur n’est pas défini, la fonction remplace les séquences non autorisées par U+FFFD (encodées en fonction de la page de code 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 code.
WC_NO_BEST_FIT_CHARS
Traduire 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 multioctet et de nouveau en Unicode ne produit 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 dont la sémantique est très différente. Dans certains cas, la modification sémantique peut être extrême. Par exemple, le symbole « ∞ » (infini) correspond à 8 (huit) dans certaines pages de code.

 

Pour les pages de code 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 codes 65001 (UTF-8) ou la page de codes 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 est défini sur 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 codes 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 système par défaut, 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 codes 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 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.
  • 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 ne termine pas null-une chaîne de sortie si la longueur de la chaîne d’entrée est explicitement spécifiée 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 est défini sur 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 ont la valeur 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 système par défaut 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’appuient sur ce comportement pour encoder des données binaires aléatoires non textuelles peut se produire 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, la majuscule A avec dieresis (umlaut) peut être représentée précomposée en tant que point de code Unicode unique « Ä » (U+00C4) ou décomposée en tant que combinaison de majuscule A et du caractère de dierèse combiné (« A » + « ̈ », c’est-à-dire U+0041 U+0308). Toutefois, la plupart des pages de codes 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 de tenter de les composer avant de les convertir en page de codes demandée. Cet indicateur est uniquement disponible pour la conversion en pages de codes SBCS (single octet) ou double octet (DBCS) (pages < de codes 50000, à l’exclusion de la page de codes 42). Si votre application doit convertir des données Unicode décomposées en pages de codes codés sur un octet 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 ces données au format Unicode.

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

   
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