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