WideCharToMultiByte-Funktion (stringapiset.h)

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

Vorsicht Die Verwendung der Funktion WideCharToMultiByte kann die Sicherheit Ihrer Anwendung beeinträchtigen. Durch das Aufrufen dieser Funktion kann ein Pufferüberlauf leicht verursacht werden, da die Größe des von lpWideCharStr angegebenen Eingabepuffers die Anzahl der Zeichen in der Unicode-Zeichenfolge entspricht, während die Größe des ausgabepuffers, der durch lpMultiByteStr angegeben ist, die Anzahl der Bytes entspricht. Um einen Pufferüberlauf zu vermeiden, muss Ihre Anwendung eine Puffergröße angeben, die für den Datentyp, den der Puffer empfängt, geeignet ist.

Daten, die von UTF-16 in Nicht-Unicode-Codierungen konvertiert werden, unterliegen Datenverlust, da eine Codeseite möglicherweise nicht in der Lage sein kann, jedes zeichen darzustellen, das in den spezifischen Unicode-Daten verwendet wird. Weitere Informationen finden Sie unter Sicherheitsaspekte: 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ä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 Unicode nicht verwendet wird, sollten Anwendungen den Datenstrom mit dem entsprechenden Codierungsnamen kennzeichnen, wenn protokolle dies zulassen. HTML- und XML-Dateien ermöglichen die Markierung, aber Textdateien sind nicht möglich.
 

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

Codeseite, die beim Ausführen der Konvertierung verwendet werden soll. Dieser Parameter kann auf den Wert einer beliebigen Codeseite festgelegt werden, die installiert oder im Betriebssystem verfügbar ist. Eine Liste der Codeseiten finden Sie unter Codeseitenbezeichner. Ihre Anwendung kann auch einen der Werte angeben, die in der folgenden Tabelle angezeigt werden.

Wert Bedeutung
CP_ACP
Die Windows ANSI-Standardcodeseite 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 unaufwendbar beschädigt werden. Dieser Wert ist nur für temporäre Verwendung und permanenten Speicher vorgesehen, wenn möglich UTF-16 oder UTF-8 zu verwenden.
 
CP_MACCP
Die aktuelle System-Macintosh-Codeseite.
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 unaufwendbar beschädigt werden. Dieser Wert ist nur für temporäre Verwendung und permanenten Speicher vorgesehen, wenn möglich UTF-16 oder UTF-8 zu verwenden.
 
Hinweis Dieser Wert wird hauptsächlich im Legacycode verwendet und sollte nicht allgemein benötigt werden, da moderne Macintosh-Computer Unicode für die Codierung verwenden.
 
CP_OEMCP
Die aktuelle System-OEM-Codeseite.
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 unaufwendbar beschädigt werden. Dieser Wert ist nur für temporäre Verwendung und permanenten Speicher vorgesehen, wenn möglich UTF-16 oder UTF-8 zu verwenden.
 
CP_SYMBOL
Windows 2000: Symbolcodeseite (42).
CP_THREAD_ACP
Windows 2000: 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 unaufwendbar beschädigt werden. Dieser Wert ist nur für temporäre Verwendung und permanenten Speicher vorgesehen, wenn möglich UTF-16 oder UTF-8 zu verwenden.
 
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. Mit diesem Wertsatz muss lpDefaultChar und lpUsedDefaultChar auf NULL festgelegt werden.
CP_UTF8
UTF-8. Mit diesem Wertsatz muss lpDefaultChar und lpUsedDefaultChar auf NULL festgelegt werden.

[in] dwFlags

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

Wert Bedeutung
WC_COMPOSITECHECK
Konvertieren Sie zusammengesetzte Zeichen, bestehend aus einem Basiszeichen und einem zeichenfreien Zeichen, jeweils mit unterschiedlichen Zeichenwerten. Übersetzen Sie diese Zeichen in vorkompilierte Zeichen, die einen einzelnen Zeichenwert für eine Kombination aus basisfreien Zeichen aufweisen. Beispielsweise ist die e im Zeichen è das Basiszeichen, und das Akzentgrabzeichen ist das Zeichen ohne Pacing.
Hinweis Windows stellt normalerweise Unicode-Zeichenfolgen mit vorkompilierten Daten dar und macht die Verwendung des WC_COMPOSITECHECK Flags unnötig.
 

Ihre Anwendung kann WC_COMPOSITECHECK mit einer der folgenden Flags kombinieren, wobei die Standardeinstellung WC_SEPCHARS ist. Diese Flags bestimmen das Verhalten der Funktion, wenn keine vordefinierte Zuordnung für eine basisfreie Zeichenkombination in einer Unicode-Zeichenfolge verfügbar ist. Wenn keine dieser Flags angegeben wird, verhält sich die Funktion so, als ob das WC_SEPCHARS Flag festgelegt ist. Weitere Informationen finden Sie unter WC_COMPOSITECHECK und verwandte Kennzeichnungen im Abschnitt "Hinweise ".

