RtlStringCbCopyUnicodeStringEx-Funktion (ntstrsafe.h)

  • Artikel

Die RtlStringCbCopyUnicodeStringEx-Funktion kopiert den Inhalt einer UNICODE_STRING-Struktur an ein angegebenes Ziel.

Syntax

NTSTRSAFEDDI RtlStringCbCopyUnicodeStringEx(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cbDest,
  [in]            PCUNICODE_STRING SourceString,
  [out]           NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcbRemaining,
  [in]            DWORD            dwFlags
);

Parameter

[out] pszDest

Optional. Ein Zeiger auf einen Puffer, der die kopierte Zeichenfolge empfängt. Die Zeichenfolge, auf die die UNICODE_STRING Struktur des SourceString-Parameters verweist, wird unter pszDest in den Puffer kopiert und mit einem NULL-Zeichen beendet. Dieser Zeiger kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[in] cbDest

Die Größe des Zielpuffers in Bytes. Der Puffer muss groß genug für die Zeichenfolge und das beendende NULL-Zeichen sein. Die maximale Anzahl von Bytes im Puffer ist NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

[in] SourceString

Optional. Ein Zeiger auf eine UNICODE_STRING Struktur, die die zu kopierende Zeichenfolge enthält. Die maximale Anzahl von Bytes in der Zeichenfolge ist NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR). Dieser Zeiger kann NULL sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlags festgelegt ist.

[out] ppszDestEnd

Optional. Wenn der Aufrufer einen Nicht-NULL-Adresszeiger bereitstellt, lädt die Funktion diese Adresse nach Abschluss des Kopiervorgangs mit einem Zeiger auf den resultierenden NULL-Zeichenfolgenabschluss des Zielpuffers.

[out, optional] pcbRemaining

Optional. Wenn der Aufrufer einen Adresszeiger ohne NULL bereitstellt, lädt die Funktion die Adresse mit der Anzahl der nicht verwendeten Bytes, die sich im Puffer befinden, auf den pszDest verweist, einschließlich Bytes, die für das beendende NULL-Zeichen verwendet werden.

[in] dwFlags

Ein oder mehrere Flags und optional ein Füllbyte. Die Flags werden wie folgt definiert:

Wert Bedeutung
STRSAFE_FILL_BEHIND_NULL 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 beendenden NULL-Zeichen folgt.
STRSAFE_IGNORE_NULLS Wenn dieses Flag festgelegt ist, kann entweder der Quell- oder Zielzeiger oder beides NULL sein. RtlStringCbCopyUnicodeStringEx 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, und der Puffer ist NULL-beendet. 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 Inhalt des Zielpuffers auf eine leere Zeichenfolge festgelegt, auch wenn STRSAFE_NULL_ON_FAILURE nicht festgelegt ist. STRSAFE_FILL_BEHIND_NULL wird ignoriert.

Rückgabewert

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

Rückgabecode Beschreibung
STATUS_SUCCESS Dieser Erfolg status bedeutet, dass Quelldaten vorhanden waren, die Zeichenfolge ohne Abschneiden kopiert wurde und der resultierende Zielpuffer NULL-beendet ist.
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 in der folgenden Liste.

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

  • Der Inhalt der UNICODE_STRING-Struktur ist ungültig.
  • In dwFlags wird ein ungültiges Flag angegeben.
  • Der Wert in cbDest ist größer als die maximale Puffergröße.
  • Der Zielpuffer (auf den pszDest verweist) ist bereits voll.
  • Ein Pufferzeiger ist NULL , und das STRSAFE_IGNORE_NULLS-Flag wird 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 mit ungleicher Länge ist vorhanden.

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

Hinweise

Die Funktion RtlStringCbCopyUnicodeStringEx verwendet die Größe des Zielpuffers (die der cbDest-Parameter angibt), um sicherzustellen, dass der Kopiervorgang nicht über das Ende des Puffers schreibt.

RtlStringCbCopyUnicodeStringEx fügt der Funktionalität der Funktion RtlStringCbCopyUnicodeString hinzu, indem ein Zeiger auf das Ende der Zielzeichenfolge und die Anzahl der Bytes zurückgegeben wird, die in dieser Zeichenfolge nicht verwendet werden. Sie können Flags für ein zusätzliches Steuerelement an die Funktion übergeben.

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

Die Zeiger *SourceString *und pszDest können NICHT NULL sein, es sei denn, das flag STRSAFE_IGNORE_NULLS ist in dwFlags festgelegt. Wenn STRSAFE_IGNORE_NULLS festgelegt ist, kann einer oder beide dieser Zeiger NULL sein. Wenn der pszDest-ZeigerNULL ist, muss der *SourceString *-Zeiger NULL sein, oder die UNICODE_STRING-Struktur muss eine leere Zeichenfolge beschreiben.

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 Alle, wenn Zeichenfolgen, die bearbeitet werden, immer im Arbeitsspeicher gespeichert sind, andernfalls PASSIVE_LEVEL

Weitere Informationen