The STGMEDIUM Structure

FORMATETC is merely half of the picture, of course, because it describes only the data format but says nothing about where the data actually is. This reference is provided by the STGMEDIUM (storage medium) structure, a generalization of the global-memory handle, which holds a mixture of different data references:

typedef struct tagSTGMEDIUM
    {
    DWORD tymed;
    union
        {
        HBITMAP       hBitmap;
        HMETAFILEPICT hMetaFilePict;
        HENHMETAFILE  hEnhMetaFile;
        HGLOBAL       hGlobal;
        LPOLESTR      lpszFileName;
        IStream      *pstm;
        IStorage     *pstg;
        } u;
    IUnknown *pUnkForRelease;
    } STGMEDIUM;

enum tagTYMED
    {
    TYMED_HGLOBAL   = 1,
    TYMED_FILE      = 2,
    TYMED_ISTREAM   = 4,
    TYMED_ISTORAGE  = 8,
    TYMED_GDI       = 16,
    TYMED_MFPICT    = 32,
    TYMED_ENHMF     = 64,
    TYMED_NULL      = 0
    }   TYMED;

The STGMEDIUM fields store the following information:

• tymed: An identifier for the type of medium used, taken from the TYMED enumeration: TYMED_HGLOBAL for global memory, TYMED_FILE for a traditional disk file, TYMED_ISTREAM for any stream object, TYMED_ISTORAGE for a storage object (it doesn't matter whether the storage medium is a compound file), TYMED_GDI for a Windows GDI object, TYMED_MFPICT for a METAFILEPICT structure in global memory, TYMED_ENHMF for an enhanced metafile in global memory, or TYMED_NULL for no medium (that is, no data).
• hBitmap, hMetafilePict, hEnhMetaFile, hGlobal, lpszFileName, pStg, pStm: A union that refers to the actual data. The meaningful element in the union is determined by tymed.
• pUnkForRelease: If non-NULL, identifies the pointer through which to call Release and free the data. This allows control over the ownership of the data, whereby a source can hand out the same data multiple times and track the number of consumer references to that data. See the following discussion of ReleaseStgMedium.

Consumers of data (that is, of a storage medium) are usually responsible for freeing the data after they have finished with it. The richness of STGMEDIUM would typically make this process quite complex—you should have the image of a big ugly switch(stm.tymed) statement floating in your head. Don't bother—OLE itself provides a single cleanup function named ReleaseStgMedium, which does all the right things according to the contents of the structure:

The ReleaseStgMedium API is exactly the reason why the tymed fields of both STGMEDIUM and FORMATETC differentiate between handles for global memory, GDI objects, and metafile pictures. Only with such precise identification can ReleaseStgMedium know how to perform cleanup correctly.

The Practical Impact of FORMATETC and STGMEDIUM

The FORMATETC and STGMEDIUM structures open up a wide range of possibilities in data transfer and solve a number of the key problems with previous protocols and data transfer techniques. The most fundamental benefit of these richer descriptions is that data no longer has to live in global memory. If the data is better suited to a disk file, use TYMED_FILE; if a storage or stream element is preferable, use TYMED_ISTORAGE or TYMED_ISTREAM. For example, persistent moniker data—which is easily written to and read from a stream (using OleSaveToStream and OleLoadFromStream)—is ideally exchanged in TYMED_ISTREAM. In fact, we'll see a standard clipboard format for this named "LinkSource" (CFSTR_LINKSOURCE). In addition, you can easily exchange marshaling data for any interface pointer, where the source would write the stream with CoMarshalInterface, and the consumer would call CoUnmarshalInterface.

Very large data sets that do not fit in memory can be kept on disk even during a data transfer operation, either in a traditional file or in an element of a compound file. Data that exists in a database need not be extracted until called for because the act of transferring an IDataObject pointer doesn't transfer any data, only the means to get at the data. If the data itself is stored in a disk file or in a storage or stream element, the consumer has the advantage of incremental access. Overall, these two structures vastly improve data transfer; any particular data can remain on its most optimal medium until the consumer chooses to copy it elsewhere.