RtlUnicodeStringInitEx-Funktion (ntstrsafe.h)

  • Artikel

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

Optional. Ein Zeiger auf eine UNICODE_STRING Struktur, die initialisiert werden soll. Der pszSrc-Zeiger wird in die UNICODE_STRING-Struktur des DestinationString-Parameters 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 dwFlags festgelegt ist.

[in, optional] pszSrc

Optional. Ein Zeiger auf eine NULL-beendete Zeichenfolgenkonstante. Dieser Zeichenfolgenzeiger wird in das Pufferelement der UNICODE_STRING Struktur kopiert, auf die der DestinationString-Parameter verweist. Dieser Zeichenfolgenzeiger kann NULL sein.

[in] dwFlags

Das folgende Flag wird 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 Abschneiden kopiert wurde und der resultierende Zielpuffer NULL-beendet ist.
STATUS_INVALID_PARAMETER
 Dieser Fehler status bedeutet, dass die Funktion einen ungültigen Eingabeparameter erhalten hat. Weitere Informationen finden Sie in der folgenden Liste.
 

RtlUnicodeStringInitEx gibt den STATUS_INVALID_PARAMETER Wert zurück, wenn einer 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.

Hinweise

Die RtlUnicodeStringInitEx-Funktion führt folgendes aus:

  • Legt das Length-Element der UNICODE_STRING-Struktur auf die Länge der Zeichenfolge in Bytes fest, auf die der pszSrc-Parameter verweist.
  • Legt das MaximumLength-Element der UNICODE_STRING-Struktur auf die Länge der Zeichenfolge in Bytes fest, auf die der pszSrc-Parameter auf plus 2 Bytes zeigt.
  • Legt das Buffer-Element der UNICODE_STRING-Struktur auf die Adresse fest, die der pszSrc-Parameter angibt.
Der DestinationString-Zeiger kann null sein, es sei denn, das flag STRSAFE_IGNORE_NULLS ist festgelegt.

Weitere Informationen zu den Sicheren Zeichenfolgenfunktionen finden Sie unter Verwenden sicherer Zeichenfolgenfunktionen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows XP mit Service Pack 1 (SP1).
Zielplattform Desktop
Kopfzeile ntstrsafe.h (einschließen von Ntstrsafe.h)
Bibliothek Ntstrsafe.lib
IRQL Alle, wenn Zeichenfolgen, die bearbeitet werden, immer im Arbeitsspeicher gespeichert sind, andernfalls PASSIVE_LEVEL

Weitere Informationen

RtlUnicodeStringInit

UNICODE_STRING