Funzione MultiByteToWideChar (stringapiset.h)

Articolo
07/16/2024

Esegue il mapping di una stringa di caratteri a una stringa UTF-16 (carattere wide). La stringa di caratteri non è necessariamente da un set di caratteri multibyte.

Attenzione Uso della funzione multiByteToWideChar può compromettere erroneamente la sicurezza dell'applicazione. La chiamata a questa funzione può causare facilmente un sovraccarico del buffer perché le dimensioni del buffer di input indicate da lpMultiByteStr uguale al numero di byte nella stringa, mentre le dimensioni del buffer di output indicate da lpWideCharStr uguale al numero di caratteri. Per evitare un sovraccarico del buffer, l'applicazione deve specificare una dimensione del buffer appropriata per il tipo di dati ricevuto dal buffer. Per altre informazioni, vedere Considerazioni sulla sicurezza: Funzionalità internazionali.

Nota Le tabelle codici ANSI possono essere diverse in computer diversi o possono essere modificate per un singolo computer, causando il danneggiamento dei dati. Per i risultati più coerenti, le applicazioni devono usare Unicode, ad esempio UTF-8 o UTF-16, anziché una tabella codici specifica, a meno che gli standard legacy o i formati di dati non impediscano l'uso di Unicode. Se non è possibile usare Unicode, le applicazioni devono contrassegnarlo con il nome di codifica appropriato quando i protocolli lo consentono. I file HTML e XML consentono l'assegnazione di tag, ma i file di testo non lo sono.

Sintassi

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
);

Parametri

[in] CodePage

Tabella codici da usare per eseguire la conversione. Questo parametro può essere impostato sul valore di qualsiasi tabella codici installata o disponibile nel sistema operativo. Per un elenco di tabelle codici, vedere identificatori della tabella codici . L'applicazione può anche specificare uno dei valori illustrati nella tabella seguente.

Valore	Significato
CP_ACP	Tabella codici ANSI di Windows predefinita del sistema. Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificata nello stesso computer, portando a archiviare i dati che diventano irreversibilmente danneggiati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
CP_MACCP	Tabella codici Macintosh di sistema corrente. Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificata nello stesso computer, portando a archiviare i dati che diventano irreversibilmente danneggiati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile. Nota Questo valore viene usato principalmente nel codice legacy e in genere non deve essere necessario perché i computer Macintosh moderni usano Unicode per la codifica.
CP_OEMCP	Tabella codici OEM di sistema corrente. Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificata nello stesso computer, portando a archiviare i dati che diventano irreversibilmente danneggiati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
CP_SYMBOL	Tabella codici simbolo (42).
CP_THREAD_ACP	Tabella codici ANSI di Windows per il thread corrente. Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificata nello stesso computer, portando a archiviare i dati che diventano irreversibilmente danneggiati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
CP_UTF7	UTF-7. Utilizzare questo valore solo quando viene forzato da un meccanismo di trasporto a 7 bit. L'uso di UTF-8 è preferibile.
CP_UTF8	UTF-8.

[in] dwFlags

Flag che indicano il tipo di conversione. L'applicazione può specificare una combinazione dei valori seguenti, con MB_PRECOMPOSED come impostazione predefinita. MB_PRECOMPOSED e MB_COMPOSITE si escludono a vicenda. MB_USEGLYPHCHARS e MB_ERR_INVALID_CHARS possono essere impostati indipendentemente dallo stato degli altri flag.

Valore	Significato
MB_COMPOSITE	Usare sempre i caratteri scomposti, ovvero i caratteri in cui un carattere di base e uno o più caratteri non inpacing hanno valori di punto di codice distinti. Ad esempio, Ä è rappresentato da A + ̈: LETTERA MAIUSCOLA LATINA A (U+0041) + COMBINAZIONE DIAERESIS (U+0308). Si noti che questo flag non può essere usato con MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	Esito negativo se viene rilevato un carattere di input non valido. A partire da Windows Vista, la funzione non rilascia punti di codice non validi se l'applicazione non imposta questo flag, ma sostituisce invece sequenze non valide con U+FFFD (codificato come appropriato per la tabella codici specificata). Windows 2000 con SP4 e versioni successive, Windows XP: Se questo flag non è impostato, la funzione elimina automaticamente punti di codice non validi. Una chiamata a GetLastError restituisce ERROR_NO_UNICODE_TRANSLATION.

