WideCharToMultiByte-Funktion (stringapiset.h)
Ordnet eine UTF-16-Zeichenfolge (Breitzeichen) einer neuen Zeichenfolge zu. Die neue Zeichenfolge stammt nicht unbedingt aus einem Multibyte-Zeichensatz.
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.
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.
| Wert | Bedeutung | ||||||
|---|---|---|---|---|---|---|---|
|
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 .
|
||||||
|
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. | ||||||
|
Ü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)
[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 |