RtlStringCbCopyUnicodeString-Funktion (ntstrsafe.h)

  • Artikel

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

Syntax

NTSTRSAFEDDI RtlStringCbCopyUnicodeString(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cbDest,
  [in]  PCUNICODE_STRING SourceString
);

Parameter

[out] pszDest

Ein Zeiger auf einen Puffer, der die kopierte Zeichenfolge empfängt. Die Zeichenfolge, auf die die UNICODE_STRING Struktur des SourceString-Parameters verweist, wird in den Puffer bei pszDest kopiert und mit einem NULL-Zeichen beendet.

[in] cbDest

Die Größe des Zielpuffers in Bytes, auf den pszDest zeigt. Der Puffer muss groß genug sein, um die Zeichenfolge und das abschließende NULL-Zeichen zu enthalten. Die maximale Anzahl von Bytes im Puffer ist NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof (WCHAR).

[in] SourceString

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

Rückgabewert

RtlStringCbCopyUnicodeString 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 Pufferspeichers nicht abgeschlossen wurde. Der Zielpuffer enthält eine abgeschnittene, mit NULL beendete Version des beabsichtigten Ergebnisses.
STATUS_INVALID_PARAMETER
 Dieser Fehler status bedeutet, dass die Funktion einen ungültigen Eingabeparameter empfangen hat. Weitere Informationen finden Sie in der folgenden Liste.
 

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

  • Der Inhalt der UNICODE_STRING-Struktur ist ungültig.
  • 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.
  • Die Länge des Zielpuffers ist null, aber eine Quellzeichenfolge ungleich null ist vorhanden.
Informationen zum Testen von NTSTATUS-Werten finden Sie unter Verwenden von NTSTATUS-Werten.

Hinweise

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

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

Die Zeiger SourceString und pszDest können nicht NULL sein. Wenn Sie NULL-Zeigerwerte verarbeiten müssen, verwenden Sie die RtlStringCbCopyUnicodeStringEx-Funktion.

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 PASSIVE_LEVEL

Weitere Informationen

RtlStringCbCopyUnicodeStringEx

RtlStringCchCopyUnicodeString

UNICODE_STRING