funzione StringCchVPrintf_lExA (strsafe.h)

  • Articolo

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.

StringCchVPrintf_lEx è simile a StringCchVPrintfEx , ma include un parametro per le informazioni sulle impostazioni locali.

Sintassi

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
);

Parametri

[out] pszDest

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

[in] cchDest

Dimensioni del buffer di destinazione, in caratteri. Questo valore deve essere sufficientemente grande per ospitare la stringa formattata finale più 1 per tenere conto del carattere Null terminante. Il numero massimo di caratteri consentiti è STRSAFE_MAX_CCH.

[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] pcchRemaining

Numero di caratteri inutilizzati in pszDest, incluso il carattere null terminante. Se pcchRemaining è 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 è stato copiato in pszDest senza troncamento e il buffer è terminato null.
STRSAFE_E_INVALID_PARAMETER
 Il valore in cchDest è 0 o maggiore di STRSAFE_MAX_CCH 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 StringCchVPrintf_lEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del 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

   
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