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, die die Routine in den Puffer schreiben kann, auf den UTF8StringDestination zeigt. Wenn UTF8StringDestination = NULL ist, legen Sie UTF8StringMaxByteCount = 0 fest.
[out] UTF8StringActualByteCount
Ein Zeiger auf einen Speicherort, in den die Routine die tatsächliche Anzahl von Bytes schreibt, die sie geschrieben hat, in den Puffer, auf den UTF8StringDestination verweist. Wenn UTF8StringDestination ungleich NULL ist, übersteigt diese Anzahl nie den Wert von UTF8StringMaxByteCount. Wenn UTF8StringDestinationNULL 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. Es wird STATUS_SOME_NOT_MAPPED zurückgegeben, wenn der Aufruf erfolgreich war, aber ein oder mehrere Eingabezeichen ungültig waren und durch das Unicode-Ersetzungszeichen U+FFFD ersetzt wurden, bevor sie in UTF-8 konvertiert wurden. Mögliche Fehlerrückgabewerte sind die folgenden Fehlercodes:
Rückgabecode | Beschreibung |
---|---|
|
Der UTF8StringMaxByteCount-Parameter gibt eine Puffergröße an, die zu klein ist, um die gesamte Ausgabezeichenfolge zu enthalten. |
|
Die Parameter UTF8StringDestination und UTF8StringActualByteCount sind beide NULL. |
|
Der UnicodeStringSource-Parameter ist NULL. |
|
UnicodeStringByteCount ist kein ganzzahliges Vielfaches von sizeof(WCHAR). |
Hinweise
Die UTF-8-Ausgabezeichenfolge ist nur dann NULL-endend, wenn die Unicode-Eingabezeichenfolge null-terminated 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 passen, und der Wert *UTF8StringActualByteCount gibt die Anzahl gültiger Bytes an, die die Routine in den Puffer geschrieben hat. Die partielle Zeichenfolge, die im Ausgabepuffer enthalten ist, enthält möglicherweise kein beendendes NULL-Zeichen.
Sie können rtlUnicodeToUTF8N zunächst aufrufen, 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. Ordnen Sie als Nächstes einen Puffer der erforderlichen Größe zu, und rufen Sie rtlUnicodeToUTF8N ein zweites Mal auf, um die UTF-8-Ausgabezeichenfolge zu erhalten.
RtlUnicodeToUTF8N 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.
RtlUnicodeToUTF8N 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 RtlUTF8ToUnicodeN-Routine konvertiert eine UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.
Sie können die Routinen RtlUnicodeToUTF8N und RtlUTF8ToUnicode 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 7 |
Zielplattform | Universell |
Header | ntifs.h (include Ntifs.h, Wdm.h, Ntifs.h) |
Bibliothek | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL |
Weitere Informationen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für