RtlUTF8ToUnicodeN-Funktion (ntifs.h)
Die RtlUTF8ToUnicodeN Routine konvertiert eine UTF-8-Zeichenfolge in eine Unicode-Zeichenfolge.
Syntax
NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
[out, optional] PWSTR UnicodeStringDestination,
[in] ULONG UnicodeStringMaxByteCount,
[out] PULONG UnicodeStringActualByteCount,
[in] PCCH UTF8StringSource,
[in] ULONG UTF8StringByteCount
);
Parameter
[out, optional] UnicodeStringDestination
Ein Zeiger auf einen vom Aufrufer zugewiesenen Zielpuffer, in den die Routine die Unicode-Ausgabezeichenfolge schreibt. Wenn dieser Parameter NULL-ist, schreibt die Routine die erforderliche Größe des Ausgabepuffers in *UnicodeStringActualByteCount.
[in] UnicodeStringMaxByteCount
Gibt die maximale Anzahl von Bytes an, auf die die Routine in den Puffer schreiben kann, auf den UnicodeStringDestination verweist. Wenn UnicodeStringDestination = NULL-, legen Sie UnicodeStringMaxByteCount = 0 fest.
[out] UnicodeStringActualByteCount
Ein Zeiger auf eine Position, in die die Routine die tatsächliche Anzahl von Bytes schreibt, die die Routine in den Puffer geschrieben hat, der UnicodeStringDestination verweist. Wenn UnicodeStringDestination- nichtNULL-ist, überschreitet diese Anzahl niemals den Wert UnicodeStringMaxByteCount. Wenn UnicodeStringDestination-NULL-ist, ist diese Anzahl die Anzahl der Bytes, die erforderlich sind, um die gesamte Ausgabezeichenfolge zu enthalten.
[in] UTF8StringSource
Ein Zeiger auf die UTF-8-Quellzeichenfolge.
[in] UTF8StringByteCount
Gibt die Anzahl der Bytes in der UTF-8-Quellzeichenfolge an, auf die der UTF8StringSource--Parameter verweist.
Rückgabewert
RtlUTF8ToUnicodeN gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist und alle UTF-8-Zeichencodes in der Eingabezeichenfolge in die entsprechenden Unicode-Zeichencodes in der Ausgabezeichenfolge konvertiert wurden. Sie gibt STATUS_SOME_NOT_MAPPED zurück, wenn der Aufruf erfolgreich ist, aber mindestens ein Eingabezeichen ungültig waren und in das Unicode-Ersetzungszeichen U+FFFD konvertiert wurden. Mögliche Fehlerrücklaufwerte sind die folgenden Fehlercodes:
| Rückgabecode | Beschreibung |
|---|---|
|
Der parameter UnicodeStringMaxByteCount gibt eine Puffergröße an, die zu klein ist, um die gesamte Ausgabezeichenfolge zu enthalten. |
|
Die parameter UnicodeStringDestination und UnicodeStringActualByteCount sind beide NULL-. |
|
Der UTF8StringSource Parameter ist NULL. |
Bemerkungen
Die Unicode-Ausgabezeichenfolge wird nur null beendet, wenn die UTF-8-Eingabezeichenfolge null-beendet ist.
Die Routine gibt STATUS_BUFFER_TOO_SMALL zurück, wenn der UnicodeStringMaxByteCount Parameter eine Puffergröße angibt, die zu klein ist, um die gesamte Ausgabezeichenfolge zu enthalten. In diesem Fall schreibt die Routine so viele Unicode-Zeichen wie in den Puffer, und der Wert *UnicodeStringActualByteCount gibt die Anzahl gültiger Bytes an, die die Routine in den Puffer geschrieben hat. Die teilweise Zeichenfolge, die im Ausgabepuffer enthalten ist, enthält möglicherweise kein endendes NULL-Zeichen.
Sie können einen ersten Aufruf an RtlUTF8ToUnicodeN- durchführen, um die erforderliche Ausgabepuffergröße abzurufen, und dann RtlUTF8ToUnicodeN erneut aufrufen, um die Unicode-Ausgabezeichenfolge abzurufen. Legen Sie im ersten Aufruf UnicodeStringDestination = NULL- und UnicodeStringMaxByteCount = 0 fest, und die Routine schreibt die erforderliche Puffergröße auf *UnicodeStringActualByteCount. Weisen Sie als Nächstes einen Puffer der erforderlichen Größe zu, und rufen Sie RtlUTF8ToUnicodeN ein zweites Mal auf, um die Unicode-Ausgabezeichenfolge abzurufen.
RtlUTF8ToUnicodeN- 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.
RtlUTF8ToUnicodeN 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 RtlUnicodeToUTF8N Routine konvertiert eine Unicode-Zeichenfolge in eine UTF-8-Zeichenfolge.
Sie können die RtlUTF8ToUnicodeN- und RtlUnicodeToUTF8N 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 7 |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Ntifs.h, Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |