MultiByteToWideChar-Funktion (stringapiset.h)
Ordnet eine Zeichenfolge einer UTF-16 -Zeichenfolge (Breite Zeichen) zu. Die Zeichenfolge stammt nicht unbedingt aus einem Multibyte-Zeichensatz.
Syntax
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
);
Parameter
[in] CodePage
Codeseite, die beim Ausführen der Konvertierung verwendet werden soll. Dieser Parameter kann auf den Wert einer beliebigen Codeseite festgelegt werden, die im Betriebssystem installiert oder verfügbar ist. Eine Liste der Codeseiten finden Sie unter Code Page Identifiers. Ihre Anwendung kann auch einen der in der folgenden Tabelle gezeigten Werte angeben.
[in] dwFlags
Flags, die den Konvertierungstyp angeben. Die Anwendung kann eine Kombination der folgenden Werte angeben, wobei MB_PRECOMPOSED die Standardeinstellung ist. MB_PRECOMPOSED und MB_COMPOSITE schließen sich gegenseitig aus. MB_USEGLYPHCHARS und MB_ERR_INVALID_CHARS können unabhängig vom Status der anderen Flags festgelegt werden.
| Wert | Bedeutung |
|---|---|
| MB_COMPOSITE | Verwenden Sie immer dekompilierte Zeichen, d. h. Zeichen, in denen ein Basiszeichen und mindestens ein nicht übersteigendes Zeichen unterschiedliche Codepunktwerte aufweisen. Z. B. wird Ä durch A + ̈: LATIN CAPITAL LETTER A (U+0041) + COMBINING DIAERESIS (U+0308) dargestellt. Beachten Sie, dass dieses Flag nicht mit MB_PRECOMPOSED verwendet werden kann. |
| MB_ERR_INVALID_CHARS | Schlägt fehl, wenn ein ungültiges Eingabezeichen aufgetreten ist. Beginnend mit Windows Vista legt die Funktion keine ungültigen Codepunkte ab, wenn die Anwendung dieses Flag nicht festlegt, sondern ungültige Sequenzen durch U+FFFD ersetzt (entsprechend der angegebenen Codepage codiert). Windows 2000 mit SP4 und höher, Windows XP: Wenn dieses Flag nicht festgelegt ist, legt die Funktion im Hintergrund unzulässige Codepunkte ab. Ein Aufruf von GetLastError- gibt ERROR_NO_UNICODE_TRANSLATION zurück. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Für die unten aufgeführten Codeseiten muss dwFlags- auf 0festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGSfehl.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 bis 57011
- 65000 (UTF-7)
- 42 (Symbol)
Anmerkung
Für UTF-8 oder Codepage 54936 (GB18030 ab Windows Vista) muss dwFlags- entweder auf 0 oder MB_ERR_INVALID_CHARSfestgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGSfehl.
[in] lpMultiByteStr
Zeigen Sie auf die zu konvertierende Zeichenfolge.
[in] cbMultiByte
Größe der Zeichenfolge, die durch den parameter lpMultiByteStr in Bytes angegeben ist. Alternativ kann dieser Parameter auf -1 festgelegt werden, wenn die Zeichenfolge null beendet ist. Beachten Sie, dass die Funktion fehlschlägt, wenn cbMultiByte-0ist.
Wenn dieser Parameter -1 ist, verarbeitet die Funktion die gesamte Eingabezeichenfolge, einschließlich des endenden NULL-Zeichens. Daher weist die resultierende Unicode-Zeichenfolge ein endendes NULL-Zeichen auf, und die von der Funktion zurückgegebene Länge enthält dieses Zeichen.
Wenn dieser Parameter auf eine positive ganze Zahl festgelegt ist, verarbeitet die Funktion genau die angegebene Anzahl von Bytes. Wenn die angegebene Größe kein endendes NULL-Zeichen enthält, wird die resultierende Unicode-Zeichenfolge nicht null beendet, und die zurückgegebene Länge enthält dieses Zeichen nicht.
[out, optional] lpWideCharStr
Zeiger auf einen Puffer, der die konvertierte Zeichenfolge empfängt.
[in] cchWideChar
Größe des durch lpWideCharStrangegebenen Puffers in Zeichen. Wenn dieser Wert 0ist, gibt die Funktion die erforderliche Puffergröße in Zeichen zurück, einschließlich eines endenden Nullzeichens, und verwendet nicht den lpWideCharStr Puffer.
Rückgabewert
Gibt die Anzahl der Zeichen zurück, die in den Puffer geschrieben wurden, der durch lpWideCharStr angegeben ist, wenn dies erfolgreich war. Wenn die Funktion erfolgreich ist und cchWideChar-0ist, ist der Rückgabewert die erforderliche Größe in Zeichen für den puffer, der durch lpWideCharStrangegeben wird. Weitere Informationen dazu, wie sich das MB_ERR_INVALID_CHARS Flag auf den Rückgabewert auswirkt, wenn ungültige Sequenzen eingegeben werden, finden Sie unter dwFlags-.
Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastErroraufrufen, wodurch eine der folgenden Fehlercodes zurückgegeben werden kann:
-
ERROR_INSUFFICIENT_BUFFER: Eine angegebene Puffergröße war nicht groß genug, oder sie wurde fälschlicherweise auf
NULLfestgelegt. - ERROR_INVALID_FLAGS: Die für Flags angegebenen Werte waren ungültig.
- ERROR_INVALID_PARAMETER: Ungültige Parameterwerte.
- ERROR_NO_UNICODE_TRANSLATION: Ungültiges Unicode wurde in einer Zeichenfolge gefunden.
Bemerkungen
Das Standardverhalten dieser Funktion besteht darin, in eine vorkompilierte Form der Eingabezeichenzeichenfolge zu übersetzen. Wenn kein vorkompiliertes Formular vorhanden ist, versucht die Funktion, in ein zusammengesetztes Formular zu übersetzen.
Die Verwendung des MB_PRECOMPOSED-Flags wirkt sich nur sehr wenig auf die meisten Codeseiten aus, da die meisten Eingabedaten bereits erstellt wurden. Erwägen Sie, NormalizeString nach der Konvertierung mit MultiByteToWideChar-aufzurufen. NormalizeString bietet genauere, standard- und konsistentere Daten und kann auch schneller sein. Beachten Sie, dass für die NORM_FORM Enumeration, die an NormalizeStringübergeben wird, NormalizationC MB_PRECOMPOSED entspricht und NormalizationD MB_COMPOSITE entspricht.
Wie in der obigen Vorsicht erwähnt, kann der Ausgabepuffer problemlos überlaufen werden, wenn diese Funktion nicht zuerst mit cchWideChar aufgerufen wird, auf 0 festgelegt ist, um die erforderliche Größe zu erhalten. Wenn das MB_COMPOSITE-Flag verwendet wird, kann die Ausgabe für jedes Eingabezeichen drei oder mehr Zeichen lang sein.
Die lpMultiByteStr und lpWideCharStr Zeiger dürfen nicht identisch sein. Wenn sie identisch sind, schlägt die Funktion fehl, und GetLastError den Wert ERROR_INVALID_PARAMETER zurück.
MultiByteToWideChar- eine Ausgabezeichenfolge nicht null beendet, wenn die Länge der Eingabezeichenfolge explizit ohne endendes Nullzeichen angegeben wird. Um eine Ausgabezeichenfolge für diese Funktion null zu beenden, sollte die Anwendung -1 übergeben oder explizit das endende NULL-Zeichen für die Eingabezeichenfolge zählen.
Die Funktion schlägt fehl, wenn MB_ERR_INVALID_CHARS festgelegt ist und in der Quellzeichenfolge ein ungültiges Zeichen gefunden wird. Ein ungültiges Zeichen ist eine der folgenden:
- Ein Zeichen, das nicht das Standardzeichen in der Quellzeichenfolge ist, wird jedoch in das Standardzeichen übersetzt, wenn MB_ERR_INVALID_CHARS nicht festgelegt ist.
- Für DBCS-Zeichenfolgen ein Zeichen, das ein Leadbyte, aber kein gültiges Trailbyte enthält.
Ab Windows Vista entspricht diese Funktion vollständig der Unicode 4.1-Spezifikation für UTF-8 und UTF-16. Die auf früheren Betriebssystemen verwendete Funktion codiert oder decodiert Surrogate Hälften oder falsch übereinstimmenden Surrogatepaaren. Code, der in früheren Versionen von Windows geschrieben wurde, die auf diesem Verhalten angewiesen sind, um zufällige binärdaten zu codieren, kann zu Problemen führen. Code, der diese Funktion für gültige UTF-8-Zeichenfolgen verwendet, verhält sich jedoch genauso wie bei früheren Windows-Betriebssystemen.
Windows XP: Um das Sicherheitsproblem der nicht kürzesten Formatversionen von UTF-8 Zeichen zu verhindern, MultiByteToWideChar diese Zeichen löscht.
Ab Windows 8:MultiByteToWideChar- wird in Stringapiset.hdeklariert. Vor Windows 8 wurde sie in Winnls.hdeklariert.
Codebeispiel
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();
}
Beispiel aus universellen Windows-Beispielen auf GitHub.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | stringapiset.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |