WideCharToMultiByte-Funktion (stringapiset.h)

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

Vorsicht Die falsche Verwendung der WideCharToMultiByte-Funktion kann die Sicherheit Ihrer Anwendung gefährden. Das Aufrufen dieser Funktion kann leicht zu einem Pufferüberlauf führen, da die von lpWideCharStr angegebene Größe des Eingabepuffers der Anzahl von Zeichen in der Unicode-Zeichenfolge entspricht, während die Größe des ausgabepuffers, der durch lpMultiByteStr angegeben wird, der Anzahl von Bytes entspricht. Um einen Pufferüberlauf zu vermeiden, muss Ihre Anwendung eine Puffergröße angeben, die dem Datentyp entspricht, den der Puffer empfängt.

Daten, die aus UTF-16-Codierungen in Nicht-Unicode-Codierungen konvertiert werden, unterliegen Datenverlust, da eine Codepage möglicherweise nicht in der Lage ist, jedes Zeichen darzustellen, das in den spezifischen Unicode-Daten verwendet wird. Weitere Informationen finden Sie unter Sicherheitsüberlegungen: Internationale Features.

 
Hinweis Die ANSI-Codepages können auf verschiedenen Computern unterschiedlich sein oder für einen einzelnen Computer geändert werden, was zu Datenbeschädigungen führt. Um die konsistentesten Ergebnisse zu erzielen, sollten Anwendungen Unicode wie UTF-8 oder UTF-16 anstelle einer bestimmten Codepage verwenden, 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 die Protokolle dies zulassen. HTML- und XML-Dateien lassen Tagging zu, Textdateien jedoch nicht.
 

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.

Wert Bedeutung
CP_ACP
Die Standardmäßige Windows ANSI-Codepage des Systems.
Hinweis Dieser Wert kann sich auf verschiedenen Computern unterscheiden, auch im selben Netzwerk. 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 nach Möglichkeit UTF-16 oder UTF-8 verwenden.
 
CP_MACCP
Die aktuelle Macintosh-Codepage des Systems.
Hinweis Dieser Wert kann sich auf verschiedenen Computern unterscheiden, auch im selben Netzwerk. 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 nach Möglichkeit UTF-16 oder UTF-8 verwenden.
 
Hinweis Dieser Wert wird hauptsächlich in 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 System-OEM-Codepage.
Hinweis Dieser Wert kann sich auf verschiedenen Computern unterscheiden, auch im selben Netzwerk. 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 nach Möglichkeit UTF-16 oder UTF-8 verwenden.
 
CP_SYMBOL
Windows 2000: Symbolcodepage (42).
CP_THREAD_ACP
Windows 2000: Die Windows ANSI-Codepage für den aktuellen Thread.
Hinweis Dieser Wert kann sich auf verschiedenen Computern unterscheiden, auch im selben Netzwerk. 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 nach Möglichkeit UTF-16 oder UTF-8 verwenden.
 
CP_UTF7
UTF-7. Verwenden Sie diesen Wert nur, wenn sie von einem 7-Bit-Transportmechanismus erzwungen werden. Die Verwendung von UTF-8 wird bevorzugt. Mit diesem Wertsatz müssen lpDefaultChar und lpUsedDefaultChar auf NULL festgelegt werden.
CP_UTF8
UTF-8. Mit diesem Wertsatz müssen 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 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.

Wert Bedeutung
WC_COMPOSITECHECK
Konvertieren Sie zusammengesetzte Zeichen, die aus einem Basiszeichen und einem Nicht-Zeichen bestehen, die jeweils unterschiedliche Zeichenwerte aufweisen. Übersetzen Sie diese Zeichen in vorkompilierte Zeichen, die einen einzelnen Zeichenwert für eine basisfreie Zeichenkombination haben. Im Zeichen è ist z. B. das e das Basiszeichen und das Akzentgrabzeichen das nonspacing-Zeichen.
Hinweis Windows stellt normalerweise Unicode-Zeichenfolgen mit vorkompilierten Daten dar, sodass die Verwendung des flags WC_COMPOSITECHECK unnötig ist.
 

