RtlUTF8ToUnicodeN-Funktion (wdm.h)

Die RtlUTF8ToUnicodeN-Routine konvertiert eine UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.

Syntax

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

Parameter

[out, optional] UnicodeStringDestination

Ein Zeiger auf einen vom Aufrufer zugewiesenen Zielpuffer, in den die Routine die Unicode-Ausgabezeichenfolge schreibt. Wenn dieser Parameter NULL ist, schreibt die Routine die erforderliche Größe des Ausgabepuffers in *UnicodeStringActualByteCount.

[in] UnicodeStringMaxByteCount

Gibt die maximale Anzahl von Bytes an, die die Routine in den Puffer schreiben kann, auf den UnicodeStringDestination verweist. Wenn UnicodeStringDestination = NULL ist, legen Sie UnicodeStringMaxByteCount = 0 fest.

[out] UnicodeStringActualByteCount

Ein Zeiger auf einen Speicherort, in den die Routine die tatsächliche Anzahl von Bytes schreibt, die die Routine in den Puffer schreibt, auf den UnicodeStringDestination verweist. Wenn UnicodeStringDestination ungleich NULL ist, übersteigt diese Anzahl nie den Wert von UnicodeStringMaxByteCount. Wenn UnicodeStringDestinationNULL ist, ist diese Anzahl die Anzahl der Bytes, die erforderlich sind, um die gesamte Ausgabezeichenfolge zu enthalten.

[in] UTF8StringSource

Ein Zeiger auf die UTF-8-Quellzeichenfolge.

[in] UTF8StringByteCount

Gibt die Anzahl der Bytes in der UTF-8-Quellzeichenfolge an, auf die der UTF8StringSource-Parameter verweist.

Rückgabewert

RtlUTF8ToUnicodeN gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist und alle UTF-8-Zeichencodes in der Eingabezeichenfolge in die entsprechenden Unicode-Zeichencodes in der Ausgabezeichenfolge konvertiert wurden. Es wird STATUS_SOME_NOT_MAPPED zurückgegeben, wenn der Aufruf erfolgreich war, aber ein oder mehrere Eingabezeichen ungültig waren und in das Unicode-Ersetzungszeichen U+FFFD konvertiert wurden. Mögliche Fehlerrückgabewerte sind die folgenden Fehlercodes:

Rückgabecode	Beschreibung
STATUS_BUFFER_TOO_SMALL	Der UnicodeStringMaxByteCount-Parameter gibt eine Puffergröße an, die zu klein ist, um die gesamte Ausgabezeichenfolge zu enthalten.
STATUS_INVALID_PARAMETER	Die Parameter UnicodeStringDestination und UnicodeStringActualByteCount sind beide NULL.
STATUS_INVALID_PARAMETER_4	Der UTF8StringSource-Parameter ist NULL.

Hinweise

Die Unicode-Ausgabezeichenfolge ist nur dann NULL-endend, wenn die UTF-8-Eingabezeichenfolge null-terminated ist.

Die Routine gibt STATUS_BUFFER_TOO_SMALL zurück, wenn der UnicodeStringMaxByteCount-Parameter eine Puffergröße angibt, die zu klein ist, um die gesamte Ausgabezeichenfolge zu enthalten. In diesem Fall schreibt die Routine so viele Unicode-Zeichen, wie in den Puffer passen, und der Wert *UnicodeStringActualByteCount gibt die Anzahl gültiger Bytes an, die die Routine in den Puffer geschrieben hat. Die partielle Zeichenfolge, die im Ausgabepuffer enthalten ist, enthält möglicherweise kein beendendes NULL-Zeichen.

Sie können rtlUTF8ToUnicodeN zunächst aufrufen, um die erforderliche Ausgabepuffergröße abzurufen, und dann RtlUTF8ToUnicodeN erneut aufrufen, um die Unicode-Ausgabezeichenfolge abzurufen. Legen Sie im ersten Aufruf UnicodeStringDestination = NULL und UnicodeStringMaxByteCount = 0 fest, und die Routine schreibt die erforderliche Puffergröße in *UnicodeStringActualByteCount. Ordnen Sie als Nächstes einen Puffer der erforderlichen Größe zu, und rufen Sie RtlUTF8ToUnicodeN ein zweites Mal auf, um die Unicode-Ausgabezeichenfolge abzurufen.

RtlUTF8ToUnicodeN unterstützt Unicode-Ersatzzeichenpaare. Ein ersatzführender Wortwert, auf den kein nachgestellter Wortwert folgt, oder ein nachgestellter Wortwert, dem kein führender Wortwert vorangestellt ist, wird jedoch nicht als gültiges Zeichen erkannt und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt.

RtlUTF8ToUnicodeN konvertiert die Eingabezeichenfolge weiterhin in eine Ausgabezeichenfolge, bis sie das Ende des Quellpuffers oder das Ende des Zielpuffers erreicht, je nachdem, was zuerst eintritt. Die Routine konvertiert alle NULL-Zeichen in der Eingabezeichenfolge in NULL-Zeichen in der Ausgabezeichenfolge. Wenn die Eingabezeichenfolge ein abschließendes NULL-Zeichen enthält, sich das NULL-Zeichen jedoch nicht am Ende des Quellpuffers befindet, wird die Routine über das abschließende NULL-Zeichen hinaus fortgesetzt, bis das Ende des verfügbaren Pufferbereichs erreicht ist.

Die RtlUnicodeToUTF8N-Routine konvertiert eine Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge.

Sie können die Routinen RtlUTF8ToUnicode und RtlUnicodeToUTF8N verwenden, um eine verlustfreie Konvertierung gültiger Textzeichenfolgen zwischen den Formaten UTF-8 und Unicode durchzuführen. Zeichenfolgen mit beliebigen Datenwerten verstoßen jedoch wahrscheinlich gegen die Unicode-Regeln für die Codierung von Ersatzzeichenpaaren, und alle Informationen, die in den ungültigen Werten in einer Eingabezeichenfolge enthalten sind, gehen verloren und können nicht aus der resultierenden Ausgabezeichenfolge wiederhergestellt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und späteren Windows-Versionen.
Zielplattform	Universell
Header	wdm.h (include Ntifs.h, Wdm.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Weitere Informationen

RtlUnicodeToUTF8N