StringCchCopyExW-Funktion (strsafe.h)

Kopiert eine Zeichenfolge in eine andere. Die Größe des Zielpuffers wird für die Funktion bereitgestellt, um sicherzustellen, dass sie nicht über das Ende des Puffers schreibt.

StringCchCopyEx fügt der Funktionalität von StringCchCopy hinzu, indem ein Zeiger auf das Ende der Zielzeichenfolge sowie die Anzahl von Zeichen zurückgegeben wird, die in dieser Zeichenfolge nicht verwendet werden. An diese Funktion können auch Flags zur zusätzlichen Steuerung übergeben werden.

StringCchCopyEx ist ein Ersatz für die folgenden Funktionen:

• strcpy, wcscpy, _tcscpy
• lstrcpy
• Strcpy

Syntax

STRSAFEAPI StringCchCopyExW(
  [out]           STRSAFE_LPWSTR  pszDest,
  [in]            size_t          cchDest,
  [in]            STRSAFE_LPCWSTR pszSrc,
  [out, optional] STRSAFE_LPWSTR  *ppszDestEnd,
  [out, optional] size_t          *pcchRemaining,
  [in]            DWORD           dwFlags
);

Parameter

[out] pszDest

Typ: LPTSTR

Der Zielpuffer, der die kopierte Zeichenfolge empfängt.

[in] cchDest

Typ: size_t

Die Größe des Zielpuffers in Zeichen. Dieser Wert muss der Länge von pszSrc plus 1 entsprechen, um die kopierte Quellzeichenfolge und das abschließende NULL-Zeichen zu berücksichtigen. Die maximale Anzahl zulässiger Zeichen ist STRSAFE_MAX_CCH.

[in] pszSrc

Typ: LPCTSTR

Die Quellzeichenfolge. Diese Zeichenfolge muss NULL-endend sein.

[out, optional] ppszDestEnd

Typ: LPTSTR*

Die Adresse eines Zeigers auf das Ende von pszDest. Wenn ppszDestEnd ungleich NULL ist und alle Daten in den Zielpuffer kopiert werden, zeigt dies auf das endende NULL-Zeichen am Ende der Zeichenfolge.

[out, optional] pcchRemaining

Typ: size_t*

Die Anzahl nicht verwendeter Zeichen in pszDest, einschließlich des abschließenden NULL-Zeichens. Wenn pcchRemainingNULL ist, wird die Anzahl nicht beibehalten oder zurückgegeben.

[in] dwFlags

Art: DWORD

Mindestens einer der folgenden Werte:

Wert	Bedeutung
STRSAFE_FILL_BEHIND_NULL 0x00000200	Wenn die Funktion erfolgreich ist, wird das niedrige Byte von dwFlags (0) verwendet, um den nicht initialisierten Teil von pszDest nach dem endenden NULL-Zeichen auszufüllen.
STRSAFE_IGNORE_NULLS 0x00000100	Behandeln Sie NULL-Zeichenfolgenzeiger wie leere Zeichenfolgen (TEXT("")). Dieses Flag ist nützlich, um Funktionen wie lstrcpy zu emulieren.
STRSAFE_FILL_ON_FAILURE 0x00000400	Wenn die Funktion fehlschlägt, wird das niedrige Byte von dwFlags (0) verwendet, um den gesamten pszDest-Puffer aufzufüllen, und der Puffer ist NULL-beendet. Im Falle eines STRSAFE_E_INSUFFICIENT_BUFFER Fehlers wird jede zurückgegebene abgeschnittene Zeichenfolge überschrieben.
STRSAFE_NULL_ON_FAILURE 0x00000800	Wenn die Funktion fehlschlägt, wird pszDest auf eine leere Zeichenfolge (TEXT("")) festgelegt. Im Falle eines STRSAFE_E_INSUFFICIENT_BUFFER Fehlers wird jede abgeschnittene Zeichenfolge überschrieben.
STRSAFE_NO_TRUNCATION 0x00001000	Wenn die Funktion fehlschlägt, wird wie bei STRSAFE_NULL_ON_FAILUREpszDest auf eine leere Zeichenfolge (TEXT("")) festgelegt. Im Falle eines STRSAFE_E_INSUFFICIENT_BUFFER Fehlers wird jede abgeschnittene Zeichenfolge überschrieben.

Rückgabewert

Typ: HRESULT

Es wird dringend empfohlen, die Makros SUCCEEDED und FAILED zu verwenden, um den Rückgabewert dieser Funktion zu testen.

Rückgabecode	BESCHREIBUNG
S_OK	Quelldaten wurden vorhanden, vollständig ohne Abschneiden kopiert, und der resultierende Zielpuffer ist NULL-beendet.
STRSAFE_E_INVALID_PARAMETER	Entweder ist pszDestNULL , wenn Quelldaten zum Kopieren vorhanden sind, oder ein ungültiges Flag wurde übergeben.
STRSAFE_E_INSUFFICIENT_BUFFER	Fehler beim Kopiervorgang aufgrund unzureichenden Pufferspeicherplatzes. Abhängig vom Wert von dwFlags kann der Zielpuffer eine abgeschnittene version des beabsichtigten Ergebnisses enthalten. In Situationen, in denen das Abschneiden akzeptabel ist, kann dies nicht unbedingt als Fehlerbedingung angesehen werden.

 

Beachten Sie, dass diese Funktion im Gegensatz zu den Funktionen, die sie ersetzt, einen HRESULT-Wert zurückgibt.

Hinweise

Im Vergleich zu den funktionen, die es ersetzt, bietet StringCchCopyEx zusätzliche Verarbeitung für die ordnungsgemäße Pufferbehandlung in Ihrem Code. Eine schlechte Pufferbehandlung ist in viele Sicherheitsprobleme verwickelt, die Pufferüberläufe beinhalten. StringCchCopyEx beendet immer NULL und überläuft nie einen gültigen Zielpuffer, auch wenn sich der Inhalt der Quellzeichenfolge während des Vorgangs ändert.

Das Verhalten ist nicht definiert, wenn sich die Zeichenfolgen, auf die von pszSrc und pszDest verwiesen wird, überlappen.

Weder pszSrc noch pszDest dürfen NULL sein, es sei denn, das STRSAFE_IGNORE_NULLS Flag ist angegeben. In diesem Fall können beide NULL sein. Ein Fehler aufgrund unzureichenden Speicherplatzes kann jedoch trotzdem zurückgegeben werden, obwohl NULL-Werte ignoriert werden.

StringCchCopyEx kann in seiner generischen Form oder in spezifischeren Formen verwendet werden. Der Datentyp der Zeichenfolge bestimmt die Form dieser Funktion, die Sie verwenden sollten.

String-Datentyp	Zeichenfolgenliterale	Funktion
char	„String“	StringCchCopyExA
TCHAR	TEXT("string")	StringCchCopyEx
WCHAR	L"string"	StringCchCopyExW

 

Hinweis

Der strsafe.h-Header definiert StringCchCopyEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP mit SP2 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 mit SP1 [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	strsafe.h

Weitere Informationen

Referenz

StringCbCopyEx

StringCchCopy