RtlUnicodeStringToUTF8String-Funktion (ntifs.h)
RtlUnicodeStringToUTF8String konvertiert die angegebene Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge.
Syntax
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parameter
DestinationString
Zeiger auf den Puffer, in dem die konvertierte UTF-8-Ausgabezeichenfolge platziert wird. Das Feld DestinationString-MaximumLength> wird nur festgelegt, wenn AllocateDestinationString auf TRUE festgelegt ist.
SourceString
Zeiger auf die Unicode-Zeichenfolge, die in UTF-8 konvertiert werden soll.
AllocateDestinationString
Boolescher Wert. Wenn TRUE festgelegt ist, ordnet RtlUnicodeStringToUTF8String den Pufferbereich für die Zielzeichenfolge zu. Nur Speicher für DestinationString-Buffer> wird von dieser API zugeordnet. Wenn RtlUnicodeStringToUTF8String die Pufferzuordnung durchführt, muss der Aufrufer die Zuordnung des Puffers mithilfe von RtlFreeUTF8String aufheben.
Rückgabewert
Diese Funktion gibt STATUS_SUCCESS zurück, wenn die Konvertierung erfolgreich ist. Mögliche Fehler- oder Warnungscodes sind:
| Code | BESCHREIBUNG |
|---|---|
| STATUS_INVALID_PARAMETERX | Fehler: Einer der Parameterwerte ist ungültig. |
| STATUS_NO_MEMORY | Fehler: RtlUnicodeStringToUTF8String konnte Pufferspeicher nicht zuordnen. |
| STATUS_BUFFER_OVERFLOW | Warnung: Die konvertierte Zeichenfolge in DestinationString-Buffer> wird aufgrund unzureichenden Speicherplatzes im Zielpuffer abgeschnitten. |
| STATUS_SOME_NOT_MAPPED | Warnung: Der Aufruf war erfolgreich, aber eines oder mehrere der Eingabezeichen waren ungültig und wurden vor der Konvertierung in UTF-8 durch das Unicode-Ersetzungszeichen U+FFFD ersetzt. |
Hinweise
Die UTF-8-Ausgabezeichenfolge ist nur dann NULL-endend, wenn die Unicode-Eingabezeichenfolge null-terminated ist.
RtlUnicodeStringToUTF8String 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ültiger Zeichencode erkannt und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt.
RtlUnicodeStringToUTF8String 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 RtlUTF8StringToUnicodeString-Routine konvertiert eine UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.
Sie können die Routinen RtlUnicodeStringToUTF8String und RtlUTF8StringToUnicodeString verwenden , um eine verlustfreie Konvertierung gültiger Textzeichenfolgen zwischen den Formaten Unicode und UTF-8 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) | Windows 10, Version 2004 |
| Kopfzeile | ntifs.h |