Expand Minimize

CryptMsgUpdate function

The CryptMsgUpdate function adds contents to a cryptographic message. The use of this function allows messages to be constructed piece by piece through repetitive calls of CryptMsgUpdate. The added message content is either encoded or decoded depending on whether the message was opened with CryptMsgOpenToEncode or CryptMsgOpenToDecode.

Syntax


BOOL WINAPI CryptMsgUpdate(
  _In_  HCRYPTMSG hCryptMsg,
  _In_  const BYTE *pbData,
  _In_  DWORD cbData,
  _In_  BOOL fFinal
);

Parameters

hCryptMsg [in]

Cryptographic message handle of the message to be updated.

pbData [in]

A pointer to the buffer holding the data to be encoded or decoded.

cbData [in]

Number of bytes of data in the pbData buffer.

fFinal [in]

Indicates that the last block of data for encoding or decoding is being processed. Correct usage of this flag is dependent upon whether the message being processed has detached data. The inclusion of detached data in a message is indicated by setting dwFlags to CMSG_DETACHED_FLAG in the call to the function that opened the message.

If CMSG_DETACHED_FLAG was not set and the message was opened using either CryptMsgOpenToDecode or CryptMsgOpenToEncode, fFinal is set to TRUE, and CryptMsgUpdate is only called once.

If the CMSG_DETACHED_FLAG flag was set and a message is opened using CryptMsgOpenToEncode, fFinal is set to TRUE only on the last call to CryptMsgUpdate.

If the CMSG_DETACHED_FLAG flag was set and a message is opened using CryptMsgOpenToDecode, fFinal is set to TRUE when the header is processed by a single call to CryptMsgUpdate. It is set to FALSE while processing the detached data in subsequent calls to CryptMsgUpdate until the last detached data block is to be processed. On the last call to CryptMsgUpdate, it is set to TRUE.

When detached data is decoded, the header and the content of a message are contained in different BLOBs. Each BLOB requires that fFinal be set to TRUE when the last call to the function is made for that BLOB.

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.

Errors encountered in the application defined callback function specified by pStreamInfo in CryptMsgOpenToDecode and CryptMsgOpenToEncode might be propagated to CryptMsgUpdate if streaming is used. If this happens, SetLastError is not called by CryptMsgUpdate after the callback function returns, which preserves any errors encountered under the control of the application. It is the responsibility of the callback function (or one of the APIs that it calls) to call SetLastError if an error occurs while the application is processing the streamed data.

The following table lists the error codes most commonly returned by the GetLastError function.

Return codeDescription
CRYPT_E_INVALID_MSG_TYPE

The message type is not valid.

CRYPT_E_MSG_ERROR

An error was encountered doing a cryptographic operation.

CRYPT_E_OID_FORMAT

The object identifier is badly formatted.

CRYPT_E_UNEXPECTED_ENCODING

The message is not encoded as expected.

CRYPT_E_UNKNOWN_ALGO

The cryptographic algorithm is unknown.

E_INVALIDARG

One or more arguments are not valid.

E_OUTOFMEMORY

Ran out of memory.

 

Propagated errors might be encountered from any of the following functions:

If the function fails, GetLastError may return an Abstract Syntax Notation One (ASN.1) encoding/decoding error. For information about these errors, see ASN.1 Encoding/Decoding Return Values.

Examples

For examples that use this function, see Example C Program: Signing, Encoding, Decoding, and Verifying a Message, Alternate Code for Encoding an Enveloped Message, Example C Program: Encoding an Enveloped, Signed Message, and Example C Program: Encoding and Decoding a Hashed Message.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

Low-level Message Functions
Simplified Message Functions
CryptMsgGetParam
CryptMsgOpenToDecode
CryptMsgOpenToEncode

 

 

Community Additions

ADD
Show:
© 2014 Microsoft