RtlUnicodeStringCbCatN-Funktion (ntstrsafe.h)

  • Artikel

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

Syntax

NTSTRSAFEDDI RtlUnicodeStringCbCatN(
  [in, out] PUNICODE_STRING  DestinationString,
  [in]      PCUNICODE_STRING SourceString,
  [in]      size_t           cbToAppend
);

Parameter

[in, out] DestinationString

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

[in] SourceString

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

[in] cbToAppend

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

Rückgabewert

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

Rückgabecode Beschreibung
STATUS_SUCCESS
 Dieser Erfolg status bedeutet, dass Quelldaten vorhanden waren, die Zeichenfolgen ohne Abschneiden verkettet wurden und der resultierende Zielpuffer NULL-beendet ist.
STATUS_BUFFER_OVERFLOW
 Diese Warnung status bedeutet, dass der Verkettungsvorgang aufgrund des unzureichenden Pufferspeichers nicht abgeschlossen wurde. Der Zielpuffer enthält eine abgeschnittene, NULL-beendete Version des beabsichtigten Ergebnisses.
STATUS_INVALID_PARAMETER
 Dieser Fehler status bedeutet, dass die Funktion einen ungültigen Eingabeparameter erhalten hat. Weitere Informationen finden Sie in der folgenden Liste.
 

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

  • Der Inhalt der UNICODE_STRING-Struktur ist ungültig.
  • Der Zielpuffer ist bereits voll.
  • Ein Pufferzeiger ist NULL.
  • Die Länge des Zielpuffers ist 0, aber eine Quellzeichenfolge mit ungleicher 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.

Hinweise

Die RtlUnicodeStringCbCatN-Funktion verwendet die Größe des Zielpuffers, um sicherzustellen, dass der Verkettungsvorgang nicht über das Ende des Puffers schreibt. Die Funktion beendet die resultierende Zeichenfolge nicht mit einem NULL-Zeichenwert (also mit null).

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

Die SourceString- und DestinationString-Zeiger dürfen nicht NULL sein. Wenn Sie NULL-Zeigerwerte verarbeiten müssen, verwenden Sie die RtlUnicodeStringCbCatNEx-Funktion.

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows XP mit Service Pack 1 (SP1) und höheren Versionen von Windows.
Zielplattform Desktop
Kopfzeile ntstrsafe.h (einschließen von Ntstrsafe.h)
Bibliothek Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Weitere Informationen

RtlUnicodeStringCbCatNEx

RtlUnicodeStringCchCatN

UNICODE_STRING