RtlUnicodeToUTF8N-Funktion

Übersetzt die angegebene Unicode-Zeichenfolge mithilfe der Codepage 8-Bit Unicode Transformation Format (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 zugeordneten Puffer, um die übersetzte Zeichenfolge zu empfangen.

UTF8StringMaxByteCount [ In]

Maximale Anzahl von Bytes, die in UTF8StringDestination geschrieben werden sollen. Wenn dieser Wert bewirkt, dass die übersetzte Zeichenfolge abgeschnitten wird, gibt RtlUnicodeToUTF8N einen Fehlerstatus 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 abgeschnittene Zeichenfolgenanzahl.

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 zeigt.

Rückgabewert

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

Rückgabecode Beschreibung
STATUS _ ERFOLGREICH
Die Unicode-Zeichenfolge wurde in UTF-8 konvertiert.
STATUS _ EINIGE _ NICHT _ ZUGEORDNET
Ein ungültiges Eingabezeichen wurde gefunden und ersetzt. Dieser Status wird als Erfolgsstatus betrachtet.
STATUS _ UNGÜLTIGER _ PARAMETER
Beide Zeiger auf UTF8StringDestination und UTF8StringActualByteCount waren NULL.
STATUS _ UNGÜLTIGER _ PARAMETER _ 4
UnicodeStringSource war NULL.
STATUSPUFFER _ _ ZU _ KLEIN
UTF8StringDestination wurde abgeschnitten.

Hinweise

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. Sie gibt eine auf NULL endende UTF-8-Zeichenfolge zurück, wenn die angegebene UnicodeStringSource ein NULL-Abschlusszeichen enthielt und die angegebene UTF8StringMaxByteCount keine Kürzung verursacht hat.

Wenn die Ausgabe abgeschnitten wird und ein ungültiges Eingabezeichen gefunden wird, gibt die Funktion den Fehler STATUS _ BUFFER _ TOO SMALL _ zurück.

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

Aufrufer von RtlUnicodeToUTF8N müssen auf IRQL < DISPATCH LEVEL ausgeführt _ werden.

Anforderungen

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

Siehe auch

RtlUTF8ToUnicodeN