MultiByteToWideChar-Funktion (stringapiset.h)
Ordnet eine Zeichenfolge einer UTF-16-Zeichenfolge (Breitzeichen) 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
Codepage, die bei der Konvertierung verwendet werden soll. Dieser Parameter kann auf den Wert einer beliebigen Codepage festgelegt werden, die im Betriebssystem installiert oder verfügbar ist. Eine Liste der Codepages finden Sie unter CodePage-Bezeichner. Ihre Anwendung kann auch einen der in der folgenden Tabelle aufgeführten 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 zerlegte Zeichen, d. h. Zeichen, in denen ein Basiszeichen und ein oder mehrere zeichenfreie Zeichen jeweils unterschiedliche Codepunktwerte aufweisen. Ä wird beispielsweise durch A + ̈: LATEINISCHER GROßBUCHSTABE A (U+0041) + KOMBINIERENDE DIAERESE (U+0308) dargestellt. Beachten Sie, dass dieses Flag nicht mit MB_PRECOMPOSED verwendet werden kann. |
| MB_ERR_INVALID_CHARS | Fehler, wenn ein ungültiges Eingabezeichen gefunden wird. Ab Windows Vista löscht die Funktion keine unzulässigen Codepunkte, wenn die Anwendung dieses Flag nicht festlegt, sondern ersetzt stattdessen unzulässige Sequenzen durch U+FFFD (entsprechend der angegebenen Codepage codiert). Windows 2000 mit SP4 und höher, Windows XP: Wenn dieses Flag nicht festgelegt ist, löscht die Funktion im Hintergrund unzulässige Codepunkte. Ein Aufruf von GetLastError gibt ERROR_NO_UNICODE_TRANSLATION zurück. |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
Für die unten aufgeführten Codepages muss dwFlags auf 0festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGS fehl.
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 bis 57011
- 65000 (UTF-7)
- 42 (Symbol)
Hinweis
Für UTF-8 oder Codepage 54936 (GB18030 ab Windows Vista) muss dwFlags auf 0 oder MB_ERR_INVALID_CHARS festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGS fehl.
[in] lpMultiByteStr
Zeiger auf die zu konvertierende Zeichenfolge.
[in] cbMultiByte
Größe der durch den lpMultiByteStr-Parameter angegebenen Zeichenfolge in Byte. Alternativ kann dieser Parameter auf -1 festgelegt werden, wenn die Zeichenfolge null-beendet ist. Beachten Sie, dass die Funktion fehlschlägt, wenn cbMultiByte ist 0.
Wenn dieser Parameter -1 ist, verarbeitet die Funktion die gesamte Eingabezeichenfolge, einschließlich des abschließenden 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 abschließendes NULL-Zeichen enthält, ist 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 lpWideCharStr. angegebenen Puffers in Zeichen. Wenn dieser Wert ist 0, gibt die Funktion die erforderliche Puffergröße in Zeichen zurück, einschließlich aller abschließenden NULL-Zeichen, und verwendet nicht den lpWideCharStr-Puffer .
Rückgabewert
Gibt die Anzahl der Zeichen zurück, die in den Puffer geschrieben wurden, die von lpWideCharStr angegeben sind, wenn dies erfolgreich war. Wenn die Funktion erfolgreich ist und cchWideChar ist 0, ist der Rückgabewert die erforderliche Größe in Zeichen für den Puffer, der von lpWideCharStr angegeben wird. 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 zurück 0 , wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, kann die Anwendung GetLastError aufrufen, wodurch einer 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: Jeder der Parameterwerte war ungültig.
- ERROR_NO_UNICODE_TRANSLATION: In einer Zeichenfolge wurde ein ungültiger Unicode-Wert gefunden.
Hinweise
Das Standardverhalten dieser Funktion besteht darin, die Eingabezeichenfolge in eine vorkompilierte Form zu übersetzen. Wenn kein vorkompiliertes Formular vorhanden ist, versucht die Funktion, in ein zusammengesetztes Formular zu übersetzen.
Die Verwendung des MB_PRECOMPOSED-Flags hat nur sehr geringe Auswirkungen auf die meisten Codepages, da die meisten Eingabedaten bereits zusammengestellt sind. Erwägen Sie den Aufruf von NormalizeString nach der Konvertierung mit MultiByteToWideChar. NormalizeString bietet präzisere, standardmäßige und konsistentere Daten und kann auch schneller sein. Beachten Sie, dass normalizationC für die NORM_FORM-Enumeration , die an NormalizeString übergeben wird, MB_PRECOMPOSED und NormalizationD MB_COMPOSITE entspricht.
Wie in der obigen Vorsicht erwähnt, kann der Ausgabepuffer leicht überlaufen werden, wenn diese Funktion nicht zuerst aufgerufen wird, wenn cchWideChar auf 0 festgelegt ist, um die erforderliche Größe zu erhalten. Wenn das flag MB_COMPOSITE verwendet wird, kann die Ausgabe drei oder mehr Zeichen lang für jedes Eingabezeichen sein.
Die Zeiger lpMultiByteStr und lpWideCharStr dürfen nicht identisch sein. Wenn sie identisch sind, schlägt die Funktion fehl, und GetLastError gibt den Wert ERROR_INVALID_PARAMETER zurück.
MultiByteToWideChar beendet eine Ausgabezeichenfolge nicht mit NULL, wenn die Eingabezeichenfolgenlänge explizit ohne ein beendendes NULL-Zeichen angegeben wird. Um eine Ausgabezeichenfolge für diese Funktion mit NULL zu beenden, sollte die Anwendung -1 übergeben oder explizit das beendende NULL-Zeichen für die Eingabezeichenfolge zählen.
Die Funktion schlägt fehl, wenn MB_ERR_INVALID_CHARS festgelegt ist und ein ungültiges Zeichen in der Quellzeichenfolge gefunden wird. Ein ungültiges Zeichen ist eines der folgenden:
- Ein Zeichen, das nicht das Standardzeichen in der Quellzeichenfolge ist, sondern in das Standardzeichen übersetzt, wenn MB_ERR_INVALID_CHARS nicht festgelegt ist.
- Für DBCS-Zeichenfolgen ein Zeichen, das über ein Leadbyte, aber kein gültiges Trailbyte verfügt.
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 einzelne Ersatzpaare oder nicht übereinstimmende Ersatzpaare. Code, der in früheren Versionen von Windows geschrieben wurde und auf diesem Verhalten basiert, um zufällige Binärdaten ohne Text 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 unter früheren Windows-Betriebssystemen.
Windows XP: Um das Sicherheitsproblem der nicht kürzesten Versionen von UTF-8-Zeichen zu verhindern, löscht MultiByteToWideChar diese Zeichen.
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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | stringapiset.h (einschließlich Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für