Fonction MultiByteToWideChar (stringapiset.h)
Mappe une chaîne de caractères à une chaîne UTF-16 (caractères larges). La chaîne de caractères ne provient pas nécessairement d’un jeu de caractères multioctets.
Syntaxe
int MultiByteToWideChar(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cbMultiByte)LPCCH lpMultiByteStr,
[in] int cbMultiByte,
[out, optional] LPWSTR lpWideCharStr,
[in] int cchWideChar
);
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, MB_PRECOMPOSED étant la valeur par défaut. MB_PRECOMPOSED et MB_COMPOSITE s’excluent mutuellement. MB_USEGLYPHCHARS et MB_ERR_INVALID_CHARS peuvent être définis quel que soit l’état des autres indicateurs.
| Valeur | Signification |
|---|---|
| MB_COMPOSITE | Utilisez toujours des caractères décomposés, c’est-à-dire des caractères dans lesquels un caractère de base et un ou plusieurs caractères sans espacement ont chacun des valeurs de point de code distinctes. Par exemple, Ä est représenté par A + ̈ : LETTRE MAJUSCULE LATINE A (U+0041) + DIAERESIS COMBINANTE (U+0308). Notez que cet indicateur ne peut pas être utilisé avec MB_PRECOMPOSED. |
| MB_ERR_INVALID_CHARS | Échec si un caractère d’entrée non valide est rencontré. À compter de Windows Vista, la fonction ne supprime pas les points de code non conformes si l’application ne définit pas cet indicateur, mais remplace les séquences non conformes par U+FFFD (encodées en fonction de la page de codes spécifiée). Windows 2000 avec SP4 et versions ultérieures, Windows XP : Si cet indicateur n’est pas défini, la fonction supprime silencieusement les points de code illégaux. Un appel à GetLastError retourne ERROR_NO_UNICODE_TRANSLATION. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Pour les pages de code répertoriées ci-dessous, dwFlags doit être défini sur 0. Sinon, la fonction échoue avec ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 à 57011
- 65000 (UTF-7)
- 42 (Symbole)
Notes
Pour UTF-8 ou la page de codes 54936 (GB18030, à compter de Windows Vista), dwFlags doit être défini sur 0 ou MB_ERR_INVALID_CHARS. Sinon, la fonction échoue avec ERROR_INVALID_FLAGS.
[in] lpMultiByteStr
Pointeur vers la chaîne de caractères à convertir.
[in] cbMultiByte
Taille, en octets, de la chaîne indiquée par le paramètre lpMultiByteStr . Vous pouvez également définir ce paramètre sur -1 si la chaîne est terminée par null. Notez que, si cbMultiByte 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 Unicode 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 d’octets spécifié. Si la taille fournie n’inclut pas de caractère Null de fin, la chaîne Unicode résultante n’est pas terminée par null et la longueur retournée n’inclut pas ce caractère.
[out, optional] lpWideCharStr
Pointeur vers une mémoire tampon qui reçoit la chaîne convertie.
[in] cchWideChar
Taille, en caractères, de la mémoire tampon indiquée par lpWideCharStr. Si cette valeur est 0, la fonction retourne la taille de mémoire tampon requise, en caractères, y compris tout caractère null de fin, et n’utilise pas la mémoire tampon lpWideCharStr .
Valeur retournée
Retourne le nombre de caractères écrits dans la mémoire tampon indiqué par lpWideCharStr en cas de réussite. Si la fonction réussit et que cchWideChar est 0, la valeur de retour est la taille requise, en caractères, pour la mémoire tampon indiquée par lpWideCharStr. Consultez également dwFlags pour plus d’informations sur la façon dont l’indicateur MB_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 : Un caractère Unicode non valide a été trouvé dans une chaîne.
Remarques
Le comportement par défaut de cette fonction consiste à traduire en une forme précomposée de la chaîne de caractères d’entrée. S’il n’existe pas de formulaire précomposé, la fonction tente de traduire en un formulaire composite.
L’utilisation de l’indicateur MB_PRECOMPOSED a très peu d’effet sur la plupart des pages de codes, car la plupart des données d’entrée sont déjà composées. Envisagez d’appeler NormalizeString après la conversion avec MultiByteToWideChar. NormalizeString fournit des données plus précises, standard et cohérentes, et peut également être plus rapide. Notez que pour l’énumération NORM_FORM passée à NormalizeString, NormalizationC correspond à MB_PRECOMPOSED et NormalizationD correspond à MB_COMPOSITE.
Comme mentionné dans la mise en garde ci-dessus, la mémoire tampon de sortie peut facilement être dépassée si cette fonction n’est pas d’abord appelée avec cchWideChar définie sur 0 afin d’obtenir la taille requise. Si l’indicateur MB_COMPOSITE est utilisé, la sortie peut être de trois caractères ou plus pour chaque caractère d’entrée.
Les pointeurs lpMultiByteStr et lpWideCharStr ne doivent pas être identiques. Si elles sont identiques, la fonction échoue et GetLastError retourne la valeur ERROR_INVALID_PARAMETER.
MultiByteToWideChar ne termine pas une chaîne de sortie avec null si la longueur de la 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.
La fonction échoue si MB_ERR_INVALID_CHARS est défini et qu’un caractère non valide est rencontré dans la chaîne source. Un caractère non valide est l’un des éléments suivants :
- Caractère qui n’est pas le caractère par défaut dans la chaîne source, mais qui se traduit par le caractère par défaut quand MB_ERR_INVALID_CHARS n’est pas défini.
- Pour les chaînes DBCS, caractère qui a un octet de début, mais pas d’octet de piste valide.
À 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 sur des chaînes UTF-8 valides se comporte de la même façon que sur les systèmes d’exploitation Windows antérieurs.
Windows XP : Pour éviter le problème de sécurité des versions non courtes de caractères UTF-8, MultiByteToWideChar supprime ces caractères.
À compter de Windows 8 :MultiByteToWideChar est déclaré dans Stringapiset.h. Avant Windows 8, elle était déclarée dans Winnls.h.
Exemple de code
catch (std::exception e)
{
// Save in-memory logging buffer to a log file on error.
::std::wstring wideWhat;
if (e.what() != nullptr)
{
int convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), NULL, 0);
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.resize(convertResult + 10);
convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), &wideWhat[0], (int)wideWhat.size());
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.insert(0, L"Exception occurred: ");
}
}
}
else
{
wideWhat = L"Exception occurred: Unknown.";
}
Platform::String^ errorMessage = ref new Platform::String(wideWhat.c_str());
// The session added the channel at level Warning. Log the message at
// level Error which is above (more critical than) Warning, which
// means it will actually get logged.
_channel->LogMessage(errorMessage, LoggingLevel::Error);
SaveLogInMemoryToFileAsync().then([=](StorageFile^ logFile) {
_logFileGeneratedCount++;
StatusChanged(this, ref new LoggingScenarioEventArgs(LoggingScenarioEventType::LogFileGenerated, logFile->Path->Data()));
}).wait();
}
Exemple d’exemples windows universels sur GitHub.
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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour