RtlUnicodeToUTF8N-Funktion

Artikel
06/13/2023

Übersetzt die angegebene Unicode-Zeichenfolge mithilfe der 8-Bit-Utf-Transformationsformat-Codepage (UTF-8) in eine neue Zeichenfolge.

Syntax

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

Parameter

UTF8StringDestination [out]: Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, um die übersetzte Zeichenfolge zu empfangen.
UTF8StringMaxByteCount [in]: Maximale Anzahl von Bytes, die in UTF8StringDestination geschrieben werden sollen. Wenn dieser Wert dazu führt, dass die übersetzte Zeichenfolge abgeschnitten wird, gibt RtlUnicodeToUTF8N einen Fehler status zurück.
UTF8StringActualByteCount [out, optional]: Ein Zeiger auf eine vom Aufrufer zugeordnete 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.
UnicodeStringSource [in]: Ein Zeiger auf die zu übersetzende Unicode-Quellzeichenfolge.
*UnicodeStringByteCount * [in]: Gibt die Anzahl der Bytes in der Unicode-Quellzeichenfolge an, auf die der UnicodeStringSource-Parameter verweist.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Unicode-Zeichenfolge wurde in UTF-8 konvertiert.
STATUS_SOME_NOT_MAPPED	Es wurde ein ungültiges Eingabezeichen gefunden und ersetzt. Diese status gilt als erfolg status.
STATUS_INVALID_PARAMETER	Beide Zeiger auf UTF8StringDestination und UTF8StringActualByteCount waren NULL.
STATUS_INVALID_PARAMETER_4	UnicodeStringSource war NULL.
STATUS_BUFFER_TOO_SMALL	UTF8StringDestination wurde abgeschnitten.

Bemerkungen

Obwohl UTF8StringActualByteCount 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. Diese Routine ändert die Quellzeichenfolge nicht. Es wird eine MIT NULL beendete UTF-8-Zeichenfolge zurückgegeben, wenn die angegebene UnicodeStringSource einen NULL-Abschlussator enthält und wenn der angegebene UTF8StringMaxByteCount keine Abschneidung verursacht hat.

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

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

Aufrufer von RtlUnicodeToUTF8N 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

RtlUTF8ToUnicodeN

Freigeben über