CMSG_STREAM_INFO

The CMSG_STREAM_INFO structure is used when you want to stream data rather than process it as a single block (for example, when processing very large messages). Messages may originate from any serialized source of data, such as a file on a hard disk, a server, CD ROM, etc.

This structure is passed to CryptMsgOpenToEncode and CryptMsgOpenToDecode.

Messages can be so large that processing them all at once by storing the data in memory can be difficult, if not impossible, depending on the amount of memory available on your computer. It is possible to process large messages without encountering memory limitations by streaming the data that is to be processed, in manageable sized blocks. The low-level message functions can be used when streaming to encode a message, and when streaming to decode a message. Any level of nesting of messages is supported when streaming to encode and streaming to decode.

The input message that is to be processed as a stream, is fed into CryptMsgUpdate by the application one block at a time, with the application determining the size of the block. As the streamed message is processed for encoding or decoding, the resulting output data is passed back to the application through an application specified callback function specified by the pfnStreamOutput member.

No assumptions should be made about the block size of the output data, since the size can vary for several reasons. When processing an enveloped message, the block size for the encryption algorithm can cause jitter in the output data block size. When processing input data, blocks that contain the message header and the SignerInfo (as defined by PKCS # 7) can affect output data block size.

The size of the output block is passed to the callback function in cbData. The application decides how to use the output data. Typically, this output data will not be persisted in memory as a whole by the application due to memory limitations, but will be serialized to a file on a hard disk, or a server, etc.

typedef struct _CMSG_STREAM_INFO {
    DWORD                    cbContent;
    PFN_CMSG_STREAM_OUTPUT   pfnStreamOutput;
    void                    *pvArg;
} CMSG_STREAM_INFO, *PCMSG_STREAM_INFO;
 

Members

cbContent

Specifies the count of bytes of the content. DER encoding is used unless a 0xFFFFFFFF is passed, which indicates that the application is not specifying the length and forces indefinite-length BER encoding to be used.

pfnStreamOutput

The address of a callback function. Typically, this callback is used to read and write data to a disk when processing large messages.

pvArg

The argument to pass to the callback function. Typically, this is used for state data which includes the handle to a more deeply nested message (when decoding) or a less deeply nested message (when encoding).

pfnStreamOutputCallback

An application-defined callback function that is called by CryptMsgUpdate (for encode and decode of messages) and by CryptMsgControl (when decoding enveloped messages) when streaming is being used. Streaming is enabled when pStreamInfo is not NULL in calls to CryptMsgOpenToDecode and CryptMsgOpenToEncode.

BOOL WINAPI CmsgStreamOutputCallback(
  IN const void *pvArg,  //in
  IN BYTE *pbData,       //in
  IN DWORD cbData,       //in
  IN BOOL fFinal         //in
);
 

Parameters

pvArg

The arguments specified by CMSG_STREAM_INFO.

pbData

A pointer to a block of processed data that is available to the application.

cbData

The size, in bytes, of the block of processed data at pbData.

fFinal

Specifies that the last block of data is being processed and that this is the last time the callback will be executed.