Função StringCbCatA (strsafe.h)
Concatena uma cadeia de caracteres para outra cadeia de caracteres. O tamanho do buffer de destino é fornecido à função para garantir que ele não escreva além do final desse buffer.
StringCbCat é uma substituição para as seguintes funções:
Sintaxe
STRSAFEAPI StringCbCatA(
[in, out] STRSAFE_LPSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_LPCSTR pszSrc
);
Parâmetros
[in, out] pszDest
Tipo: LPTSTR
A cadeia de caracteres para a qual pszSrc deve ser concatenado e que receberá toda a cadeia de caracteres resultante. A cadeia de caracteres em pszSrc é adicionada ao final da cadeia de caracteres em pszDest.
[in] cbDest
Tipo: size_t
O tamanho do buffer de destino, em bytes. Esse valor deve considerar o comprimento de pszSrc mais o comprimento de pszDest mais o caractere nulo de terminação. O número máximo de bytes permitidos é STRSAFE_MAX_CCH * sizeof(TCHAR).
[in] pszSrc
Tipo: LPCTSTR
A cadeia de caracteres de origem que deve ser concatenada até o final do pszDest. Essa cadeia de caracteres deve ser terminada em nulo.
Valor retornado
Tipo: HRESULT
Essa função pode retornar um dos valores a seguir. É altamente recomendável que você use as macros SUCCEEDED e FAILED para testar o valor retornado dessa função.
| Código de retorno | Descrição |
|---|---|
|
Os dados de origem estavam presentes, as cadeias de caracteres estavam totalmente concatenadas sem truncamento e o buffer de destino resultante foi encerrado em nulo. |
|
O valor em cbDest é menor sizeof(TCHAR) ou maior que o valor máximo permitido.
|
|
Falha na operação de concatenação devido a espaço em buffer insuficiente. O buffer de destino contém uma versão truncada e terminada em nulo do resultado pretendido. Em situações em que o truncamento é aceitável, isso pode não ser necessariamente visto como uma condição de falha. |
Observe que essa função retorna um valor HRESULT , ao contrário das funções que ela substitui.
Comentários
StringCbCat fornece processamento adicional para tratamento de buffer adequado em seu código. A má manipulação de buffer está implicada em muitos problemas de segurança que envolvem estouros de buffer. Ele sempre termina em nulo e nunca estoura um buffer de destino válido, mesmo que o conteúdo da cadeia de caracteres de origem seja alterado durante a operação.
StringCbCat pode ser usado em sua forma genérica ou em suas formas mais específicas. O tipo de dados da cadeia de caracteres determina a forma dessa função que você deve usar, conforme mostrado na tabela a seguir.
| Tipo de dados da cadeia de caracteres | Literal da cadeia de caracteres | Função |
|---|---|---|
| char | “cadeia de caracteres” | StringCbCatA |
| TCHAR | TEXT("string") | StringCbCat |
| WCHAR | L"string" | StringCbCatW |
O comportamento será indefinido se as cadeias de caracteres apontadas por pszSrc e pszDest se sobrepõem.
Nem pszSrc nem pszDest devem ser NULL. Consulte StringCbCatEx se você precisar da manipulação de valores de ponteiro de cadeia de caracteres nula.
Observação
O cabeçalho strsafe.h define StringCbCat como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows XP com SP2 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 com SP1 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | strsafe.h |
Confira também
Referência