RtlUnicodeToUTF8N-Funktion (ntifs.h)

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

Syntax

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

Parameter

[out] UTF8StringDestination

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

[in] UTF8StringMaxByteCount

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

[out] UTF8StringActualByteCount

Ein Zeiger auf eine Position, in die die Routine die tatsächliche Anzahl von Bytes schreibt, die sie in den Puffer geschrieben hat, auf den utf8StringDestination verweist. Wenn UTF8StringDestination- nichtNULL-ist, überschreitet diese Anzahl niemals den Wert UTF8StringMaxByteCount. Wenn UTF8StringDestination-NULL-ist, ist diese Anzahl die Anzahl der Bytes, die erforderlich sind, um die gesamte Ausgabezeichenfolge zu enthalten.

[in] UnicodeStringSource

Ein Zeiger auf die Unicode-Quellzeichenfolge.

[in] UnicodeStringByteCount

Gibt die Anzahl der Bytes in der Unicode-Quellzeichenfolge an, auf die der UnicodeStringSource Parameter verweist.

Rückgabewert

RtlUnicodeToUTF8N gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist und alle Unicode-Zeichencodes in der Eingabezeichenfolge in die entsprechenden UTF-8-Zeichencodes in der Ausgabezeichenfolge konvertiert wurden. Sie gibt STATUS_SOME_NOT_MAPPED zurück, wenn der Aufruf erfolgreich ist, aber mindestens ein Eingabezeichen ungültig waren und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt wurden, bevor sie in UTF-8 konvertiert wurden. Mögliche Fehlerrücklaufwerte sind die folgenden Fehlercodes:

Bemerkungen

Die UTF-8-Ausgabezeichenfolge wird nur null beendet, wenn die Unicode-Eingabezeichenfolge null-beendet ist.

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

Sie können einen ersten Aufruf an RtlUnicodeToUTF8N- durchführen, um die erforderliche Ausgabepuffergröße abzurufen, und dann RtlUnicodeToUTF8N erneut aufrufen, um die Unicode-Ausgabezeichenfolge abzurufen. Legen Sie im ersten Aufruf UTF8StringDestination = NULL- und UTF8StringMaxByteCount = 0 fest, und die Routine schreibt die erforderliche Puffergröße in *UTF8StringActualByteCount. Weisen Sie als Nächstes einen Puffer der erforderlichen Größe zu, und rufen Sie RtlUnicodeToUTF8N ein zweites Mal auf, um die UTF-8-Ausgabezeichenfolge abzurufen.

RtlUnicodeToUTF8N- unterstützt Unicode-Ersatzpaare. Ein vorangestellter Wortwert, auf den kein nachfolgender Wortwert folgt, oder ein nachgestellter Wortwert, der keinem führenden Wortwert vorangestellt ist, wird jedoch nicht als gültiger Zeichencode erkannt und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt.

RtlUnicodeToUTF8N die Eingabezeichenfolge weiterhin in eine Ausgabezeichenfolge konvertiert, bis sie das Ende des Quellpuffers oder das Ende des Zielpuffers erreicht, je nachdem, was zuerst auftritt. Die Routine konvertiert alle NULL-Zeichen in der Eingabezeichenfolge in NULL-Zeichen in der Ausgabezeichenfolge. Wenn die Eingabezeichenfolge ein endendes NULL-Zeichen enthält, das Nullzeichen jedoch nicht am Ende des Quellpuffers liegt, wird die Routine über das endende Nullzeichen fortgesetzt, bis es das Ende des verfügbaren Pufferraums erreicht.

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

Sie können RtlUnicodeToUTF8N- und RtlUTF8ToUnicodeN Routinen verwenden, um eine verlustlose Konvertierung gültiger Textzeichenfolgen zwischen den Unicode- und UTF-8-Formaten durchzuführen. Zeichenfolgen mit beliebigen Datenwerten verstoßen jedoch wahrscheinlich gegen die Unicode-Regeln für die Codierung von Ersatzpaaren, 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

Siehe auch

RtlUTF8ToUnicodeN