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.

Pour les pages de codes 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)

[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 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 NULLsur .
• 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.

Les pages de codes ANSI peuvent être différentes sur différents ordinateurs ou peuvent être modifiées pour un seul ordinateur, ce qui entraîne une altération des données. Pour les résultats les plus cohérents, les applications doivent utiliser Unicode, comme UTF-8 ou UTF-16, au lieu d’une page de codes spécifique, sauf si les normes ou les 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 les fichiers texte ne le font pas.

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 0 pour 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.

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.

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

MultiByteToWideChar ne met pas fin à 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. Fonction utilisée sur des systèmes d’exploitation antérieurs encode ou décode les moitiés de substitution solitaires ou les 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 sans forme la plus courte des caractères UTF-8, MultiByteToWideChar supprime ces caractères.

À compter 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 d’exemples windows universels sur GitHub.

Exigences

Voir aussi

Fonctions Unicode et jeu de caractères

Jeux de caractères et Unicode

WideCharToMultiByte

API Vertdll disponibles dans les enclaves VBS