StringCchVPrintf_lExA Funktion (strsafe.h)

  • Artikel
  • 3 Minuten Lesedauer

Schreibt formatierte Daten mithilfe eines Zeigers auf eine Liste von Argumenten 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.

StringCchVPrintf_lEx ähnelt StringCchVPrintfEx , enthält jedoch einen Parameter für Gebietsschemainformationen.

Syntax

STRSAFEAPI StringCchVPrintf_lExA(
  [out]           STRSAFE_LPSTR                                  pszDest,
  [in]            size_t                                         cchDest,
  [out]           STRSAFE_LPSTR                                  *ppszDestEnd,
  [out, optional] size_t                                         *pcchRemaining,
  [in]            DWORD                                          dwFlags,
  [in]            _Printf_format_string_params_(2)STRSAFE_LPCSTR pszFormat,
  [in]            _locale_t                                      locale,
  [in]            va_list                                        argList
);

Parameter

[out] pszDest

Der Zielpuffer, der die formatierte, null-beendete Zeichenfolge empfängt, die aus pszFormat und argList erstellt wurde.

[in] cchDest

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 endende Nullzeichen zu berücksichtigen. Die maximale Anzahl zulässiger Zeichen ist STRSAFE_MAX_CCH.

[out] ppszDestEnd

Die Adresse eines Zeigers auf das Ende von pszDest. Wenn ppszDestEndnicht NULL ist und alle Daten in den Zielpuffer kopiert werden, verweist dies auf das endende Nullzeichen am Ende der Zeichenfolge.

[out, optional] pcchRemaining

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

Mindestens eine der folgenden Werte.

Wert Bedeutung
STRSAFE_FILL_BEHIND_NULL
0x00000200
 Wenn die Funktion erfolgreich verläuft, wird der niedrige Byte von dwFlags (0) verwendet, um den nicht initialisierten Teil von pszDest nach dem beendenden NULL-Zeichen auszufüllen.
STRSAFE_IGNORE_NULLS
0x00000100
 Behandeln von NULL-Zeichenfolgenzeigern wie leere Zeichenfolgen (TEXT("")).
STRSAFE_FILL_ON_FAILURE
0x00000400
 Wenn die Funktion fehlschlägt, wird der niedrige Byte von dwFlags (0) zum Ausfüllen des gesamten pszDest-Puffers verwendet, und der Puffer ist null beendet. Bei einem STRSAFE_E_INSUFFICIENT_BUFFER Fehler wird eine abgeschnittene Zeichenfolge überschrieben.
STRSAFE_NULL_ON_FAILURE
0x00000800
 Wenn die Funktion fehlschlägt, wird pszDest auf eine leere Zeichenfolge (TEXT("")festgelegt. Bei einem STRSAFE_E_INSUFFICIENT_BUFFER Fehler wird eine abgeschnittene Zeichenfolge überschrieben.
STRSAFE_NO_TRUNCATION
0x00001000
 Wenn die Funktion fehlschlägt, wird pszDest wie bei STRSAFE_NULL_ON_FAILURE auf eine leere Zeichenfolge (TEXT("")festgelegt. Bei einem STRSAFE_E_INSUFFICIENT_BUFFER Fehler wird eine abgeschnittene Zeichenfolge überschrieben.

[in] pszFormat

Die Formatzeichenfolge. Diese Zeichenfolge muss null beendet werden. Weitere Informationen finden Sie unter Formatspezifikationssyntax.

[in] locale

Das Gebietsschemaobjekt. Weitere Informationen finden Sie unter _create_locale.

[in] argList

Die Argumente, die in die pszFormat-Zeichenfolge eingefügt werden sollen.

Rückgabewert

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
S_OK
 Es gab ausreichend Platz für das Ergebnis, das ohne Abschneiden in pszDest kopiert werden soll, und der Puffer ist NULL-beendet.
STRSAFE_E_INVALID_PARAMETER
 Der Wert in cchDest ist entweder 0 oder größer als STRSAFE_MAX_CCH, oder der Zielpuffer ist bereits voll.
STRSAFE_E_INSUFFICIENT_BUFFER
 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.

Hinweise

Weitere Informationen zu va_lists finden Sie in den in Stdarg.h definierten Konventionen.

Das Verhalten ist nicht definiert, wenn sich die Zeichenfolgen, auf die pszDest, pszFormat oder alle Argumentzeichenfolgen verweisen, überlappen.

Weder pszFormat nochpszDest 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.

Um diese Funktion zu verwenden, müssen Sie das folgende Makro in Ihrer Kopfzeilendatei definieren, bevor Sie StrSafe.h einschließen.

#define STRSAFE_LOCALE_FUNCTIONS

Hinweis

Der strsafe.h-Header definiert StringCchVPrintf_lEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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 Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile strsafe.h