Freigeben über

RtlUnicodeStringCbCatNEx-Funktion (ntstrsafe.h)

  • Artikel

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

Syntax

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

Parameter

[in, out] DestinationString

Wahlfrei. 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 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 dwFlagsfestgelegt ist.

[in] SourceString

Wahlfrei. 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 Bytes im Zeichenfolgenpuffer der Struktur ist NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). SourceString- kann NULL-sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlagsfestgelegt ist.

[in] cbToAppend

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

[out, optional] RemainingString

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

[in] dwFlags

Mindestens ein Flag und optional ein Füllbyte. Die Kennzeichen sind 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 dem letzten Zeichen in der Zeichenfolge folgt.
STRSAFE_IGNORE_NULLS Wenn dieses Flag festgelegt ist, kann der Quell- oder Zielzeiger oder beides NULL-werden. RtlUnicodeStringCbCatNEx behandelt NULL- Quellpufferzeiger wie leere Zeichenfolgen (TEXT("")), die kopiert werden können. NULL- Zielpufferzeiger können keine nicht leeren Zeichenfolgen empfangen.
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 auszufüllen. Mit diesem Vorgang werden alle bereits vorhandenen Pufferinhalte überschrieben.
STRSAFE_NULL_ON_FAILURE Wenn dieses Flag festgelegt ist und die Funktion fehlschlägt, wird der Zielpuffer auf eine leere Zeichenfolge (TEXT("")) festgelegt. Mit diesem Vorgang werden alle bereits vorhandenen Pufferinhalte überschrieben.
STRSAFE_NO_TRUNCATION

Wenn dieses Kennzeichen festgelegt ist und die Funktion STATUS_BUFFER_OVERFLOWzurückgibt:

  • Wenn STRSAFE_FILL_ON_FAILURE auch angegeben wird, füllt STRSAFE_NO_TRUNCATION den Zielpuffer entsprechend aus.
  • Andernfalls wird der Zielpuffer nicht geä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 Byte festgelegt.

Rückgabewert

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

Rückgabecode Beschreibung
STATUS_SUCCESS Dieser Erfolgsstatus bedeutet, dass Quelldaten vorhanden waren und die Zeichenfolgen ohne Abschneiden verkettet wurden.
STATUS_BUFFER_OVERFLOW Dieser Warnstatus bedeutet, dass der Verkettungsvorgang aufgrund unzureichender Leerzeichen im Zielpuffer nicht abgeschlossen wurde. Wenn STRSAFE_NO_TRUNCATION festgelegt ist, finden Sie weitere Informationen im dwFlags-parameter.
STATUS_INVALID_PARAMETER Dieser Fehlerstatus bedeutet, dass die Funktion einen ungültigen Eingabeparameter empfangen hat. Weitere Informationen finden Sie in der folgenden Liste.

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

  • Der Inhalt einer UNICODE_STRING-Struktur ist ungültig.
  • Ein ungültiges Kennzeichen wird in dwFlags-angegeben.
  • Der Zielpuffer ist bereits voll.
  • Ein Pufferzeiger ist NULL- und das STRSAFE_IGNORE_NULLS Flag wird in dwFlags nicht angegeben.
  • Der Zielpufferzeiger ist NULL-, die Puffergröße ist jedoch nicht null.
  • Der Zielpufferzeiger ist NULL-, oder die Länge ist Null, aber eine Zeichenfolge mit nicht nuller Lä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.

Bemerkungen

Die RtlUnicodeStringCbCatNEx--Funktion verwendet die Größe des Zielpuffers, um sicherzustellen, dass der Verkettungsvorgang nicht über das Ende des Puffers schreibt. Standardmäßig die Funktion nicht die resultierende Zeichenfolge mit einem Nullzeichenwert (d. a. null) beenden. Als Option kann der Aufrufer das STRSAFE_FILL_BEHIND Flag und einen Füllbytewert von Null verwenden, um eine resultierende Zeichenfolge zu beenden, die nicht den gesamten Zielpuffer einnimmt.

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

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

Die SourceString und DestinationString Zeiger können nicht NULL- werden, es sei denn, das STRSAFE_IGNORE_NULLS Flag wird in dwFlagsfestgelegt. Wenn STRSAFE_IGNORE_NULLS festgelegt ist, kann ein oder beide Zeiger NULL-werden. Wenn der DestinationString Zeiger NULL-ist, muss der SourceString Zeiger NULL- sein, oder die UNICODE_STRING-Struktur muss eine leere Zeichenfolge angeben.

Weitere Informationen zu den funktionen für sichere Zeichenfolgen finden Sie unter Verwenden sicherer Zeichenfolgenfunktionen.

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Verfügbar ab Windows XP mit Service Pack 1 (SP1).
Zielplattform- Desktop
Header- ntstrsafe.h (include Ntstrsafe.h)
Library Ntstrsafe.lib
IRQL- Wenn Zeichenfolgen, die bearbeitet werden, immer im Arbeitsspeicher vorhanden sind, andernfalls PASSIVE_LEVEL

Siehe auch