RtlUnicodeStringCopyStringStringEx-Funktion (ntstrsafe.h)

Die RtlUnicodeStringCopyStringStringEx-Funktion kopiert eine Zeichenfolge in eine UNICODE_STRING-Struktur .

Syntax

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

Parameter

[out] DestinationString

Optional. Ein Zeiger auf eine UNICODE_STRING-Struktur , die die kopierte Zeichenfolge empfängt. Die Zeichenfolge, auf die der pszSrc-Parameter zeigt (mit Ausnahme des beendenden NULL), wird in den Puffer kopiert, auf den die UNICODE_STRING Struktur des DestinationString-Parameters verweist. Die maximale Anzahl von Bytes in der Zeichenfolge ist NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). DestinationString kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] pszSrc

Optional. Ein Zeiger auf eine NULL-endende Zeichenfolge, die in den Puffer kopiert wird, auf den die UNICODE_STRING Struktur des DestinationString-Parameters verweist. pszSrc kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[out, optional] RemainingString

Optional. Wenn der Aufrufer einen Zeiger ungleich NULL auf eine UNICODE_STRING-Struktur bereitstellt, legt die Funktion den Buffer-Member dieser Struktur am Ende der verketteten Zeichenfolge fest, legt den Length-Member der Struktur auf 0 (null) und das MaximumLength-Element der Struktur auf die Anzahl der Bytes fest, die im Zielpuffer verbleiben. RemainingString kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] dwFlags

Mindestens ein Flag und optional ein Füllbyte. Die Flags werden wie folgt definiert:

Rückgabewert

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

RtlUnicodeStringCopyStringStringEx gibt den STATUS_INVALID_PARAMETER Wert zurück, wenn einer der folgenden Aktionen auftritt:

• Der Inhalt einer UNICODE_STRING-Struktur ist ungültig.
• In dwFlags wird ein ungültiges Flag angegeben.
• Der Zielpuffer ist bereits voll.
• Ein Pufferzeiger ist NULL , und das flag STRSAFE_IGNORE_NULLS wird in dwFlags nicht angegeben.
• Der Zielpufferzeiger ist NULL, aber die Puffergröße ist nicht null.
• Der Zielpufferzeiger ist NULL, oder seine Länge ist null, aber eine Quellzeichenfolge ungleich null ist vorhanden.

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

Hinweise

Die RtlUnicodeStringCopyStringEx-Funktion verwendet die Größe des Zielpuffers, um sicherzustellen, dass der Verkettungsvorgang nicht über das Ende des Puffers schreibt. Standardmäßig beendet die Funktion die resultierende Zeichenfolge nicht mit einem NULL-Zeichenwert (also mit null). Als Option kann der Aufrufer das flag STRSAFE_FILL_BEHIND und einen Füllbytewert von null bis null beenden eine resultierende Zeichenfolge verwenden, die nicht den gesamten Zielpuffer belegt.

RtlUnicodeStringCopyStringEx fügt der Funktionalität der RtlUnicodeStringCopyString-Funktion hinzu, indem eine UNICODE_STRING-Struktur zurückgegeben wird, die das Ende der Zielzeichenfolge und die Anzahl der Bytes identifiziert, die in dieser Zeichenfolge nicht verwendet werden. Sie können Flags für zusätzliche Steuerung an RtlUnicodeStringCopyStringEx übergeben.

Wenn sich die Quell- und Zielzeichenfolgen überschneiden, ist das Verhalten der Funktion nicht definiert.

Die Zeiger pszSrc und DestinationString können nicht NULL sein, es sei denn, das flag STRSAFE_IGNORE_NULLS ist in dwFlags festgelegt. Wenn STRSAFE_IGNORE_NULLS festgelegt ist, können einer oder beide dieser Zeiger NULL sein. Wenn der DestinationString-ZeigerNULL ist, muss der pszSrc-ZeigerNULL oder auf eine leere Zeichenfolge zeigen.

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

Anforderungen

Weitere Informationen

• RtlUnicodeStringCopyString
• UNICODE_STRING