RtlUnicodeStringVPrintfEx-Funktion (ntstrsafe.h)

Artikel
02/07/2025

Die RtlUnicodeStringVPrintfEx--Funktion erstellt eine Textzeichenfolge mit Formatierungen, die auf bereitgestellten Formatierungsinformationen basieren, und speichert die Zeichenfolge in einer UNICODE_STRING Struktur.

Syntax

NTSTRSAFEDDI RtlUnicodeStringVPrintfEx(
  [out]           PUNICODE_STRING  DestinationString,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags,
  [in]            NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

Parameter

[out] DestinationString

Wahlfrei. Ein Zeiger auf eine UNICODE_STRING Struktur, die eine formatierte Zeichenfolge empfängt. RtlUnicodeStringVPrintfEx erstellt diese Zeichenfolge aus der Formatierungszeichenfolge, die pszFormat liefert, und der Argumentliste der Funktion. Die maximale Anzahl von Zeichen in der Zeichenfolge ist NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString- kann NULL-sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlagsfestgelegt ist.

[out, optional] RemainingString

Wahlfrei. Wenn der Aufrufer einen Nicht-NULL- Zeiger auf eine UNICODE_STRING-Struktur bereitstellt, RtlUnicodeStringVPrintfE- legt den Buffer Member dieser Struktur auf das Ende der formatierten Zeichenfolge fest, legt den Length Member der Struktur auf Null fest und legt das MaximumLength-Element 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:

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. RtlUnicodeStringVPrintfEx 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 Flag festgelegt ist und die Funktion STATUS_BUFFER_OVERFLOW zurückgibt, werden die Inhalte des Zielpuffers 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.

[in] pszFormat

Ein Zeiger auf eine mit Null beendete Textzeichenfolge, die printf--styled-formatierungsdirektiven enthält. Dieser Zeiger kann NULL-sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlagsfestgelegt ist.

[in] argList

Eine va_list-typed argument list. Argumente in dieser Argumentliste werden mithilfe der Formatierungszeichenfolge interpretiert, die pszFormat liefert.

Rückgabewert

RtlUnicodeStringVPrintfEx 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 unzureichendem Speicherplatz im Zielpuffer nicht abgeschlossen wurde. Wenn STRSAFE_NO_TRUNCATION in dwFlags-festgelegt ist, wird der Zielpuffer nicht geändert. Wenn das Flag nicht festgelegt ist, enthält der Zielpuffer eine abgeschnittene Version der kopierten Zeichenfolge.
STATUS_INVALID_PARAMETER	Dieser Fehler Status bedeutet, dass die Funktion einen ungültigen Eingabeparameter empfangen hat. Weitere Informationen finden Sie im folgenden Absatz.

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

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

Bemerkungen

Die RtlUnicodeStringVPrintfEx--Funktion verwendet die Größe des Zielpuffers, um sicherzustellen, dass der Zeichenfolgenformatierungsvorgang 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.

RtlUnicodeStringVPrintfEx der Funktionalität der RtlUnicodeStringVPrintf-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 RtlUnicodeStringVPrintfEx- für zusätzliche Steuerung übergeben.

Wenn sich die Formatzeichenfolge und die Zielzeichenfolge überlappen, ist das Verhalten der Funktion nicht definiert.

Die pszFormat 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 pszFormat- Zeiger NULL- oder auf eine leere Zeichenfolge zeigen.

Weitere Informationen zu va_list-typed-argument lists finden Sie in der Microsoft Windows SDK-Dokumentation.

Weitere Informationen zu den sicheren Zeichenfolgenfunktionen finden Sie unter Verwenden von Funktionen für sichere Zeichenfolgen.

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