Fonction MultiByteToWideChar (stringapiset.h)
Mappe une chaîne de caractères à une chaîne UTF-16 (caractère large). 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, avec 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 indépendamment de 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 non interlignes ont chacun des valeurs de point de code distinctes. Par exemple, Ä est représenté par A + ̈ : LETTRE MAJUSCULE LATINE A (U+0041) + COMBINAISON DIAERÈSE (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 autorisés si l’application ne définit pas cet indicateur, mais remplace plutôt les séquences illégales 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égal. Un appel à GetLastError retourne ERROR_NO_UNICODE_TRANSLATION. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Pour les pages de codes répertoriées ci-dessous, dwFlags doit être définie sur 0. Sinon, la fonction échoue avec ERROR_INVALID_FLAGS.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 à 57011
- 65000 (UTF-7)
- 42 (Symbole)
Note
Pour UTF-8 ou la page de codes 54936 (GB18030, à partir de Windows Vista), dwFlags doivent être définis 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 est 0, la fonction échoue.
Si ce paramètre est -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 spécifié d’octets. 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 de retour
Retourne le nombre de caractères écrits dans la mémoire tampon indiquée 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 de MB_ERR_INVALID_CHARS affecte la valeur de retour lorsque les 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 elle était incorrectement définie sur
NULL. - ERROR_INVALID_FLAGS: les valeurs fournies pour les indicateurs n’étaient pas valides.
- ERROR_INVALID_PARAMETER: toutes les valeurs de paramètre n’étaient pas valides.
- ERROR_NO_UNICODE_TRANSLATION: Unicode non valide a été trouvé dans une chaîne.
Remarques
Le comportement par défaut de cette fonction consiste à se traduire en une forme précomposée de la chaîne de caractères d’entrée. Si un formulaire précomposé n’existe pas, la fonction tente de se traduire en formulaire composite.
L’utilisation de l’indicateur de 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 longs 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 si la longueur de la chaîne d’entrée est spécifiée explicitement sans caractère null de fin. Pour mettre fin à une chaîne de sortie pour cette fonction, l’application doit passer -1 ou compter explicitement le caractère null de fin de la chaîne d’entrée.
La fonction échoue si MB_ERR_INVALID_CHARS est définie 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 se traduit par le caractère par défaut lorsque MB_ERR_INVALID_CHARS n’est pas défini.
- Pour les chaînes DBCS, caractère qui a un octet de prospect, mais pas d’octet de fin 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 précédents encode ou décode les paires de substitution moitiés ou paires de substitution incompatibles. Le code écrit dans les versions antérieures de Windows qui s’appuient sur ce comportement pour encoder des données binaires non textuelles aléatoires peut rencontrer 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 abrégées des caractères UTF-8, MultiByteToWideChar supprime ces caractères.
à partir de Windows 8 :MultiByteToWideChar est déclaré dans Stringapiset.h. Avant Windows 8, il a été déclaré 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 de exemples windows universels sur GitHub.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | stringapiset.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
fonctions Unicode et jeu de caractères