Funzione MultiByteToWideChar (stringapiset.h)
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.
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
Pagina 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 pagine codici, vedere Identificatori di tabella codici. L'applicazione può anche specificare uno dei valori illustrati nella tabella seguente.
[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 decomposti, ovvero i caratteri in cui un carattere di base e uno o più caratteri nonpacing 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 | Errore se viene rilevato un carattere di input non valido. A partire da Windows Vista, la funzione non elimina i punti di codice illegali se l'applicazione non imposta questo flag, ma sostituisce le sequenze illegali con U+FFFD (codificato come appropriato per la pagina codici specificata). Windows 2000 con SP4 e versioni successive, Windows XP: Se questo flag non è impostato, la funzione elimina in modo automatico i punti di codice non validi. Una chiamata a GetLastError restituisce ERROR_NO_UNICODE_TRANSLATION. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Per le pagine codici elencate di seguito, è necessario impostare dwFlags 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), è necessario impostare dwFlags 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 è terminata con 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 terminante. Pertanto, la stringa Unicode risultante ha un carattere null terminante e la lunghezza restituita dalla funzione include questo carattere.
Se questo parametro è impostato su un intero positivo, la funzione elabora esattamente il numero specificato di byte. Se le dimensioni specificate non includono un carattere Null terminante, la stringa Unicode risultante non viene terminata con valore 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 tutti i caratteri null terminanti e non usa il buffer lpWideCharStr .
Valore restituito
Restituisce il numero di caratteri scritti nel buffer indicato da lpWideCharStr se ha esito positivo. Se la funzione ha esito positivo e cchWideChar è , il valore restituito è 0la dimensione necessaria, in caratteri, per il buffer indicato da lpWideCharStr. Vedere anche dwFlags per informazioni sul modo in cui il flag MB_ERR_INVALID_CHARS influisce sul valore restituito quando le sequenze non valide sono di input.
La funzione restituisce 0 se non riesce. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:
- ERROR_INSUFFICIENT_BUFFER: una dimensione del buffer fornita non è sufficiente oppure è stata impostata in modo errato su
NULL. - ERROR_INVALID_FLAGS: i valori forniti per i flag non sono validi.
- ERROR_INVALID_PARAMETER: i valori dei parametri non sono validi.
- ERROR_NO_UNICODE_TRANSLATION: è stato trovato Unicode non valido in una stringa.
Commenti
Il comportamento predefinito di questa funzione consiste nel tradurre in una forma precomposta della stringa di caratteri di input. Se non esiste un modulo precomposto, la funzione tenta di tradurre in una forma composita.
L'uso del flag di MB_PRECOMPOSED ha molto poco effetto sulla maggior parte delle pagine codici perché la maggior parte dei dati di input è già composta. Prendere in considerazione la chiamata di NormalString dopo la conversione con MultiByteToWideChar. NormalString offre dati più accurati, standard e coerenti e possono anche essere più veloci. Si noti che per l'enumerazione NORM_FORM passata a NormalString, NormalizationC corrisponde a MB_PRECOMPOSED e NormalizationD corrisponde a MB_COMPOSITE.
Come accennato in precedenza, il buffer di output può essere facilmente superato 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ò essere di 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 terminante. Per terminare una stringa di output per questa funzione, l'applicazione deve passare in modo esplicito -1 o contare in modo esplicito il carattere null terminante 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 si traduce nel carattere predefinito quando MB_ERR_INVALID_CHARS non è impostato.
- Per le stringhe DBCS, un carattere con un byte di lead ma nessun 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 le metà surrogate solitarie o coppie surrogate non corrispondenti. Il codice scritto nelle versioni precedenti di Windows che si basano su questo comportamento per codificare dati binari non testuali casuali potrebbe verificarsi problemi. Tuttavia, il codice che usa questa funzione in stringhe UTF-8 valide si comporta come nei 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 è 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.
Requisiti
| 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 | Windows |
| Intestazione | stringapiset.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per