Função CryptMsgUpdate (wincrypt.h)

Artigo
08/27/2023

A função CryptMsgUpdate adiciona conteúdo a uma mensagem criptográfica. O uso dessa função permite que as mensagens sejam construídas por peça por meio de chamadas repetitivas de CryptMsgUpdate. O conteúdo da mensagem adicionada é codificado ou decodificado dependendo se a mensagem foi aberta com CryptMsgOpenToEncode ou CryptMsgOpenToDecode.

Sintaxe

BOOL CryptMsgUpdate(
  [in] HCRYPTMSG  hCryptMsg,
  [in] const BYTE *pbData,
  [in] DWORD      cbData,
  [in] BOOL       fFinal
);

Parâmetros

[in] hCryptMsg

Identificador de mensagem criptográfica da mensagem a ser atualizada.

[in] pbData

Um ponteiro para o buffer que contém os dados a serem codificados ou decodificados.

[in] cbData

Número de bytes de dados no buffer pbData .

[in] fFinal

Indica que o último bloco de dados para codificação ou decodificação está sendo processado. O uso correto desse sinalizador depende se a mensagem que está sendo processada tem dados desanexados. A inclusão de dados desanexados em uma mensagem é indicada definindo dwFlags como CMSG_DETACHED_FLAG na chamada para a função que abriu a mensagem.

Se CMSG_DETACHED_FLAG não tiver sido definida e a mensagem tiver sido aberta usando CryptMsgOpenToDecode ou CryptMsgOpenToEncode, fFinal será definida como TRUE e CryptMsgUpdate será chamada apenas uma vez.

Se o sinalizador CMSG_DETACHED_FLAG tiver sido definido e uma mensagem for aberta usando CryptMsgOpenToEncode, fFinal será definida como TRUE somente na última chamada para CryptMsgUpdate.

Se o sinalizador CMSG_DETACHED_FLAG foi definido e uma mensagem é aberta usando CryptMsgOpenToDecode, fFinal é definido como TRUE quando o cabeçalho é processado por uma única chamada para CryptMsgUpdate. Ele é definido como FALSE ao processar os dados desanexados em chamadas subsequentes para CryptMsgUpdate até que o último bloco de dados desanexado seja processado. Na última chamada para CryptMsgUpdate, ela é definida como TRUE.

Quando os dados desanexados são decodificados, o cabeçalho e o conteúdo de uma mensagem estão contidos em BLOBs diferentes. Cada BLOB requer que fFinal seja definido como TRUE quando a última chamada para a função for feita para esse BLOB.

Retornar valor

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.

Erros encontrados na função de retorno de chamada definida pelo aplicativo especificada por pStreamInfo em CryptMsgOpenToDecode e CryptMsgOpenToEncode poderão ser propagados para CryptMsgUpdate se o streaming for usado. Se isso acontecer, SetLastError não será chamado por CryptMsgUpdate depois que a função de retorno de chamada retornar, o que preservará todos os erros encontrados sob o controle do aplicativo. É responsabilidade da função de retorno de chamada (ou uma das APIs que ela chama) chamar SetLastError se ocorrer um erro enquanto o aplicativo estiver processando os dados transmitidos.

A tabela a seguir lista os códigos de erro mais comumente retornados pela função GetLastError .

Código de retorno	Descrição
CRYPT_E_INVALID_MSG_TYPE	O tipo de mensagem não é válido.
CRYPT_E_MSG_ERROR	Erro ao realizar uma operação criptográfica.
CRYPT_E_OID_FORMAT	O identificador de objeto está mal formatado.
CRYPT_E_UNEXPECTED_ENCODING	A mensagem não está codificada conforme o esperado.
CRYPT_E_UNKNOWN_ALGO	O algoritmo criptográfico é desconhecido.
E_INVALIDARG	Um ou mais argumentos não são válidos.
E_OUTOFMEMORY	Ficou sem memória.

Erros propagados podem ser encontrados de qualquer uma das seguintes funções:

Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll

Confira também

Cryptmsggetparam

Cryptmsgopentodecode

Cryptmsgopentoencode

Funções de mensagem de baixo nível

Funções de mensagem simplificadas