StringCchPrintfExW-Funktion (strsafe.h)
Schreibt formatierte Daten in die angegebene Zeichenfolge. Die Größe des Zielpuffers wird für die Funktion bereitgestellt, um sicherzustellen, dass er nicht über das Ende dieses Puffers schreibt.
StringCchPrintfEx fügt die Funktionalität von StringCchPrintf hinzu, indem sie einen Zeiger an das Ende der Zielzeichenfolge zurückgibt, sowie die Anzahl von Zeichen, die in dieser Zeichenfolge nicht verwendet werden. Flags können auch an die Funktion für zusätzliche Steuerelemente übergeben werden.
StringCchPrintfEx ist ein Ersatz für die folgenden Funktionen:
Syntax
STRSAFEAPI StringCchPrintfExW(
[out] STRSAFE_LPWSTR pszDest,
[in] size_t cchDest,
[out, optional] STRSAFE_LPWSTR *ppszDestEnd,
[out, optional] size_t *pcchRemaining,
[in] DWORD dwFlags,
[in] STRSAFE_LPCWSTR pszFormat,
...
);
Parameter
[out] pszDest
Typ: LPTSTR
Der Zielpuffer, der die formatierte, null-beendete Zeichenfolge empfängt, die von pszFormat und seinen Argumenten erstellt wurde.
[in] cchDest
Typ: size_t
Die Größe des Zielpuffers in Zeichen. Dieser Wert muss ausreichend groß sein, um die endgültige formatierte Zeichenfolge plus 1 zu berücksichtigen, um das endeende Nullzeichen zu berücksichtigen. Die maximale Anzahl zulässiger Zeichen ist STRSAFE_MAX_CCH.
[out, optional] ppszDestEnd
Typ: LPTSTR*
Die Adresse eines Zeigers am Ende von pszDest. Wenn ppszDestEnd nicht NULL ist und alle Daten in den Zielpuffer kopiert werden, verweist dies auf das Endzeichen null am Ende der Zeichenfolge.
[out, optional] pcchRemaining
Typ: size_t*
Die Anzahl der nicht verwendeten Zeichen in pszDest, einschließlich des terminierenden Nullzeichens. Wenn pcchRemainingNULL ist, wird die Anzahl nicht beibehalten oder zurückgegeben.
[in] dwFlags
Art: DWORD
Mindestens eine der folgenden Werte.
[in] pszFormat
Typ: LPCTSTR
Die Formatzeichenfolge. Diese Zeichenfolge muss null-beendet sein. Weitere Informationen finden Sie unter Formatspezifikationssyntax.
...
Die Argumente, die in die pszFormat-Zeichenfolge eingefügt werden sollen.
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 |
|---|---|
|
Es gab genügend Speicherplatz für das Ergebnis, das in pszDest kopiert werden soll, ohne abgeschnitten zu werden, und der Puffer ist null-beendet. |
|
Der Wert in cchDest ist entweder 0 oder größer als STRSAFE_MAX_CCH, oder der Zielpuffer ist bereits vollständig. |
|
Der Kopiervorgang konnte aufgrund des unzureichenden Pufferraums fehlgeschlagen sein. 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, anders als die Funktionen, die sie ersetzt.
Hinweise
Im Vergleich zu den funktionen, die sie ersetzt, bietet StringCchPrintfEx zusätzliche Verarbeitung für die richtige Pufferbehandlung in Ihrem Code. Die schlechte Pufferbehandlung wird in vielen Sicherheitsproblemen, die Pufferüberläufe umfassen, im Zusammenhang mit Pufferüberläufen einbezogen. StringCchPrintfEx beendet immer null-beendet einen Nichtzero-Länge-Zielpuffer.
Das Verhalten ist nicht definiert, wenn die Zeichenfolgen, die von pszDest, pszFormat oder allen Argumentzeichenfolgen überlappen.
Weder pszFormat 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 immer noch zurückgegeben werden, obwohl NULL-Werte ignoriert werden.
StringCchPrintfEx kann in seinem generischen Formular oder in seinen spezifischeren Formularen verwendet werden. Der Datentyp der Zeichenfolge bestimmt die Form dieser Funktion, die Sie verwenden sollten.
| String-Datentyp | Zeichenfolgenliterale | Funktion |
|---|---|---|
| char | „String“ | StringCchPrintfExA |
| TCHAR | TEXT("string") | StringCchPrintfEx |
| WCHAR | L"string" | StringCchPrintfExW |
Hinweis
Der strsafe.h-Header definiert StringCchPrintfEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstanten automatisch auswählt. Das Mischen der Verwendung des Codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann dazu führen, dass keine Übereinstimmungen auftreten, 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