WC_DEFAULTCHAR Ersetzen Sie Ausnahmen durch das Standardzeichen während der Konvertierung.
WC_DISCARDNS Verwerfen von Zeichen ohne Pacing während der Konvertierung.
WC_SEPCHARS Standard. Generieren Sie separate Zeichen während der Konvertierung.
 
WC_ERR_INVALID_CHARS
Windows Vista und höher: Fehler (durch Zurückgeben von 0 und Festlegen des letzten Fehlercodes auf ERROR_NO_UNICODE_TRANSLATION), wenn ein ungültiges Eingabezeichen aufgetreten ist. Sie können den letzten Fehlercode mit einem Aufruf von GetLastError abrufen. Wenn dieses Flag nicht festgelegt ist, ersetzt die Funktion illegale Sequenzen durch U+FFFD (codiert entsprechend der angegebenen Codeseite) und wird durch Zurückgeben der Länge der konvertierten Zeichenfolge erfolgreich. Beachten Sie, dass dieses Kennzeichen nur gilt, wenn CodePage als CP_UTF8 oder 54936 angegeben wird. Es kann nicht mit anderen Codeseitenwerten verwendet werden.
WC_NO_BEST_FIT_CHARS
Übersetzen Sie alle Unicode-Zeichen, die nicht direkt in Multibyte-Äquivalente zum standardzeichen übersetzt werden, das von lpDefaultChar angegeben ist. Anders ausgedrückt: Wenn die Übersetzung von Unicode in Multibyte und zurück in Unicode erneut nicht dasselbe Unicode-Zeichen liefert, verwendet die Funktion das Standardzeichen. Dieses Kennzeichen kann von sich selbst oder in Kombination mit den anderen definierten Flags verwendet werden.

Bei Zeichenfolgen, die eine Überprüfung erfordern, z. B. Datei-, Ressourcen- und Benutzernamen, sollte die Anwendung immer das WC_NO_BEST_FIT_CHARS Flag verwenden. Dieses Flag verhindert, dass die Funktion Zeichen mit Zeichen zuordnen kann, die ähnlich erscheinen, aber sehr unterschiedliche Semantik haben. In einigen Fällen kann die semantische Änderung extrem sein. Beispielsweise wird das Symbol für "∞" (Unendlichkeit) in einigen Codeseiten 8 (acht) zugeordnet.

 

Für die unten aufgeführten Codeseiten 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)
Hinweis Für die Codeseite 65001 (UTF-8) oder die Codeseite 54936 (GB18030, Windows Vista und höher) muss dwFlags auf 0 oder WC_ERR_INVALID_CHARS festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGS fehl.
 

[in] lpWideCharStr

Zeiger auf die Unicode-Zeichenfolge, um zu konvertieren.

[in] cchWideChar

Größe in Zeichen der Zeichenfolge, die von lpWideCharStr angegeben ist. 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 terminierenden Nullzeichens. Daher verfügt die resultierende Zeichenzeichenfolge über ein beendetes Nullzeichen, und die länge, die von der Funktion zurückgegeben wird, 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 beendetes NULL-Zeichen enthält, ist die resultierende Zeichenzeichenfolge 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, in Bytes, des Puffers, der von lpMultiByteStr angegeben ist. Wenn dieser Wert 0 ist, gibt die Funktion die erforderliche Puffergröße zurück, in Bytes, einschließlich eines terminierenden Nullzeichens, und verwendet keinen lpMultiByteStr-Puffer .

[in, optional] lpDefaultChar

Zeiger auf das Zeichen, das verwendet werden soll, wenn ein Zeichen nicht auf der angegebenen Codeseite dargestellt werden kann. Die Anwendung legt diesen Parameter auf NULL fest, wenn die Funktion einen Systemstandardwert verwendet. Um das Systemstandardzeichen abzurufen, kann die Anwendung die GetCPInfo- oder GetCPInfoEx-Funktion aufrufen.

Für die einstellungen CP_UTF7 und CP_UTF8 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 ein Standardzeichen in der Konvertierung verwendet hat. Das Flag wird auf TRUE festgelegt, wenn eine oder mehrere Zeichen in der Quellzeichenfolge nicht in der angegebenen Codeseite dargestellt werden können. Andernfalls wird das Flag auf FALSE festgelegt. Dieser Parameter kann auf NULL festgelegt werden.

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

Rückgabewert

Wenn dies erfolgreich ist, gibt die Anzahl von Bytes zurück, die in den Puffer geschrieben wurden, auf den lpMultiByteStr verweist. Wenn die Funktion erfolgreich ist und cbMultiByte 0 ist, ist der Rückgabewert die erforderliche Größe in Bytes für den puffer, der von lpMultiByteStr angegeben ist. Weitere Informationen dazu finden Sie unter dwFlags , wie sich das WC_ERR_INVALID_CHARS Flag auf den Rückgabewert auswirkt, wenn ungültige Sequenzen eingegeben werden.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, kann die Anwendung GetLastError aufrufen, die einen der folgenden Fehlercodes zurückgeben kann:

  • ERROR_INSUFFICIENT_BUFFER. Eine angegebene Puffergröße war nicht groß genug, oder es wurde falsch auf NULL festgelegt.
  • ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
  • ERROR_INVALID_PARAMETER. Eine der Parameterwerte war ungültig.
  • ERROR_NO_UNICODE_TRANSLATION. Ungültiges Unicode wurde in einer Zeichenfolge gefunden.

