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, _
                ByRef lpMultiByteStr As Byte, _
                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

Quellen