Valore

Significato

MB_COMPOSITE

Usare sempre i caratteri scomposti, ovvero i caratteri in cui un carattere di base e uno o più caratteri non inpacing hanno valori di punto di codice distinti. Ad esempio, Ä è rappresentato da A + ̈: LETTERA MAIUSCOLA LATINA A (U+0041) + COMBINAZIONE DIAERESIS (U+0308). Si noti che questo flag non può essere usato con MB_PRECOMPOSED.

MB_ERR_INVALID_CHARS

Esito negativo se viene rilevato un carattere di input non valido.

A partire da Windows Vista, la funzione non rilascia punti di codice non validi se l'applicazione non imposta questo flag, ma sostituisce invece sequenze non valide con U+FFFD (codificato come appropriato per la tabella codici specificata).

Windows 2000 con SP4 e versioni successive, Windows XP: Se questo flag non è impostato, la funzione elimina automaticamente punti di codice non validi. Una chiamata a GetLastError restituisce ERROR_NO_UNICODE_TRANSLATION.

MB_PRECOMPOSED

Default; non usare con MB_COMPOSITE. Usare sempre caratteri precompisi, ovvero i caratteri con un singolo valore di carattere per una combinazione di caratteri base o nonpacing. Ad esempio, nel carattere è, l'e è il carattere di base e il segno di gravità principale è il carattere nonpacing. Se per un carattere è definito un singolo punto di codice Unicode, l'applicazione deve usarla invece di un carattere di base separato e di un carattere non di formattazione. Ad esempio, Ä è rappresentato dal singolo punto di codice Unicode MAIUSCOLA LATIN LETTERA A WITH DIAERESIS (U+00C4).

MB_USEGLYPHCHARS

Usare i caratteri glifi anziché i caratteri di controllo.

Per le tabelle codici elencate di seguito, dwFlags deve essere impostato su 0. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_FLAGS.

50220
50221
50222
50225
50227
50229
Da 57002 a 57011
65000 (UTF-7)
42 (simbolo)

Nota

Per UTF-8 o tabella codici 54936 (GB18030, a partire da Windows Vista), dwFlags deve essere impostato su 0 o MB_ERR_INVALID_CHARS. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_FLAGS.

[in] lpMultiByteStr

Puntatore alla stringa di caratteri da convertire.

[in] cbMultiByte

Dimensioni, in byte, della stringa indicata dal parametro lpMultiByteStr. In alternativa, questo parametro può essere impostato su -1 se la stringa è con terminazione Null. Si noti che, se cbMultiByte è 0, la funzione ha esito negativo.

Se questo parametro è -1, la funzione elabora l'intera stringa di input, incluso il carattere null di terminazione. Pertanto, la stringa Unicode risultante ha un carattere Null di terminazione e la lunghezza restituita dalla funzione include questo carattere.

Se questo parametro è impostato su un numero intero positivo, la funzione elabora esattamente il numero specificato di byte. Se le dimensioni specificate non includono un carattere Null di terminazione, la stringa Unicode risultante non termina con null e la lunghezza restituita non include questo carattere.

[out, optional] lpWideCharStr

Puntatore a un buffer che riceve la stringa convertita.

[in] cchWideChar

Dimensioni, in caratteri, del buffer indicato da lpWideCharStr. Se questo valore è 0, la funzione restituisce le dimensioni del buffer necessarie, in caratteri, inclusi i caratteri null di terminazione e non usa il buffer lpWideCharStr.

