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
Zeiger auf den Puffer, in dem die konvertierte Unicode-Ausgabezeichenfolge gespeichert ist. Das Feld DestinationString-MaximumLength> wird nur festgelegt, wenn AllocateDestinationString auf TRUE festgelegt ist.
SourceString
Zeiger auf die UTF-8-Quellzeichenfolge, die in Unicode konvertiert werden soll.
AllocateDestinationString
Boolescher Wert. Wenn true festgelegt ist, ordnet RtlUTF8StringToUnicodeString den Pufferbereich für die Zielzeichenfolge zu. Nur Speicher für DestinationString-Buffer> wird von dieser API zugeordnet. Wenn RtlUTF8StringToUnicodeString die Pufferzuordnung durchführt, muss der Aufrufer die Zuordnung des Puffers mithilfe von RtlFreeUnicodeString 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: RtlUTF8StringToUnicodeString 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 vom Unicode-Ersetzungszeichen U+FFFD konvertiert. |
Hinweise
Die Unicode-Ausgabezeichenfolge ist nur dann NULL-endend, wenn die UTF-8-Eingabezeichenfolge null-terminated ist.
RtlUTF8StringToUnicodeString 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ültiges Zeichen erkannt und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt.
RtlUTF8StringToUnicodeString 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 RtlUnicodeStringToUTF8String-Routine konvertiert eine Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge.
Sie können die Routinen RtlUTF8StringToUnicodeString und RtlUnicodeStringToUTF8String verwenden, um eine verlustfreie Konvertierung gültiger Textzeichenfolgen zwischen den Formaten UTF-8 und Unicode 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 |
| Zielplattform | Universell |
| Header | ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |