RtlUTF8ToUnicodeN-Funktion

Artikel
06/13/2023

Übersetzt die angegebene Quellzeichenfolge mithilfe der UTF-8-Codepage (8-Bit Unicode Transformation Format) in eine Unicode-Zeichenfolge.

Syntax

NTSTATUS WINAPI RtlUTF8ToUnicodeN(
  _Out_     PWSTR  UnicodeStringDestination,
  _In_      ULONG  UnicodeStringMaxByteCount,
  _Out_opt_ PULONG UnicodeStringActualByteCount,
  _In_      PCCH   UTF8StringSource,
  _In_      ULONG  UTF8StringByteCount
);

Parameter

UnicodeStringDestination [out]: Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die übersetzte Zeichenfolge empfängt.
UnicodeStringMaxByteCount [in]: Maximale Anzahl von Bytes, die bei UnicodeStringDestination geschrieben werden sollen. Wenn dieser Wert dazu führt, dass die übersetzte Zeichenfolge abgeschnitten wird, gibt RtlUTF8ToUnicodeN einen Fehler status zurück.
UnicodeStringActualByteCount [out, optional]: Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Länge der übersetzten Zeichenfolge in Bytes empfängt. Dieser Parameter ist optional und kann NULL sein. Wenn die Zeichenfolge abgeschnitten wird, zählt die zurückgegebene Zahl die tatsächliche Anzahl abgeschnittener Zeichenfolgen.
UTF8StringSource [in]: Ein Zeiger auf die zu übersetzende Zeichenfolge.
UTF8StringByteCount [in]: Größe der Zeichenfolge in Bytes bei UTF8StringSource.

Rückgabewert

RtlUTF8ToUnicodeN gibt einen der folgenden NTSTATUS-Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Zeichenfolge wurde in Unicode konvertiert.
STATUS_SOME_NOT_MAPPED	Es wurde ein ungültiges Eingabezeichen gefunden und ersetzt. Diese status gilt als erfolgreich status.
STATUS_INVALID_PARAMETER	Beide Zeiger auf UnicodeStringDestination und UnicodeStringActualByteCount waren NULL.
STATUS_INVALID_PARAMETER_4	Utf8StringSource war NULL.
STATUS_BUFFER_TOO_SMALL	UnicodeStringDestination wurde abgeschnitten.

Bemerkungen

Obwohl UnicodeStringActualByteCount optional ist und NULL sein kann, sollten Aufrufer Speicher dafür bereitstellen, da die empfangene Länge verwendet werden kann, um zu bestimmen, ob die Konvertierung erfolgreich war.

Wenn die Ausgabe abgeschnitten wird und ein ungültiges Eingabezeichen gefunden wird, gibt die Funktion STATUS_BUFFER_TOO_SMALL Fehler zurück.

Wenn die UnicodeStringDestination auf NULL festgelegt ist, gibt die Funktion die erforderliche Anzahl von Bytes zurück, um die übersetzte Zeichenfolge ohne Abschneiden in UnicodeStringActualByteCount zu hosten.

RtlUTF8ToUnicodeN ändert die Quellzeichenfolge nur, wenn die Zeiger UnicodeStringDestination und UTF8StringSource gleichwertig sind. Die zurückgegebene Unicode-Zeichenfolge ist nicht NULL-beendet.

Aufrufer von RtlUTF8ToUnicodeN müssen unter IRQL < DISPATCH_LEVEL ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Header	Wdm.h
DLL	Ntdll.dll

Siehe auch

RtlUnicodeToUTF8N

Freigeben über