RtlUnicodeStringVPrintfEx-Funktion (ntstrsafe.h)

Artikel
02/29/2024

Die RtlUnicodeStringVPrintfEx-Funktion erstellt eine Textzeichenfolge mit Formatierungen, die auf den angegebenen 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

Optional. Ein Zeiger auf eine UNICODE_STRING Struktur, die eine formatierte Zeichenfolge empfängt. RtlUnicodeStringVPrintfEx erstellt diese Zeichenfolge aus der Formatierungszeichenfolge, die pszFormat bereitstellt, 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 dwFlags festgelegt ist.

[out, optional] RemainingString

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

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 zu fü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 sein. 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 zu fü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, wird der Inhalt 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 Bytes festgelegt.

[in] pszFormat

Ein Zeiger auf eine nicht beendete Textzeichenfolge, die Formatierungsdirektiven im Printf-Format enthält. Dieser Zeiger kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] argList

Eine va_list typisierte Argumentliste. Argumente in dieser Argumentliste werden von der using-Formatierungszeichenfolge interpretiert, die pszFormat bereitstellt.

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 des unzureichenden Speicherplatzes 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 erhalten 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.
In dwFlags wird ein ungültiges Flag 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, 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.

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

Hinweise

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

RtlUnicodeStringVPrintfEx fügt die Funktionalität der RtlUnicodeStringVPrintf-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 RtlUnicodeStringVPrintfEx übergeben.

Wenn sich die Formatzeichenfolge und die Zielzeichenfolge überschneiden, ist das Verhalten der Funktion undefiniert.

Die Zeiger pszFormat und DestinationString können nur 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 pszFormat-ZeigerNULL sein oder auf eine leere Zeichenfolge zeigen.

Weitere Informationen zu va_list typisierten Argumentlisten finden Sie in der Microsoft Windows SDK-Dokumentation.

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