StringCchCatNExA-Funktion (strsafe.h)
Verkettet die angegebene Anzahl von Zeichen zwischen einer Zeichenfolge und einer anderen Zeichenfolge. Die Größe des Zielpuffers wird für die Funktion bereitgestellt, um sicherzustellen, dass er nicht über das Ende dieses Puffers schreibt.
StringCchCatNEx fügt der Funktionalität von StringCchCatN hinzu, indem ein Zeiger an das Ende der Zielzeichenfolge sowie die Anzahl der zeichen zurückgegeben wird, die in dieser Zeichenfolge nicht verwendet wurden. Flags können auch an die Funktion für zusätzliche Steuerelemente übergeben werden.
StringCchCatNEx ist ein Ersatz für die folgenden Funktionen:
Syntax
STRSAFEAPI StringCchCatNExA(
[in, out] STRSAFE_LPSTR pszDest,
[in] size_t cchDest,
[in] STRSAFE_PCNZCH pszSrc,
[in] size_t cchToAppend,
[out, optional] STRSAFE_LPSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags
);
Parameter
[in, out] pszDest
Typ: LPTSTR
Der Zielpuffer, der die Zeichenfolge enthält, die mit pszSrc verkettet werden soll, und erhält die gesamte resultierende Zeichenfolge. Die Zeichenfolge bei pszSrc wird am Ende der Zeichenfolge bei pszDest hinzugefügt.
[in] cchDest
Typ: size_t
Die Größe des Zielpuffers in Zeichen. Dieser Wert muss der Länge von pszSrc plus der Länge von pszDest plus 1 entsprechen, um das endierende Nullzeichen zu berücksichtigen. Die maximale Anzahl zulässiger Zeichen ist STRSAFE_MAX_CCH.
[in] pszSrc
Typ: LPCTSTR
Die Quellzeichenfolge, die am Ende von pszDest verkettet ist. Diese Zeichenfolge muss null beendet werden.
[in] cchToAppend
Typ: size_t
Die maximale Anzahl von Zeichen, die an pszDest angefügt werden sollen.
[out, optional] ppszDestEnd
Typ: LPTSTR*
Die Adresse eines Zeigers auf das Ende von pszDest. Wenn ppszDestEndnicht NULL ist und alle Daten an den Zielpuffer angefügt werden, verweist dies auf das endende Nullzeichen am Ende der Zeichenfolge.
[out, optional] pcchRemaining
Typ: size_t*
Die Anzahl nicht verwendeter Zeichen in pszDest, einschließlich des endenden Nullzeichens. Wenn pcchRemainingNULL ist, wird die Anzahl nicht aufbewahrt oder zurückgegeben.
[in] dwFlags
Art: DWORD
Mindestens eine der folgenden Werte.
Rückgabewert
Typ: HRESULT
Diese Funktion kann einen der folgenden Werte zurückgeben. Es wird dringend empfohlen, dass Sie die ERFOLGREICHen und FEHLGESCHLAGENen Makros verwenden, um den Rückgabewert dieser Funktion zu testen.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Quelldaten wurden vorhanden, die Zeichenfolgen wurden ohne Abschneiden verkettet, und der resultierende Zielpuffer ist NULL-beendet. |
|
Der Wert in cchDest ist größer als STRSAFE_MAX_CCH, ein ungültiges Flag wurde übergeben, oder es gibt Abweichungen zwischen der Größe des pszDest, cchDest und der Menge des Materials, das in pszSrc angefügt werden soll. |
|
Fehler beim Kopiervorgang aufgrund unzureichender Pufferspeicherung. Abhängig vom Wert von dwFlags kann der Zielpuffer eine abgeschnittene, null-beendete Version des beabsichtigten Ergebnisses enthalten. In Situationen, in denen abgeschnitten werden kann, kann dies möglicherweise nicht unbedingt als Fehlerbedingung angesehen werden. |
Beachten Sie, dass diese Funktion einen HRESULT-Wert zurückgibt, im Gegensatz zu den Funktionen, die sie ersetzt.
Bemerkungen
Im Vergleich zu den ersetzten Funktionen bietet StringCchCatNEx zusätzliche Verarbeitung für die ordnungsgemäße Pufferbehandlung in Ihrem Code. Eine schlechte Pufferbehandlung ist in vielen Sicherheitsproblemen mit Pufferüberläufen verbunden. StringCchCatNEx wird immer null beendet und überläuft niemals 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 durch pszSrc und pszDest überlappen.
Weder pszSrc noch pszDest sollten NULL sein, es sei denn, das STRSAFE_IGNORE_NULLS Flag wird angegeben, in diesem Fall kann beide NULL sein. Ein Fehler aufgrund unzureichender Leerzeichen kann jedoch weiterhin zurückgegeben werden, auch wenn NULL-Werte ignoriert werden.
StringCchCatNEx kann in der 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“ | StringCchCatNExA |
| TCHAR | TEXT("string") | StringCchCatNEx |
| WCHAR | L"string" | StringCchCatNExW |
Hinweis
Der strsafe.h-Header definiert StringCchCatNEx als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der codierungsneutralen Aliase mit Code, der nicht codierungsneutral ist, kann zu Übereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| 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