RtlUnicodeStringCatStringEx-Funktion (ntstrsafe.h)

  • Artikel

Die RtlUnicodeStringCatStringEx-Funktion verkettet zwei Zeichenfolgen, wenn die Zielzeichenfolge in einer UNICODE_STRING-Struktur enthalten ist.

Syntax

NTSTRSAFEDDI RtlUnicodeStringCatStringEx(
  [in, out]       PUNICODE_STRING  DestinationString,
  [in]            NTSTRSAFE_PCWSTR pszSrc,
  [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 der endenden 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

Optional. Ein vom Aufrufer bereitgestellter Zeiger auf eine Quellzeichenfolge mit NULL-Beendigung. Diese Zeichenfolge wird mit dem Ende der Zeichenfolge verkettet, die in der UNICODE_STRING Struktur enthalten ist, die DestinationString angibt. 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. Dieser Zeiger 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:

Wert Bedeutung
STRSAFE_FILL_BEHIND Wenn dieses Flag festgelegt ist und die Funktion erfolgreich ist, wird das niedrige Byte von dwFlags verwendet, um den Teil des Zielpuffers auszufüllen, der auf das letzte Zeichen in der Zeichenfolge folgt.
STRSAFE_IGNORE_NULLS Wenn dieses Flag festgelegt ist und die Funktion erfolgreich ist, wird das niedrige Byte von dwFlags verwendet, um den Teil des Zielpuffers auszufüllen, der auf das letzte Zeichen in der Zeichenfolge folgt.
STRSAFE_FILL_ON_FAILURE Wenn dieses Flag festgelegt ist und die Funktion fehlschlägt, wird das niedrige Byte von dwFlags verwendet, um den gesamten Zielpuffer aufzufüllen. Dieser Vorgang überschreibt alle bereits vorhandenen Pufferinhalte.
STRSAFE_NULL_ON_FAILURE Wenn dieses Flag festgelegt ist und die Funktion fehlschlägt, wird der Zielpuffer auf eine leere Zeichenfolge (TEXT("")) festgelegt. Dieser Vorgang überschreibt alle bereits vorhandenen Pufferinhalte.
STRSAFE_NO_TRUNCATION

Wenn dieses Flag festgelegt ist und die Funktion STATUS_BUFFER_OVERFLOW zurückgibt:

  • Wenn auch STRSAFE_FILL_ON_FAILURE angegeben ist, füllt STRSAFE_NO_TRUNCATION den Zielpuffer entsprechend aus.
  • Andernfalls wird der Zielpuffer unverändert.
STRSAFE_ZERO_LENGTH_ON_FAILURE Wenn dieses Flag festgelegt ist und die Funktion STATUS_BUFFER_OVERFLOW zurückgibt, wird die Länge der Zielzeichenfolge auf null Bytes festgelegt.

Rückgabewert

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

Rückgabecode Beschreibung
STATUS_SUCCESS Dieser Erfolg status bedeutet, dass Quelldaten vorhanden waren und die Zeichenfolgen ohne Abschneiden verkettet wurden.
STATUS_BUFFER_OVERFLOW Diese Warnung status bedeutet, dass der Kopiervorgang aufgrund von unzureichendem Speicherplatz im Zielpuffer nicht abgeschlossen wurde. Wenn STRSAFE_NO_TRUNCATION festgelegt ist, finden Sie weitere Informationen im dwFlags-Parameter .
STATUS_INVALID_PARAMETER Dieser Fehler status bedeutet, dass die Funktion einen ungültigen Eingabeparameter empfangen hat. Weitere Informationen finden Sie in der folgenden Liste.

RtlUnicodeStringCatStringEx 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 RtlUnicodeStringCatStringEx-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.

RtlUnicodeStringCatStringEx fügt der Funktionalität der RtlUnicodeStringCatString-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 an RtlUnicodeStringCatStringExoder ein zusätzliches Steuerelement ü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-Zeiger entweder NULL oder auf eine leere Zeichenfolge zeigen.

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