Função StringCbCatW (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 após o final desse buffer.
StringCbCat é uma substituição para as seguintes funções:
- strcat, wcscat, _tcsat
- lstrcat
- StrCat
- StrCatBuff
Sintaxe
STRSAFEAPI StringCbCatW(
[in, out] STRSAFE_LPWSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_LPCWSTR pszSrc
);
Parâmetros
[in, out] pszDest
Tipo: LPTSTR
A cadeia de caracteres à qual pszSrc deve ser concatenada 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 de pszDest. Essa cadeia de caracteres deve ser terminada em nulo.
Valor de retorno
Tipo: HRESULT
Essa função pode retornar um dos valores a seguir. É altamente recomendável que você use o bem-sucedido e macros de COM FALHA para testar o valor retornado dessa função.
| Código de retorno | Descrição |
|---|---|
|
Os dados de origem estavam presentes, as cadeias de caracteres foram totalmente concatenadas sem truncamento e o buffer de destino resultante foi encerrado em nulo. |
|
O valor em cbDest é menor que sizeof(TCHAR) ou maior que o valor máximo permitido.
|
|
A operação de concatenação falhou devido ao 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, diferentemente das funções que ela substitui.
Observações
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 sobrecargas de buffer. Ele sempre termina nulo e nunca excede um buffer de destino válido, mesmo se o conteúdo da cadeia de caracteres de origem for 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 de cadeia de caracteres | Literal de cadeia de caracteres | Função |
|---|---|---|
| char | "string" | |
| TCHAR | TEXT("string") | StringCbCat |
| WCHAR | L"string" | |
O comportamento será indefinido se as cadeias de caracteres apontadas por pszSrc e pszDest sobreposição.
Nem pszSrc nem pszDest devem ser NULL. Consulte StringCbCatEx se você precisar lidar com valores nulos de ponteiro de cadeia de caracteres.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP com SP2 [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 com SP1 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | strsafe.h |
Consulte também
de referência de