MultiByteToWideChar-Funktion (stringapiset.h)

Artikel
07/16/2024

Ordnet eine Zeichenfolge einer UTF-16 -Zeichenfolge (Breite Zeichen) zu. Die Zeichenfolge stammt nicht unbedingt aus einem Multibyte-Zeichensatz.

Vorsicht Die Verwendung der MultiByteToWideChar-Funktion kann die Sicherheit Ihrer Anwendung fälschlicherweise beeinträchtigen. Das Aufrufen dieser Funktion kann zu einem Pufferüberlauf führen, da die Größe des eingabepuffers, der durch lpMultiByteStr angegeben ist, der Anzahl der Bytes in der Zeichenfolge entspricht, während die Größe des ausgabepuffers, der durch lpWideCharStr angegeben ist, der Anzahl von Zeichen entspricht. Um einen Pufferüberlauf zu vermeiden, muss ihre Anwendung eine Puffergröße angeben, die für den Datentyp geeignet ist, den der Puffer empfängt. Weitere Informationen finden Sie unter Sicherheitsüberlegungen: Internationale Features.

Hinweis Die ANSI-Codeseiten können auf verschiedenen Computern unterschiedlich sein oder für einen einzelnen Computer geändert werden, was zu Datenbeschädigung führt. Für die einheitlichen Ergebnisse sollten Anwendungen Unicode verwenden, z. B. UTF-8 oder UTF-16, anstelle einer bestimmten Codeseite, es sei denn, ältere Standards oder Datenformate verhindern die Verwendung von Unicode. Wenn Die Verwendung von Unicode nicht möglich ist, sollten Anwendungen den Datenstrom mit dem entsprechenden Codierungsnamen markieren, wenn protokolle dies zulassen. HTML- und XML-Dateien ermöglichen tagging, Textdateien jedoch nicht.

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.

Wert	Bedeutung
CP_ACP	Die Standardmäßige Windows ANSI-Codeseite des Systems. Hinweis Dieser Wert kann auf verschiedenen Computern auch im selben Netzwerk unterschiedlich sein. Sie kann auf demselben Computer geändert werden, was dazu führt, dass gespeicherte Daten unwiederbringlich beschädigt werden. Dieser Wert ist nur für die temporäre Verwendung vorgesehen, und der permanente Speicher sollte UTF-16 oder UTF-8 verwenden, falls möglich.
CP_MACCP	Die aktuelle Macintosh-Codeseite des Systems. Hinweis Dieser Wert kann auf verschiedenen Computern auch im selben Netzwerk unterschiedlich sein. Sie kann auf demselben Computer geändert werden, was dazu führt, dass gespeicherte Daten unwiederbringlich beschädigt werden. Dieser Wert ist nur für die temporäre Verwendung vorgesehen, und der permanente Speicher sollte UTF-16 oder UTF-8 verwenden, falls möglich. Hinweis Dieser Wert wird hauptsächlich im Legacycode verwendet und sollte in der Regel nicht benötigt werden, da moderne Macintosh-Computer Unicode für die Codierung verwenden.
CP_OEMCP	Die aktuelle OEM-Codeseite des Systems. Hinweis Dieser Wert kann auf verschiedenen Computern auch im selben Netzwerk unterschiedlich sein. Sie kann auf demselben Computer geändert werden, was dazu führt, dass gespeicherte Daten unwiederbringlich beschädigt werden. Dieser Wert ist nur für die temporäre Verwendung vorgesehen, und der permanente Speicher sollte UTF-16 oder UTF-8 verwenden, falls möglich.
CP_SYMBOL	Symbolcodeseite (42).
CP_THREAD_ACP	Die Windows ANSI-Codeseite für den aktuellen Thread. Hinweis Dieser Wert kann auf verschiedenen Computern auch im selben Netzwerk unterschiedlich sein. Sie kann auf demselben Computer geändert werden, was dazu führt, dass gespeicherte Daten unwiederbringlich beschädigt werden. Dieser Wert ist nur für die temporäre Verwendung vorgesehen, und der permanente Speicher sollte UTF-16 oder UTF-8 verwenden, falls möglich.
CP_UTF7	UTF-7. Verwenden Sie diesen Wert nur, wenn sie durch einen 7-Bit-Transportmechanismus erzwungen wird. Die Verwendung von UTF-8 wird bevorzugt.
CP_UTF8	UTF-8.

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

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

Vorgabe; verwenden Sie nicht mit MB_COMPOSITE. Verwenden Sie immer vorkompilierte Zeichen, d. h. Zeichen mit einem einzelnen Zeichenwert für eine Basis- oder Nicht-Füllzeichenkombination. Im Zeichen "è" ist das Zeichen "e" beispielsweise das Basiszeichen und das Akzent-Graviszeichen das nicht übersteigende Zeichen.For example, the e is the base character and the accent grave mark is the nonspacing character. Wenn ein einzelner Unicode-Codepunkt für ein Zeichen definiert ist, sollte die Anwendung ihn anstelle eines separaten Basiszeichens und eines nicht überstellenden Zeichens verwenden. Beispielsweise wird Ä durch den einzelnen Unicode-Codepunkt LATIN CAPITAL LETTER A WITH DIAERESIS (U+00C4) dargestellt.

MB_USEGLYPHCHARS

Verwenden Sie Glyphenzeichen anstelle von Steuerzeichen.

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

Siehe auch

Unicode- und Zeichensatzfunktionen

Unicode- und Zeichensätze

WideCharToMultiByte-

Vertdll-APIs in VBS-Enklaven

Freigeben über