RtlUnicodeStringInitEx-Funktion (ntstrsafe.h)

Artikel
02/07/2025

Die RtlUnicodeStringInitEx--Funktion initialisiert eine UNICODE_STRING Struktur.

Syntax

NTSTRSAFEDDI RtlUnicodeStringInitEx(
  [out]          PUNICODE_STRING  DestinationString,
  [in, optional] NTSTRSAFE_PCWSTR pszSrc,
  [in]           DWORD            dwFlags
);

Parameter

[out] DestinationString

Wahlfrei. Ein Zeiger auf eine UNICODE_STRING Struktur, die initialisiert werden soll. Der pszSrc Zeiger wird in die UNICODE_STRING Struktur des Parameters DestinationString kopiert. Die maximale Anzahl von Zeichen in der Zeichenfolge, auf die pszSrc verweist, ist NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString- kann NULL-sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlagsfestgelegt ist.

[in, optional] pszSrc

Wahlfrei. Ein Zeiger auf eine null-beendete Zeichenfolgenkonstante. Dieser Zeichenfolgenzeiger wird in das Buffer Member der UNICODE_STRING Struktur kopiert, auf das der DestinationString-Parameter verweist. Dieser Zeichenfolgenzeiger kann NULL-werden.

[in] dwFlags

Das folgende Kennzeichen ist definiert:

STRSAFE_IGNORE_NULLS

Wenn dieses Flag festgelegt ist, kann der Quellzeiger NULL-sein. RtlUnicodeStringInitEx behandelt NULL Quellpufferzeiger wie leere Zeichenfolgen (TEXT("")), die kopiert werden können.

Rückgabewert

RtlUnicodeStringInitEx gibt einen der folgenden NTSTATUS-Werte zurück.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Dieser Erfolg Status bedeutet, dass Quelldaten vorhanden waren, die Zeichenfolge ohne Abkürzung kopiert wurde und der resultierende Zielpuffer null beendet ist.
STATUS_INVALID_PARAMETER	Dieser Fehler Status bedeutet, dass die Funktion einen ungültigen Eingabeparameter empfangen hat. Weitere Informationen finden Sie in der folgenden Liste.

RtlUnicodeStringInitEx gibt den STATUS_INVALID_PARAMETER Wert zurück, wenn eine der folgenden Aktionen auftritt:

Die Länge der Zeichenfolge, auf die der pszSrc Parameter verweist, ist größer als NTSTRSAFE_UNICODE_STRING_MAX_CCH Zeichen.
Der DestinationString Zeiger ist NULL-, aber der pszSrc Zeiger ist nicht NULL-.

Informationen zum Testen von NTSTATUS-Werten finden Sie unter Verwenden von NTSTATUS-Werten.

Bemerkungen

Die funktion RtlUnicodeStringInitEx führt folgende Aktionen aus:

Legt den Length Member der UNICODE_STRING Struktur auf die Länge in Byte der Zeichenfolge fest, auf die der pszSrc Parameter verweist.
Legt den MaximumLength Member der UNICODE_STRING Struktur auf die Länge der Zeichenfolge in Bytes fest, die der pszSrc Parameter auf plus 2 Byte verweist.
Legt den Buffer Member der UNICODE_STRING Struktur auf die Adresse fest, die der pszSrc Parameter angibt.

Der DestinationString Zeiger kann nur dann NULL- werden, wenn das STRSAFE_IGNORE_NULLS Flag festgelegt ist.

Weitere Informationen zu den sicheren Zeichenfolgenfunktionen finden Sie unter Verwenden von Funktionen für sichere Zeichenfolgen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar ab Windows XP mit Service Pack 1 (SP1).
Zielplattform-	Desktop
Header-	ntstrsafe.h (include Ntstrsafe.h)
Library	Ntstrsafe.lib
IRQL-	Wenn Zeichenfolgen, die bearbeitet werden, immer im Arbeitsspeicher vorhanden sind, andernfalls PASSIVE_LEVEL

Siehe auch

RtlUnicodeStringInit

UNICODE_STRING

Freigeben über