funzione StringCbVPrintf_lExA (strsafe.h)

Articolo
03/15/2023

Scrive i dati formattati nella stringa specificata usando un puntatore a un elenco di argomenti. Le dimensioni del buffer di destinazione vengono fornite alla funzione per assicurarsi che non venga scritto oltre la fine del buffer.

StringCbVPrintf_lEx è simile a StringCbVPrintfEx , ma include un parametro per le informazioni sulle impostazioni locali.

Sintassi

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

Parametri

[out] pszDest

Buffer di destinazione, che riceve la stringa con terminazione null formattata creata da pszFormat e argList.

[in] cbDest

Dimensioni del buffer di destinazione, in byte. Questo valore deve essere sufficientemente grande per contenere la stringa formattata finale e il carattere null terminante. Il numero massimo di byte consentiti è STRSAFE_MAX_CCH * sizeof(TCHAR).

[out] ppszDestEnd

Indirizzo di un puntatore alla fine di pszDest. Se ppszDestEnd non è NULL e tutti i dati vengono copiati nel buffer di destinazione, questo punta al carattere Null terminante alla fine della stringa.

[out, optional] pcbRemaining

Numero di byte inutilizzati in pszDest, inclusi quelli usati per il carattere null terminante. Se pcbRemaining è NULL, il conteggio non viene mantenuto o restituito.

[in] dwFlags

Uno o più dei valori seguenti.

Valore	Significato
STRSAFE_FILL_BEHIND_NULL 0x00000200	Se la funzione ha esito positivo, il byte basso di dwFlags (0) viene usato per riempire la parte non inizializzata di pszDest seguendo il carattere null terminante.
STRSAFE_IGNORE_NULLS 0x00000100	Trattare i puntatori di stringa NULL come stringhe vuote (TEXT("")).
STRSAFE_FILL_ON_FAILURE 0x00000400	Se la funzione ha esito negativo, il byte basso di dwFlags (0) viene usato per riempire l'intero buffer pszDest e il buffer viene terminato con null. Nel caso di un errore di STRSAFE_E_INSUFFICIENT_BUFFER , qualsiasi stringa troncata restituita viene sovrascritto.
STRSAFE_NULL_ON_FAILURE 0x00000800	Se la funzione ha esito negativo, pszDest è impostata su una stringa vuota (TEXT("")). Nel caso di un errore di STRSAFE_E_INSUFFICIENT_BUFFER , qualsiasi stringa troncata viene sovrascritta.
STRSAFE_NO_TRUNCATION 0x00001000	Come nel caso di STRSAFE_NULL_ON_FAILURE, se la funzione ha esito negativo, pszDest è impostata su una stringa vuota (TEXT("")). Nel caso di un errore di STRSAFE_E_INSUFFICIENT_BUFFER , qualsiasi stringa troncata viene sovrascritta.

[in] pszFormat

Stringa di formato. Questa stringa deve essere terminata con null. Per altre informazioni, vedere Sintassi della specifica del formato.

[in] locale

Oggetto delle impostazioni locali. Per altre informazioni, vedere _create_locale.

[in] argList

Argomenti da inserire nella stringa pszFormat .

Valore restituito

Questa funzione può restituire uno dei valori seguenti. È consigliabile usare le macro SUCCESSED e FAILED per testare il valore restituito di questa funzione.

Codice restituito	Descrizione
S_OK	Il risultato deve essere copiato in pszDest senza troncamento e il buffer viene terminato con null.
STRSAFE_E_INVALID_PARAMETER	Il valore in cbDest è 0 o maggiore di `STRSAFE_MAX_CCH * sizeof(TCHAR)`oppure il buffer di destinazione è già pieno.
STRSAFE_E_INSUFFICIENT_BUFFER	L'operazione di copia non è riuscita a causa di spazio buffer insufficiente. A seconda del valore di dwFlags, il buffer di destinazione può contenere una versione troncata e terminata null del risultato previsto. In situazioni in cui il troncamento è accettabile, questo potrebbe non essere necessariamente considerato come una condizione di errore.

Commenti

Per altre informazioni sulle va_lists, vedere le convenzioni definite in Stdarg.h.

Il comportamento non è definito se le stringhe puntate da pszDest, pszFormat o qualsiasi stringa di argomento si sovrappone.

Né pszFormat né pszDest devono essere NULL a meno che non sia specificato il flag di STRSAFE_IGNORE_NULLS, in cui entrambi possono essere NULL. Tuttavia, un errore dovuto a spazio insufficiente può essere restituito anche se i valori NULL vengono ignorati.

Per usare questa funzione, è necessario definire la macro seguente nel file di intestazione, prima di includere StrSafe.h.

#define STRSAFE_LOCALE_FUNCTIONS

Nota

L'intestazione strsafe.h definisce StringCbVPrintf_lEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	strsafe.h

Condividi tramite