Valore restituito

Restituisce il numero di caratteri scritti nel buffer indicato da lpWideCharStr in caso di esito positivo. Se la funzione ha esito positivo e cchWideChar 0, il valore restituito è la dimensione richiesta, in caratteri, per il buffer indicato da lpWideCharStr. Vedi anche dwFlags per informazioni su come il flag MB_ERR_INVALID_CHARS influisce sul valore restituito quando vengono immesse sequenze non valide.

La funzione restituisce 0 se non riesce. Per ottenere informazioni estese sull'errore, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER: le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_FLAGS: i valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER: uno dei valori dei parametri non è valido.
ERROR_NO_UNICODE_TRANSLATION: è stato trovato Unicode non valido in una stringa.

Osservazioni

Il comportamento predefinito di questa funzione consiste nel convertire in una forma precomposta della stringa di caratteri di input. Se non esiste un modulo precomposto, la funzione tenta di convertire in un formato composito.

L'uso del flag MB_PRECOMPOSED ha molto poco effetto sulla maggior parte delle tabelle codici perché la maggior parte dei dati di input è già composta. È consigliabile chiamare NormalizeString dopo la conversione con MultiByteToWideChar. NormalizeString fornisce dati più accurati, standard e coerenti e può anche essere più veloce. Si noti che per l'enumerazione NORM_FORM passata a NormalizeString, NormalizationC corrisponde a MB_PRECOMPOSED e NormalizationD corrisponde a MB_COMPOSITE.

Come indicato nell'avviso precedente, il buffer di output può essere facilmente sovraccaricato se questa funzione non viene prima chiamata con cchWideChar impostata su 0 per ottenere le dimensioni necessarie. Se viene usato il flag MB_COMPOSITE, l'output può contenere tre o più caratteri per ogni carattere di input.

I puntatori lpMultiByteStr e lpWideCharStr non devono essere uguali. Se sono uguali, la funzione ha esito negativo e GetLastError restituisce il valore ERROR_INVALID_PARAMETER.

MultiByteToWideChar non termina una stringa di output se la lunghezza della stringa di input viene specificata in modo esplicito senza un carattere Null di terminazione. Per terminare null una stringa di output per questa funzione, l'applicazione deve passare -1 o contare in modo esplicito il carattere null di terminazione per la stringa di input.

La funzione ha esito negativo se MB_ERR_INVALID_CHARS è impostato e viene rilevato un carattere non valido nella stringa di origine. Un carattere non valido è uno dei seguenti:

Carattere che non è il carattere predefinito nella stringa di origine, ma viene convertito nel carattere predefinito quando MB_ERR_INVALID_CHARS non è impostato.
Per le stringhe DBCS, un carattere con un byte iniziale ma senza byte finale valido.

A partire da Windows Vista, questa funzione è completamente conforme alla specifica Unicode 4.1 per UTF-8 e UTF-16. La funzione usata nei sistemi operativi precedenti codifica o decodifica lone surrogato metà o coppie di surrogati non corrispondenti. Il codice scritto nelle versioni precedenti di Windows che si basano su questo comportamento per codificare dati binari non di testo casuali potrebbe riscontrare problemi. Tuttavia, il codice che usa questa funzione in stringhe UTF-8 valide avrà lo stesso comportamento dei sistemi operativi Windows precedenti.

Windows XP: Per evitare il problema di sicurezza delle versioni non più brevi dei caratteri UTF-8, MultiByteToWideChar elimina questi caratteri.

A partire da Windows 8:MultiByteToWideChar viene dichiarato in Stringapiset.h. Prima di Windows 8, è stato dichiarato in Winnls.h.

Esempio di codice

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();
}

Esempio di esempi universali di Windows in GitHub.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	stringapiset.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

funzioni unicode e set di caratteri

set di caratteri e Unicode

WideCharToMultiByte

API Vertdll disponibili nelle enclave VBS

Condividi tramite