Using Buffered Streams

When the IStream interface is used, several different functions can be called to produce the stream. Generally, performance is improved by using a buffered stream. The MAPI OpenStreamOnFile function produces a stream that is not buffered, so Microsoft Exchange Server provides the OpenVirtualStreamOnFile and OpenVirtualStreamOnProperty functions, which provide buffered streams.

    To transfer data using buffered streams

• Use the Virtual Stream on File (VSOF) mechanism, which is obtained with a call to the OpenVirtualStreamOnFile function. This is a buffered version of the MAPI OpenStreamOnFile function and is recommended in most cases.
• Use the Virtual Stream on Property (VSOP) mechanism, which is obtained with a call to the OpenVirtualStreamOnProperty function. This function creates a buffered stream and is used for retrieving and setting binary and string properties that may be too large to use with the IMAPIProp::GetProps and SetProps methods.
• Use the MAPI OpenStreamOnFile function by passing in flags to control the creation of the stream object. This function call returns a stream pointer and a Stream object. In most cases, performance is improved by using the OpenVirtualStreamOnFile function.
• Use the Win32 IStream interface functions. This interface is used by all the preceding functions to return a Stream object and a pointer which should be used for memory allocation and deallocation. To free the Stream object, the application or provider must call the OLE IStream::Release method.

All of the procedures listed above use OLE streams. Win32, MAPI, and the Microsoft Exchange Server SDK all contain functions for working with OLE streams. For information about the IStream interface, see the Platform SDK. For more information about the MAPI OpenStreamOnFile method, see the MAPI Programmer’s Reference.

For more information about OLE, see Inside OLE 2 by Kraig Brochschmidt (Microsoft Press).

Streams can be used to work with rich text format (RTF) properties. For more information, see Saving ANSI Text as a Message Property in RTF, Saving RTF Text as a Message Property in RTF, and Retrieving ANSI Text from a Message Property in RTF.