RtlUnicodeStringCchCatNEx-Funktion (ntstrsafe.h)

Die RtlUnicodeStringCchCatNEx-Funktion verkettet zwei Zeichenfolgen, die in UNICODE_STRING Strukturen enthalten sind, während die Größe der kopierten Zeichenfolge begrenzt wird.

Syntax

NTSTRSAFEDDI RtlUnicodeStringCchCatNEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            PCUNICODE_STRING SourceString,
  [in]            size_t           cchToAppend,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags
);

Parameter

[in, out] DestinationString

Optional. Ein Zeiger auf eine UNICODE_STRING-Struktur . Diese Struktur enthält einen Puffer, der bei der Eingabe eine Zeichenfolge enthält, mit der die Quellzeichenfolge verkettet wird. Bei der Ausgabe ist dieser Puffer der Zielpuffer, der die gesamte resultierende Zeichenfolge enthält. Die Quellzeichenfolge wird am Ende der Zielzeichenfolge hinzugefügt. Die maximale Anzahl von Zeichen im Zeichenfolgenpuffer der Struktur ist NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] SourceString

Optional. Ein Zeiger auf eine UNICODE_STRING-Struktur . Diese Struktur enthält einen Puffer, der die Quellzeichenfolge enthält. Diese Zeichenfolge wird am Ende der Zielzeichenfolge hinzugefügt. Die maximale Anzahl von Zeichen im Zeichenfolgenpuffer der Struktur ist NTSTRSAFE_UNICODE_STRING_MAX_CCH. SourceString kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] cchToAppend

Die maximale Anzahl von Zeichen, die an die Zeichenfolge angefügt werden sollen, die vom DestinationString-Parameter beschrieben wird.

[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

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

RtlUnicodeStringCchCatNEx gibt den STATUS_INVALID_PARAMETER Wert zurück, wenn:

• 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.
• Der Wert des cchToAppend-Parameters ist größer als NTSTRSAFE_UNICODE_STRING_MAX_CCH.

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

Hinweise

Die RtlUnicodeStringCchCatNEx-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.

RtlUnicodeStringCchCatNEx fügt der Funktionalität der RtlUnicodeStringCchCatN-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 RtlUnicodeStringCchCatNEx übergeben.

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

Die Zeiger SourceString 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, kann einer oder beide NULL sein. Wenn der DestinationString-ZeigerNULL ist, muss der SourceString-ZeigerNULL sein, oder die UNICODE_STRING-Struktur muss eine leere Zeichenfolge angeben.

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

Anforderungen

Weitere Informationen

• RtlUnicodeStringCbCatNEx
• RtlUnicodeStringCchCatN
• UNICODE_STRING