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 zu initialisierende UNICODE_STRING-Struktur. Der pszSrc-Zeiger wird in die UNICODE_STRING-Struktur des DestinationString-Parameters kopiert. Die maximale Anzahl von Zeichen in der Zeichenfolge, auf die pszSrc zeigt, 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-endende Zeichenfolgenkonstante. Dieser Zeichenfolgenzeiger wird in den Buffer-Member der UNICODE_STRING-Struktur kopiert, auf die der DestinationString-Parameter verweist. Dieser Zeichenfolgenzeiger kann NULL sein.

[in] dwFlags

Das folgende Flag 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 Abschneiden 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 einer der folgenden Aktionen auftritt:

  • Die Länge der Zeichenfolge, auf die der pszSrc-Parameter zeigt, ist größer als NTSTRSAFE_UNICODE_STRING_MAX_CCH Zeichen.
  • Der DestinationString-Zeiger ist NULL, aber der zeiger pszSrc 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 den Length-Member der UNICODE_STRING-Struktur auf die Länge der Zeichenfolge in Bytes fest, auf die der pszSrc-Parameter verweist.
  • Legt den MaximumLength-Member der UNICODE_STRING-Struktur auf die Länge der Zeichenfolge in Bytes fest, auf die der pszSrc-Parameter plus 2 Bytes zeigt.
  • Legt den Buffer-Member der UNICODE_STRING-Struktur auf die Adresse fest, die der pszSrc-Parameter angibt.
Der DestinationString-Zeiger kann nicht 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 PASSIVE_LEVEL

Weitere Informationen

RtlUnicodeStringInit

UNICODE_STRING