Freigeben über

RtlStringCchCopyUnicodeStringEx-Funktion (ntstrsafe.h)

Die RtlStringCchCopyUnicodeStringEx--Funktion kopiert den Inhalt einer UNICODE_STRING Struktur in ein angegebenes Ziel.

Syntax

NTSTRSAFEDDI RtlStringCchCopyUnicodeStringEx(
  [out]           NTSTRSAFE_PWSTR  pszDest,
  [in]            size_t           cchDest,
  [in]            PCUNICODE_STRING SourceString,
  [out]           NTSTRSAFE_PWSTR  *ppszDestEnd,
  [out, optional] size_t           *pcchRemaining,
  [in]            DWORD            dwFlags
);

Parameter

[out] pszDest

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

[in] cchDest

Die Größe des Zielpuffers in Zeichen. Der Puffer muss groß genug für die Zeichenfolge und das endende Nullzeichen sein. Die maximale Anzahl von Zeichen im Puffer ist NTSTRSAFE_MAX_CCH.

[in] SourceString

Wahlfrei. Ein Zeiger auf eine UNICODE_STRING Struktur, die die zu kopierende Zeichenfolge enthält. Die maximale Anzahl von Zeichen in der Zeichenfolge ist NTSTRSAFE_UNICODE_STRING_MAX_CCH. Dieser Zeiger kann NULL-sein, aber nur, wenn STRSAFE_IGNORE_NULLS in dwFlagsfestgelegt ist.

[out] ppszDestEnd

Wahlfrei. 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-Zeichenfolgenbezeichner des Zielpuffers.

[out, optional] pcchRemaining

Wahlfrei. Wenn der Aufrufer einen null-NULL- Adresszeiger bereitstellt, lädt die Funktion die Adresse mit der Anzahl nicht verwendeter Zeichen, die sich im Puffer befinden, auf den pszDest verweist, einschließlich des endenden NULL-Zeichens.

[in] dwFlags

Mindestens ein Flag und optional ein Füllbyte. Die Kennzeichen sind wie folgt definiert:

Wert Bedeutung
STRSAFE_FILL_BEHIND_NULL Wenn dieses Flag festgelegt ist und die Funktion erfolgreich ausgeführt wird, wird das niedrige Byte von dwFlags verwendet, um den Teil des Zielpuffers auszufüllen, der auf das endende Nullzeichen folgt.
STRSAFE_IGNORE_NULLS Wenn dieses Flag festgelegt ist, kann entweder der Quell- oder Zielzeiger oder beides NULL-werden. RtlStringCchCopyUnicodeStringEx 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, und der Puffer wird null-beendet. 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 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

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

Rückgabecode Beschreibung
STATUS_SUCCESS Dieser Erfolg Status bedeutet, dass Quelldaten vorhanden waren, die Zeichenfolge ohne Abkürzung 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 empfangen hat. Weitere Informationen finden Sie in der folgenden Liste.

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

  • Der Inhalt der UNICODE_STRING-Struktur ist ungültig.
  • Ein ungültiges Kennzeichen wird in dwFlags-angegeben.
  • Der Wert in cchDest- 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-, die Puffergröße ist jedoch nicht null.
  • Der Zielpufferzeiger ist NULL- oder seine Länge 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 RtlStringCchCopyUnicodeStringEx--Funktion verwendet die Größe des Zielpuffers (die der cchDest Parameter angibt), um sicherzustellen, dass der Kopiervorgang nicht über das Ende des Puffers schreibt.

RtlStringCchCopyUnicodeStringEx der Funktionalität der RtlStringCchCopyUnicodeString Funktion hinzu, indem ein Zeiger an 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 zusätzliche Steuerelemente an die Funktion übergeben.

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

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

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

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Verfügbar in Windows XP mit Service Pack 1 (SP1) und höheren Versionen von Windows.
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