WideCharToMultiByte-Funktion (stringapiset.h)

Ordnet eine UTF-16-Zeichenfolge (Breitzeichen) einer neuen Zeichenfolge zu. Die neue Zeichenfolge stammt nicht unbedingt aus einem Multibyte-Zeichensatz.

Syntax

int WideCharToMultiByte(
  [in]            UINT                               CodePage,
  [in]            DWORD                              dwFlags,
  [in]            _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
  [in]            int                                cchWideChar,
  [out, optional] LPSTR                              lpMultiByteStr,
  [in]            int                                cbMultiByte,
  [in, optional]  LPCCH                              lpDefaultChar,
  [out, optional] LPBOOL                             lpUsedDefaultChar
);

Parameter

[in] CodePage

Codepage, die beim Ausführen 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 dargestellten Werte angeben.

[in] dwFlags

Flags, die den Konvertierungstyp angeben. Die Anwendung kann eine Kombination der folgenden Werte angeben. Die Funktion funktioniert schneller, wenn keines dieser Flags festgelegt ist. Die Anwendung sollte WC_NO_BEST_FIT_CHARS und WC_COMPOSITECHECK mit dem spezifischen Wert angeben, der WC_DEFAULTCHAR, um alle möglichen Konvertierungsergebnisse abzurufen. Wenn nicht alle drei Werte angegeben werden, fehlen einige Ergebnisse.

Für die unten aufgeführten Codepages muss dwFlags 0 sein. 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] lpWideCharStr

Zeiger auf die zu konvertierende Unicode-Zeichenfolge.

[in] cchWideChar

Größe der durch lpWideCharStr. angegebenen Zeichenfolge in Zeichen. Alternativ kann dieser Parameter auf -1 festgelegt werden, wenn die Zeichenfolge null-beendet ist. Wenn cchWideChar auf 0 festgelegt ist, schlägt die Funktion fehl.

Wenn dieser Parameter -1 ist, verarbeitet die Funktion die gesamte Eingabezeichenfolge, einschließlich des abschließenden NULL-Zeichens. Daher weist die resultierende 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 Zeichen. Wenn die angegebene Größe kein abschließendes NULL-Zeichen enthält, ist die resultierende Zeichenfolge nicht null-beendet, und die zurückgegebene Länge enthält dieses Zeichen nicht.

[out, optional] lpMultiByteStr

Zeiger auf einen Puffer, der die konvertierte Zeichenfolge empfängt.

[in] cbMultiByte

Größe des durch lpMultiByteStr. angegebenen Puffers in Byte. Wenn dieser Wert 0 ist, gibt die Funktion die erforderliche Puffergröße in Bytes zurück, einschließlich aller abschließenden NULL-Zeichen, und verwendet nicht den lpMultiByteStr-Puffer .

[in, optional] lpDefaultChar

Zeiger auf das Zeichen, das verwendet werden soll, wenn ein Zeichen in der angegebenen Codepage nicht dargestellt werden kann. Die Anwendung legt diesen Parameter auf NULL fest, wenn die Funktion einen Systemstandardwert verwenden soll. Um das Standardzeichen des Systems abzurufen, kann die Anwendung die Funktion GetCPInfo oder GetCPInfoEx aufrufen.

Für die CP_UTF7- und CP_UTF8 einstellungen für CodePage muss dieser Parameter auf NULL festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_PARAMETER fehl.

[out, optional] lpUsedDefaultChar

Zeiger auf ein Flag, das angibt, ob die Funktion bei der Konvertierung ein Standardzeichen verwendet hat. Das Flag wird auf TRUE festgelegt, wenn ein oder mehrere Zeichen in der Quellzeichenfolge nicht in der angegebenen Codepage dargestellt werden können. Andernfalls wird das Flag auf FALSE festgelegt. Dieser Parameter kann auf NULL festgelegt werden.

Für die CP_UTF7- und CP_UTF8 einstellungen für CodePage muss dieser Parameter auf NULL festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_PARAMETER fehl.

Rückgabewert

Bei erfolgreicher Ausführung gibt die Anzahl der Bytes zurück, die in den Puffer geschrieben werden, auf den lpMultiByteStr verweist. Wenn die Funktion erfolgreich ist und cbMultiByte 0 ist, entspricht der Rückgabewert der erforderlichen Größe in Bytes für den puffer, der durch lpMultiByteStr angegeben ist. Weitere Informationen dazu, wie sich das WC_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 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 NULL festgelegt.
• 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-Code gefunden.

Hinweise

Die Zeiger lpMultiByteStr und lpWideCharStr dürfen nicht identisch sein. Wenn sie identisch sind, schlägt die Funktion fehl, und GetLastError gibt ERROR_INVALID_PARAMETER zurück.

