RtlUnicodeStringToUTF8String-Funktion (ntifs.h)
RtlUnicodeStringToUTF8String die angegebene Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge konvertiert.
Syntax
NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
PUTF8_STRING DestinationString,
PCUNICODE_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parameter
DestinationString
Zeigen Sie auf den Puffer, in dem die konvertierte UTF-8-Ausgabezeichenfolge platziert wird. Das DestinationString->MaximumLength-Feld wird nur festgelegt, wenn "AllocateDestinationString"- WAHR ist.
SourceString
Zeiger auf die Unicode-Zeichenfolge, die in UTF-8 konvertiert werden soll.
AllocateDestinationString
Boolescher Wert. Beim Festlegen von TRUE weist RtlUnicodeStringToUTF8String den Pufferbereich für die Zielzeichenfolge zu. Nur Speicher für DestinationString->Buffer wird von dieser API zugewiesen. Wenn RtlUnicodeStringToUTF8String die Pufferzuweisung durchführt, muss der Aufrufer den Puffer mithilfe RtlFreeUTF8String.
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 unzureichendem Speicherplatz im Zielpuffer abgeschnitten. |
| STATUS_SOME_NOT_MAPPED | Warnung: Der Aufruf war erfolgreich, aber mindestens ein Eingabezeichen war ungültig und wurde durch das Unicode-Ersetzungszeichen U+FFFD ersetzt, bevor er in UTF-8 konvertiert wurde. |
Bemerkungen
Die UTF-8-Ausgabezeichenfolge wird nur null beendet, wenn die Unicode-Eingabezeichenfolge null-beendet ist.
RtlUnicodeStringToUTF8String 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.
RtlUnicodeStringToUTF8String 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 RtlUTF8StringToUnicodeString Routine konvertiert eine UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.
Sie können die RtlUnicodeStringToUTF8String und RtlUTF8StringToUnicodeString 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
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 10, Version 2004 |
| Header- | ntifs.h |