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.

Für die unten aufgeführten Codeseiten muss dwFlags auf .0 Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGS fehl.

• 50220
• 50221
• 50222
• 50225
• 50227
• 50229
• 57002 bis 57011
• 65000 (UTF-7)
• 42 (Symbol)

[in] lpMultiByteStr

Zeigen Sie auf die zu konvertierende Zeichenfolge.

[in] cbMultiByte

Größe der durch den parameter lpMultiByteStr angegebenen Zeichenfolge in Bytes. Alternativ kann dieser Parameter auf -1 festgelegt werden, wenn die Zeichenfolge null beendet ist. Beachten Sie, dass bei cbMultiByte0ein Fehler auftritt.

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 puffers in Zeichen, der durch lpWideCharStr angegeben ist. Wenn dieser Wert lautet 0, gibt die Funktion die erforderliche Puffergröße in Zeichen zurück, einschließlich eines endenden NULL-Zeichens und verwendet nicht den lpWideCharStr-Puffer .

Rückgabewert

Gibt die Anzahl der Zeichen zurück, die in den Puffer geschrieben wurden, der von lpWideCharStr angegeben ist, wenn dies erfolgreich war. Wenn die Funktion erfolgreich ist und cchWideChar lautet, ist 0der Rückgabewert die erforderliche Größe in Zeichen für den puffer, der durch lpWideCharStr angegeben ist. Weitere Informationen dazu, wie sich das MB_ERR_INVALID_CHARS Flag auf den Rückgabewert auswirkt, wenn ungültige Sequenzen eingegeben werden, finden Sie auch unter dwFlags.

Die Funktion gibt zurück 0 , wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, 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 NULL.
• 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 ANSI-Codeseiten können auf verschiedenen Computern unterschiedlich sein oder für einen einzelnen Computer geändert werden, was zu Datenbeschädigungen 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.

Der Ausgabepuffer kann problemlos überlaufen werden, wenn diese Funktion nicht zuerst mit cchWideChar0 aufgerufen wird, 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 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 das Aufrufen von NormalizeString nach der Konvertierung mit MultiByteToWideChar. NormalizeString bietet genauere, standardmäßige und konsistentere Daten und kann auch schneller sein. Beachten Sie, dass für die an NormalizeString übergebene NORM_FORM Enumeration NormalizationC MB_PRECOMPOSED und NormalizationD MB_COMPOSITE entspricht.

Die lpMultiByteStr - und lpWideCharStr-Zeiger 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 keine Ausgabezeichenfolge, wenn die Länge der Eingabezeichenfolge explizit ohne ein beendetes 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 lone Surrogate-Hälften oder nicht übereinstimmende Ersatzpaare. 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, 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

Siehe auch

Unicode- und Zeichensatzfunktionen

Unicode- und Zeichensätze

WideCharToMultiByte

In VBS-Enklaven verfügbare Vertdll-APIs