WideCharToMultiByte beendet eine Ausgabezeichenfolge nicht null, wenn die Länge der Eingabezeichenfolge explizit ohne ein abschließendes NULL-Zeichen angegeben wird. Um eine Ausgabezeichenfolge für diese Funktion null zu beenden, muss die Anwendung -1 übergeben oder explizit das abschließende NULL-Zeichen für die Eingabezeichenfolge zählen.

Wenn cbMultiByte kleiner als cchWideChar ist, schreibt diese Funktion die von cbMultiByte angegebene Anzahl von Zeichen in den puffer, der durch lpMultiByteStr angegeben ist. Wenn CodePage jedoch auf CP_SYMBOL und cbMultiByte kleiner als cchWideChar ist, schreibt die Funktion keine Zeichen in lpMultiByteStr.

Die WideCharToMultiByte-Funktion funktioniert am effizientesten, wenn sowohl lpDefaultChar als auch lpUsedDefaultChar auf NULL festgelegt sind. Die folgende Tabelle zeigt das Verhalten der Funktion für die vier möglichen Kombinationen dieser Parameter.

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 einsame Ersatzzeichenhälften oder falsch übereinstimmende Ersatzzeichenpaare. Code, der in früheren Versionen von Windows geschrieben wurde und auf diesem Verhalten basiert, um zufällige Nicht-Text-Binärdaten zu codieren, kann auf Probleme stoßen. Code, der diese Funktion verwendet, um gültige UTF-8-Zeichenfolgen zu erzeugen, verhält sich jedoch genauso wie bei früheren Windows-Betriebssystemen.

Ab Windows 8: WideCharToMultiByte wird in Stringapiset.h deklariert. Vor Windows 8 wurde sie in Winnls.h deklariert.

WC_COMPOSITECHECK und verwandte Flags

Das WC_COMPOSITECHECK-Flag bewirkt, dass die WideCharToMultiByte-Funktion auf zerlegte Unicode-Zeichen testet und versucht, sie zu verfassen, bevor sie in die angeforderte Codepage konvertiert werden. Dieses Flag ist nur für die Konvertierung in Codepages mit single byte (SBCS) oder Double Byte (DBCS) (Codepages < 50000, ausgenommen Codepage 42) verfügbar. Wenn Ihre Anwendung zerlegte Unicode-Daten in Einzelbyte- oder Doppelbytecodepages konvertieren muss, kann dieses Flag nützlich sein. Allerdings können nicht alle Zeichen auf diese Weise konvertiert werden, und es ist zuverlässiger, solche Daten wie Unicode zu speichern und zu speichern.

Wenn eine Anwendung WC_COMPOSITECHECK verwendet, bleiben einige Zeichenkombinationen möglicherweise unvollständig oder enthalten möglicherweise zusätzliche zeichenfreie Zeichen. Beispielsweise kombiniert A + ̈ + ̈ zu Ä + ̈. Die Verwendung des WC_DISCARDNS-Flags bewirkt, dass die Funktion zusätzliche Zeichen verwirft, die keine Zeichenfolgenzeichen enthalten. Die Verwendung des WC_DEFAULTCHAR Flags bewirkt, dass die Funktion stattdessen das Standardersetzungszeichen (in der Regel "?") verwendet. Die Verwendung des WC_SEPCHARS-Flags bewirkt, dass die Funktion versucht, jedes zusätzliche Zeichen ohne Strich in die Zielcodepage zu konvertieren. In der Regel verursacht dieses Flag auch die Verwendung des Ersatzzeichens ("?"). Für Codepage 1258 (Vietnamesisch) und 20269 sind jedoch zeichenfreie Zeichen vorhanden und können verwendet werden. Die Konvertierungen für diese Codepages sind nicht perfekt. Einige Kombinationen werden nicht ordnungsgemäß in codepage 1258 konvertiert, und WC_COMPOSITECHECK beschädigt Daten in codepage 20269. Wie bereits erwähnt, ist es zuverlässiger, Ihre Anwendung so zu entwerfen, dass daten wie Unicode gespeichert und gespeichert werden.

Beispiele

ISDSC_STATUS DiscpUnicodeToAnsiSize(
    IN __in PWCHAR UnicodeString,
    OUT ULONG *AnsiSizeInBytes
    )
/*++
Routine Description:
    This routine will return the length needed to represent the unicode
    string as ANSI
Arguments:
    UnicodeString is the unicode string whose ansi length is returned
    *AnsiSizeInBytes is number of bytes needed to represent unicode
        string as ANSI
Return Value:
    ERROR_SUCCESS or error code
--*/
{
    _try
    {
        *AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
                                               0,
                                               UnicodeString,
                                               -1,
                                               NULL,
                                               0, NULL, NULL);
    } _except(EXCEPTION_EXECUTE_HANDLER) {
        return(ERROR_NOACCESS);
    }
    return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}

Anforderungen

Siehe auch

MultiByteToWideChar

Unicode- und Zeichensatzfunktionen

Unicode und Zeichensätze

In VBS-Enclaves verfügbare Vertdll-APIs