MultiByteToWideChar

Aus API-Wiki
Zur Navigation springenZur Suche springen

Die API-Funktion MultiByteToWideChar konvertiert einen einbyte/mehrbyte-Character-String in einen Wide-Character-Unicodestring der Kodierung UTF16.

Declare Function MultiByteToWideChar lib "kernel32.dll" ( _
                 ByVal CodePage As Long, _
                 ByVal dwFlags As Long, _
                 ByVal lpMultiByteStr As Long, _
                 ByVal cbMultiByte As Long, _
                 ByVal lpWideCharStr As Long, _
                 ByVal cchWideChar As Long) As Long


Parameter

CodePage

Die Codepage, die bei der Konversion verwendet werden soll. Es kann jede im System installierte Codepage verwendet werden oder eine aus der folgenden Liste. Die Liste ist nicht vollständig; sie zeigt nur mögliche Werte:
Private Const CP_ACP        As Long = 0     ' ANSI Code Page
Private Const CP_OEMCP      As Long = 1     ' OEM Code page
Private Const CP_MACCP      As Long = 2     '
Private Const CP_THREAD_ACP As Long = 3     '
Private Const CP_SYMBOL     As Long = 42    '
Private Const CP_ISO8859_4  As Long = 28594 ' Baltisch
Private Const CP_ISO8859_15 As Long = 28605 ' Lateinisch 9
Private Const CP_UTF7       As Long = 65000 ' UTF-7 code page
Private Const CP_UTF8       As Long = 65001 ' UTF-8 code page
' Die Werte der Konstanten kann man auch in der Regions-Einstellung nachlesen.
' siehe: Systemsteuerung->Regions und Sprachoptionen->Erweitert->Codepagekonvertierungstabelle

für eine komplette Liste siehe Code Page Identifiers

dwFlags

Es kann eine Kombination aus folgenden Flags verwendet werden. MB_PRECOMPOSED und MB_COMPOSITE können jedoch nicht zusammen verwendet werden.
Private Const MB_NOFLAGS           As Long = &H0 ' es werden keine Flags verwendet
Private Const MB_PRECOMPOSED       As Long = &H1 ' Always use precomposed characters — that is, characters in
                                                 ' which a base character and a nonspacing character have a
                                                 ' single character value. This is the default translation 
                                                 ' option. Cannot be used with MB_COMPOSITE.

Private Const MB_COMPOSITE         As Long = &H2 ' Always use composite characters — that is, characters in
                                                 ' which a base character and a nonspacing character have
                                                 ' different character values. 
                                                 ' Cannot be used with MB_PRECOMPOSED.

Private Const MB_USEGLYPHCHARS     As Long = &H4 ' Use glyph characters instead of control characters

Private Const MB_ERR_INVALID_CHARS As Long = &H8 ' Wenn die Funktion auf ein ungültiges Zeichen stößt,
                                                 ' it fails and GetLastError liefert 
                                                 ' ERROR_NO_UNICODE_TRANSLATION.

lpMultiByteStr

[in] Zeiger auf die 8-Bit-Zeichenfolge, die konvertiert werden soll.

cbMultiByte

[in] Größe, in Bytes, der 8-Bit-Zeichenfolge, die konvertiert werden soll. Wenn hier -1 angegeben wird und der String mit einem Nullzeichen terminiert ist, so wird die Länge automatsich ermittelt.

lpWideCharStr

[out] Zeiger auf einen Puffer, der den übersetzten UTF-16-String empfängt.

cchWideChar

[in] Größe, in Wide-Characters, des Puffers, der den übersetzten UTF-16-String enthält. Wenn hier 0 übergeben wird, liefert die Funktion die erforderliche Größe in UTF-16-Codeeinheiten zurück, ohne die Übersetzung durchzuführen.

Rückgabe

Anzahl der UTF-16-Codeeinheiten, die in den Puffer geschrieben wurden, wenn die Funktion erfolgreich war und cchWideChar <> 0 ist. Anmerkung: Die zurückgegebene Länge enthält ein Null-Terminierungszeichen.

Null deutet auf einen Fehler hin. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf (in VBC: Err.LastDLLError). Mögliche Werte für GetLastError:

Private Const ERROR_INVALID_PARAMETER      As Long = 87
Private Const ERROR_INSUFFICIENT_BUFFER    As Long = 122
Private Const ERROR_INVALID_FLAGS          As Long = 1004&
Private Const ERROR_NO_UNICODE_TRANSLATION As Long = 1113&

Anmerkungen:

Der Fehler ERROR_INVALID_PARAMETER tritt auf, wenn lpMultiByteStr und lpWideCharStr auf den gleichen Speicherbereich zeigen.

Der Fehler ERROR_NO_UNICODE_TRANSLATION tritt auf wenn das Flag MB_ERR_INVALID_CHARS gesetzt ist und wenn der Quellstring ein ungültiges Zeichen enthält. Ein ungültiges Zeichen ist ein führendes (leading) Byte, dass kein folgendes (trail) Byte besitzt. Wenn MB_ERR_INVALID_CHARS nicht gesetzt ist wird ein ungültiges Zeichen in ein Defaultzeichen übersetzt.

Der Fehler ERROR_INSUFFICIENT_BUFFER tritt auf, wenn der Puffer, in den hineingeschrieben werden soll, nicht die erforderliche Länge aufweist.

Beispiel

FAQ 0155: Wie konvertiere ich eine VB-Zeichenkette nach UTF-8 oder zurück?

Betriebssystem

Die Funktion ist unter folgenden Betriebssystemen funktionsfähig:

  • Windows 95 mit Unicodeerweiterung
  • Windows 98 mit Unicodeerweiterung
  • Windows NT 3.1 und später
  • Windows 2000
  • Windows XP
  • Windows Vista

Verwandte Funktionen

Api1 - MultiByteToWideChar
Api2 - Beschreibung

Verweise

Unicode Functions WideCharToMultiByte

Quellen