Ihre Anwendung kann WC_COMPOSITECHECK mit einem der folgenden Flags kombinieren, wobei der Standardwert WC_SEPCHARS ist. Diese Flags bestimmen das Verhalten der Funktion, wenn keine vorkompilierte Zuordnung für eine Nicht-Basiszeichenkombination in einer Unicode-Zeichenfolge verfügbar ist. Wenn keines dieser Flags angegeben wird, verhält sich die Funktion so, als wäre das WC_SEPCHARS-Flag festgelegt. Weitere Informationen finden Sie unter WC_COMPOSITECHECK und zugehörige Flags im Abschnitt Hinweise .

WC_DEFAULTCHAR Ersetzen Sie ausnahmen durch das Standardzeichen während der Konvertierung.
WC_DISCARDNS Verwerfen sie nicht übersteigende Zeichen während der Konvertierung.
WC_SEPCHARS Standard. Generieren Sie während der Konvertierung separate Zeichen.
 
WC_ERR_INVALID_CHARS
Windows Vista und höher: Schlägt fehl (durch Zurückgeben von 0 und Festlegen des Letzten Fehlercodes auf ERROR_NO_UNICODE_TRANSLATION), wenn ein ungültiges Eingabezeichen gefunden wird. Sie können den Code des letzten Fehlers mit einem Aufruf von GetLastError abrufen. Wenn dieses Flag nicht festgelegt ist, ersetzt die Funktion ungültige Sequenzen durch U+FFFD (entsprechend der angegebenen Codepage codiert) und gibt die Länge der konvertierten Zeichenfolge zurück. Beachten Sie, dass dieses Flag nur gilt, wenn CodePage als CP_UTF8 oder 54936 angegeben wird. Sie kann nicht mit anderen Codepagewerten verwendet werden.
WC_NO_BEST_FIT_CHARS
Übersetzen Sie alle Unicode-Zeichen, die nicht direkt in Multibyte-Entsprechungen mit dem von lpDefaultChar angegebenen Standardzeichen übersetzt werden. Anders ausgedrückt: Wenn die Übersetzung von Unicode in Multibyte und wieder zurück in Unicode nicht dasselbe Unicode-Zeichen ergibt, verwendet die Funktion das Standardzeichen. Dieses Flag kann allein oder in Kombination mit den anderen definierten Flags verwendet werden.

Für Zeichenfolgen, die eine Überprüfung erfordern, z. B. Datei-, Ressourcen- und Benutzernamen, sollte die Anwendung immer das flag WC_NO_BEST_FIT_CHARS verwenden. Dieses Flag verhindert, dass die Funktion Zeichen zuordnen kann, die ähnlich aussehen, aber eine sehr unterschiedliche Semantik aufweisen. 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 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)
Hinweis Für die Codepage 65001 (UTF-8) oder die Codepage 54936 (GB18030, Windows Vista und höher) muss dwFlags entweder auf 0 oder WC_ERR_INVALID_CHARS festgelegt werden. Andernfalls schlägt die Funktion mit ERROR_INVALID_FLAGS fehl.
 

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

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

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

Wie unter Verwenden der Unicode-Normalisierung zum Darstellen von Zeichenfolgen erläutert, ermöglicht Unicode mehrere Darstellungen derselben Zeichenfolge (linguistisch interpretiert). Beispielsweise kann Groß-A mit Dieresis (Umlaut) entweder als einzelner Unicode-Codepunkt "Ä" (U+00C4) vorkompiliert oder als Kombination aus Groß-A und dem kombinierenden Dieresezeichen ("A" + " ̈", d. h. U+0041 U+0308) zerlegt werden. Die meisten Codepages enthalten jedoch nur zusammengesetzte Zeichen.

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

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ßen von Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

MultiByteToWideChar

Unicode- und Zeichensatzfunktionen

Unicode und Zeichensätze

In VBS-Enclaves verfügbare Vertdll-APIs