RtlAnsiStringToUnicodeString-Funktion (wdm.h)

Artikel
02/27/2024

RtlAnsiStringToUnicodeString konvertiert die angegebene ANSI-Quellzeichenfolge in eine Unicode-Zeichenfolge.

Syntax

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Parameter

[in, out] DestinationString

Zeiger auf eine UNICODE_STRING-Struktur , die die konvertierte Unicode-Zeichenfolge enthält. Wenn AllocateDestinationStringAUF TRUE festgelegt ist, ordnet die Routine einen neuen Puffer zu, der die Zeichenfolgendaten enthält, und aktualisiert den Buffer-Member von DestinationString so, dass er auf den neuen Puffer verweist. Andernfalls verwendet die Routine den derzeit angegebenen Puffer, um die Zeichenfolge zu enthalten.

[in] SourceString

Zeiger auf die ANSI-Zeichenfolge, die in Unicode konvertiert werden soll.

[in] AllocateDestinationString

Gibt an, ob diese Routine den Pufferspeicher für die Zielzeichenfolge zuordnen soll. Wenn dies der Fall ist, muss der Aufrufer die Zuordnung des Puffers durch Aufrufen von RtlFreeUnicodeString aufheben.

Rückgabewert

Wenn die Konvertierung erfolgreich ist, gibt RtlAnsiStringToUnicodeString STATUS_SUCCESS zurück. Bei Einem Fehler ordnet die Routine keinen Arbeitsspeicher zu.

Hinweise

Die Übersetzung entspricht den aktuellen Gebietsschemainformationen des Systems.

Wenn der Aufrufer AllocateDestinationString auf TRUE festlegt, ersetzt die Routine den Buffer-Member von DestinationString durch einen Zeiger auf den zugeordneten Puffer. Der alte Wert kann auch dann überschrieben werden, wenn die Routine einen Fehler status Code zurückgibt.

Diese Routine wird nicht in einer Headerdatei deklariert. Sie können jedoch die folgende Deklaration in Ihren Quellcode kopieren:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Sie können die folgenden Routinen verwenden, um Einzelbyte- und Doppelbytezeichen in Unicode-Zeichen zu konvertieren:

Weitere Informationen zu diesen und anderen Zeichenfolgenverarbeitungsroutinen finden Sie unter Rtl-Routinen (Run-Time Library).

RtlAnsiCharToUnicodeCharChar weist Sicherheitsmängel auf. Erwägen Sie stattdessen die Verwendung der Routine RtlAnsiStringToUnicodeString .

Wenn *SourceCharacter beim Eintrag auf einen Ein-Byte-Puffer zeigt, der das erste Byte eines Zwei-Byte-Zeichencodes enthält, überschreibt RtlAnsiCharToUnicodeCharcharchar den Puffer, wenn versucht wird, das zweite Byte zu lesen.

Beim Systemstart bestimmt das Betriebssystem die Benutzersprache aus den Gebietsschemaeinstellungen und installiert die entsprechende ANSI-Codepage des Systems. RtlAnsiCharToUnicodeCharCharchar verwendet diese Codepage, um ein Einzelbyte- oder Doppelbytezeichen in das entsprechende Unicode-Zeichen zu konvertieren.

Wenn die ANSI-Codepage des Systems einen Einzelbytezeichensatz (d. h. den ANSI-Zeichensatz) definiert, beschleunigt RtlAnsiCharToUnicodeCharchar den Konvertierungsvorgang, indem ein ANSI-Zeichen im Bereich 0x00 auf 0x7f erweitert wird, um das entsprechende Unicode-Zeichen zu erzeugen. Die Routine konvertiert den ANSI-Wert 0x5c in das umgekehrte Schrägstrichzeichen ("\"), auch wenn die Einzelbyte-Codepage dieses Zeichen als Yen-Zeichen definiert.

Wenn *SourceCharacter bei der Eingabe auf einen ungültigen Zeichencode zeigt, gibt RtlAnsiCharToUnicodeCharCharchar den Unicode-Leerzeichencode zurück, 0x0020. Die folgende Liste enthält Beispiele für ungültige Zeichencodes:

Das erste Byte des Zeichencodes ist ein Wert, der nur als zweites Byte eines Zweibytezeichencodes gültig ist.
Das zweite Byte eines Zwei-Byte-Zeichencodes ist ein Wert, der nur als erstes Byte gültig ist.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL