RtlUTF8StringToUnicodeString-Funktion (ntifs.h)
Die RtlUTF8StringToUnicodeString Routine konvertiert die angegebene UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.
Syntax
NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
PUNICODE_STRING DestinationString,
PUTF8_STRING SourceString,
BOOLEAN AllocateDestinationString
);
Parameter
DestinationString
Zeigen Sie auf den Puffer, in dem die konvertierte Unicode-Ausgabezeichenfolge gespeichert ist. Das DestinationString->MaximumLength-Feld wird nur festgelegt, wenn "AllocateDestinationString"- WAHR ist.
SourceString
Zeiger auf die UTF-8-Quellzeichenfolge, die in Unicode konvertiert werden soll.
AllocateDestinationString
Boolescher Wert. Bei Festlegung von TRUE weist RtlUTF8StringToUnicodeString den Pufferbereich für die Zielzeichenfolge zu. Nur Speicher für DestinationString->Buffer wird von dieser API zugewiesen. Wenn RtlUTF8StringToUnicodeString die Pufferzuweisung durchführt, muss der Aufrufer den Puffer mithilfe RtlFreeUnicodeString-.
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: RtlUTF8StringToUnicodeString- konnte keinen Pufferspeicher 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 vom Unicode-Ersetzungszeichen U+FFFD konvertiert, bevor er in UTF-8 konvertiert wurde. |
Bemerkungen
Die Unicode-Ausgabezeichenfolge wird nur null beendet, wenn die UTF-8-Eingabezeichenfolge null-beendet ist.
RtlUTF8StringToUnicodeString unterstützt Unicode-Ersatzpaare. Ein vorangestellter Wortwert, auf den kein nachfolgender Wortwert folgt, oder ein nachfolgender Wortwert, der nicht einem führenden Wortwert vorausgeht, wird jedoch nicht als gültiges Zeichen erkannt und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt.
RtlUTF8StringToUnicodeString die Eingabezeichenfolge weiterhin in eine Ausgabezeichenfolge konvertiert, 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 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 RtlUnicodeStringToUTF8String Routine konvertiert eine Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge.
Sie können die RtlUTF8StringToUnicodeString und RtlUnicodeStringToUTF8String Routinen verwenden, um eine verlustlose Konvertierung gültiger Textzeichenfolgen zwischen den UTF-8- und Unicode-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 |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h, Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |