RtlUnicodeStringCbCatStringNEx-Funktion (ntstrsafe.h)

Die RtlUnicodeStringCbCatStringNEx-Funktion verkettet zwei Zeichenfolgen, wenn die Zielzeichenfolge in einer UNICODE_STRING-Struktur enthalten ist, während die Größe der angefügten Zeichenfolge begrenzt wird.

Syntax

NTSTRSAFEDDI RtlUnicodeStringCbCatStringNEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            NTSTRSAFE_PCWSTR pszSrc,
  [in]            size_t           cbToAppend,
  [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 Zielzeichenfolge 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 (mit Ausnahme des beendenden NULL) wird am Ende der Zielzeichenfolge hinzugefügt. Die maximale Anzahl von Bytes im Zeichenfolgenpuffer der Struktur ist NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). DestinationString kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] pszSrc

Ein vom Aufrufer bereitgestellter Zeiger auf eine NULL-beendete Zeichenfolge. Diese Zeichenfolge wird mit dem Ende der Zeichenfolge verkettet, die in der UNICODE_STRING Struktur enthalten ist, auf die DestinationString verweist. pszSrc kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] cbToAppend

Die maximale Anzahl von Bytes, die an die Zeichenfolge angefügt werden sollen, die der DestinationString-Parameter beschreibt.

[out, optional] RemainingString

Optional. Wenn der Aufrufer einen Nicht-NULL-Zeiger auf eine UNICODE_STRING Struktur bereitstellt, legt die Funktion den Buffer-Member dieser Struktur auf das Ende der verketteten Zeichenfolge fest, legt den Length-Member der Struktur auf 0 fest und legt 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

Ein oder mehrere Flags und optional ein Füllbyte. Die Flags werden wie folgt definiert:

Rückgabewert

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

RtlUnicodeStringCbCatStringNEx 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 STRSAFE_IGNORE_NULLS-Flag wird nicht angegeben.
• Der Zielpufferzeiger ist NULL, aber die Puffergröße ist nicht 0.
• Der Zielpufferzeiger ist NULL, oder seine Länge ist 0, aber eine Quellzeichenfolge ohne Zerolänge ist vorhanden.
• Der Wert des cbToAppend-Parameters ist größer als NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).

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

Hinweise

Die **RtlUnicodeStringCbCatStringNEx **-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-terminate einer resultierenden Zeichenfolge verwenden, die nicht den gesamten Zielpuffer belegt.

RtlUnicodeStringCbCatStringNEx fügt die Funktionalität der RtlUnicodeStringCbCatStringN-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 Steuerelemente an RtlUnicodeStringCbCatStringNEx übergeben.

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

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

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

Anforderungen

Weitere Informationen

• RtlUnicodeStringCbCatStringN
• RtlUnicodeStringCchCatStringNEx
• UNICODE_STRING