Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This structure is used to enable stream data processing rather than single block processing. Stream processing is most often used when processing large messages. Stream-process messages can originate from any serialized source such as a file on a hard disk, a server, or a CD ROM.

This structure is passed to CryptMsgOpenToEncodeand CryptMsgOpenToDecode.

Syntax 

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

Members

cbContent

Specifies the size of the content in bytes. Normal Distinguised Encoding Rules (DER) encoding is used unless a 0xFFFFFFFF is passed indicating that the application is not specifying the content length. This forces the use of indefinite-length Basic Encoding Rules (BER) encoding.

pfnStreamOutput

Address of a callback function used to read from and write data to a disk when processing large messages.

The callback function must have the following signature and parameters:

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

Parameter Description

pvArg

The arguments that are specified by CMSG_STREAM_INFO.

pbData

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

cbData

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.
pvArg

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

Remarks

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

The input message to be processed as a stream feeds into CryptMsgUpdateone 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 pfnStreamOutputmember.

No assumptions can be made about the block size of the output data because the size can vary for several reasons such as the jitter in output block size caused by the block size for the encryption algorithm when processing an enveloped message, or when blocks that contain the message header and the SignerInfo as defined by PKCS # 7 are processed.

The size of the output block is passed to the callback function in its cbData parameter The use of output data is determined in the calling application. Typically, output from stream processing will not be persisted in memory as a whole due to memory limitations, but will be serialized to a disk or server file.

Requirements

Header wincrypt.h
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also