Funzione StringCbCatNExA (strsafe.h)
Concatena il numero specificato di byte da una stringa a un'altra. Le dimensioni del buffer di destinazione vengono fornite alla funzione per assicurarsi che non venga scritto oltre la fine del buffer.
StringCbCatNEx è una sostituzione delle funzioni seguenti:
StringCbCatNEx aggiunge alla funzionalità di StringCbCatN restituendo un puntatore alla fine della stringa di destinazione, nonché il numero di byte rimasti inutilizzati in tale stringa. I flag possono anche essere passati alla funzione per un controllo aggiuntivo.Sintassi
STRSAFEAPI StringCbCatNExA(
[in, out] STRSAFE_LPSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_PCNZCH pszSrc,
[in] size_t cbToAppend,
[out, optional] STRSAFE_LPSTR *ppszDestEnd,
[out, optional] size_t *pcbRemaining,
[in] DWORD dwFlags
);
Parametri
[in, out] pszDest
Tipo: LPTSTR
Il buffer di destinazione, che contiene la stringa da concatenare con pszSrc e riceverà l'intera stringa risultante. La stringa in pszSrc viene aggiunta alla fine della stringa in pszDest.
[in] cbDest
Tipo: size_t
Dimensioni del buffer di destinazione, in byte. Questo valore deve considerare la lunghezza di pszSrc più la lunghezza di pszDest più i byte usati per il carattere Null di terminazione. Il numero massimo di byte consentiti è STRSAFE_MAX_CCH * sizeof(TCHAR).
[in] pszSrc
Tipo: LPCTSTR
Stringa di origine da concatenare alla fine di pszDest. Questa stringa deve essere con terminazione Null.
[in] cbToAppend
Tipo: size_t
Numero massimo di byte da aggiungere a pszDest.
[out, optional] ppszDestEnd
Tipo: LPTSTR*
Indirizzo di un puntatore alla fine di pszDest. Se ppszDestEnd è diverso da NULL e tutti i dati vengono accodati al buffer di destinazione, punta al carattere Null di terminazione alla fine della stringa.
[out, optional] pcbRemaining
Tipo: size_t*
Numero di byte inutilizzati in pszDest, inclusi quelli usati per il carattere Null di terminazione. Se pcbRemaining è NULL, il conteggio non viene mantenuto o restituito.
[in] dwFlags
Tipo: DWORD
Uno o più dei valori seguenti.
Valore restituito
Tipo: HRESULT
Questa funzione può restituire uno dei valori seguenti. È consigliabile utilizzare le macro SUCCEEDED e FAILED per testare il valore restituito di questa funzione.
| Codice restituito | Descrizione |
|---|---|
|
I dati di origine erano presenti, le stringhe sono state concatenate senza troncamento e il buffer di destinazione risultante è con terminazione Null. |
|
Il valore in cbDest è maggiore di STRSAFE_MAX_CCH * sizeof(TCHAR), è stato passato un flag non valido o sono presenti discrepanze tra le dimensioni di pszDest, cbDest e la quantità di materiale da accodare in pszSrc.
|
|
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 con terminazione Null del risultato previsto. Nelle situazioni in cui il troncamento è accettabile, questo potrebbe non essere necessariamente considerato come una condizione di errore. |
Si noti che questa funzione restituisce un valore HRESULT , a differenza delle funzioni che sostituisce.
Commenti
Rispetto alle funzioni che sostituisce, StringCbCatNEx fornisce un'elaborazione aggiuntiva per la gestione corretta del buffer nel codice. La gestione del buffer insufficiente è implicata in molti problemi di sicurezza che comportano sovraccarichi del buffer. StringCbCatNEx termina sempre null-terminate e non esegue mai l'overflow di un buffer di destinazione valido, anche se il contenuto della stringa di origine cambia durante l'operazione.
Il comportamento non è definito se le stringhe a cui punta pszSrc e pszDest si sovrappongono.
Né pszSrc né pszDest devono essere NULL a meno che non venga specificato il flag STRSAFE_IGNORE_NULLS , nel qual caso entrambi possono essere NULL. Tuttavia, è possibile che venga restituito un errore dovuto a spazio insufficiente anche se i valori NULL vengono ignorati.
StringCbCatNEx può essere usato nel formato generico o nei moduli più specifici. Il tipo di dati della stringa determina la forma di questa funzione da usare.
| Tipo di dati String | Stringhe letterali | Funzione |
|---|---|---|
| char | "stringa" | StringCbCatNExA |
| TCHAR | TEXT("string") | StringCbCatNEx |
| WCHAR | L"string" | StringCbCatNExW |
Nota
L'intestazione strsafe.h definisce StringCbCatNEx 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 indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP con SP2 [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 con SP1 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | strsafe.h |
Vedi anche
Riferimento