Bemerkungen

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

WideCharToMultiByte beendet keine Ausgabezeichenfolge null, wenn die Eingabezeichenfolgenlänge explizit angegeben wird, ohne null zu beenden. Um eine Ausgabezeichenfolge für diese Funktion null zu beenden, sollte die Anwendung in -1 übergeben oder explizit das Endzeichen null für die Eingabezeichenfolge zählen.

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

Die Funktion WideCharToMultiByte 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.

lpDefaultChar lpUsedDefaultChar Ergebnis
NULL NULL Keine Standardüberprüfung. Diese Parametereinstellungen sind die effizientesten für die Verwendung mit dieser Funktion.
Nicht NULL-Zeichen NULL Verwendet das angegebene Standardzeichen, legt jedoch nicht lpUsedDefaultChar fest.
NULL Nicht NULL-Zeichen Verwendet das Systemstandardzeichen und legt lpUsedDefaultChar bei Bedarf fest.
Nicht NULL-Zeichen Nicht NULL-Zeichen Verwendet das angegebene Standardzeichen und legt lpUsedDefaultChar bei Bedarf fest.
 

Ab Windows Vista entspricht diese Funktion vollständig der Unicode 4.1-Spezifikation für UTF-8 und UTF-16. Die funktion, die bei früheren Betriebssystemen codiert oder decodes lone surrogate halves or mismatched surrogate pairs. Code, der in früheren Versionen von Windows geschrieben wurde, die sich auf dieses Verhalten verlassen, um zufällige Nicht-Text-Binärdaten zu codieren, kann zu Problemen führen. 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

Wie in der Verwendung der Unicode-Normalisierung für Zeichenfolgen beschrieben, ermöglicht Unicode mehrere Darstellungen derselben Zeichenfolge (interpretiert). Beispielsweise kann Dieresis (Umlaut) entweder als einzelner Unicode-Codepunkt "Ä" (U+00C4) dargestellt oder als Kombination von Kapital A und der kombinationsigen Dieresiszeichen ("A" + "̈" dargestellt werden, d. b. U+0041 U+0308). Die meisten Codeseiten bieten jedoch nur zusammengesetzte Zeichen.

Das WC_COMPOSITECHECK-Flag führt dazu, dass die WideCharToMultiByte-Funktion auf dekompilierte Unicode-Zeichen getestet und versucht, sie zu verfassen, bevor sie in die angeforderte Codeseite konvertiert werden. Dieses Flag ist nur für die Konvertierung in single byte (SBCS) oder Double Byte (DBCS)-Codeseiten (Codeseiten < 50000, außer Codeseite 42) verfügbar. Wenn Ihre Anwendung kompilierte Unicode-Daten in einzelne Byte- oder Doppel-Byte-Codeseiten konvertieren muss, kann dieses Flag nützlich sein. Allerdings können nicht alle Zeichen auf diese Weise konvertiert werden, und es ist zuverlässiger, daten wie Unicode zu speichern und zu speichern.

Wenn eine Anwendung WC_COMPOSITECHECK verwendet, bleiben einige Zeichenkombinationen möglicherweise unvollständig oder verfügen möglicherweise über zusätzliche nicht übersteigende Zeichen. Beispiel: A + ̈ + ̈ kombiniert mit Ä + ̈. Die Verwendung des WC_DISCARDNS-Flags führt dazu, dass die Funktion zusätzliche Nicht-Pacing-Zeichen verwerfen kann. Die Verwendung des WC_DEFAULTCHAR-Flags bewirkt, dass die Funktion stattdessen das Standard-Ersatzzeichen (normalerweise "?") verwendet. Die Verwendung des WC_SEPCHARS-Flags führt dazu, dass die Funktion versucht, jedes zusätzliche nicht übersteigende Zeichen in die Zielcodeseite zu konvertieren. In der Regel verursacht dieses Flag auch die Verwendung des Ersatzzeichens ("?"). Für Codeseite 1258 (Vietnamesisch) und 20269 sind jedoch nicht übersteigende Zeichen vorhanden und können verwendet werden. Die Konvertierungen für diese Codeseiten sind nicht perfekt. Einige Kombinationen werden nicht ordnungsgemäß in Codeseite 1258 konvertiert, und WC_COMPOSITECHECK beschädigt Daten auf der Codeseite 20269. Wie bereits erwähnt, ist es zuverlässiger, Ihre Anwendung zu entwerfen, um daten wie Unicode zu speichern und zu speichern.

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

   
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 (enthalten Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

MultiByteToWideChar

Unicode- und Zeichensatzfunktionen

Unicode- und Zeichensätze