The IOleCache2 Interface

The IOleCache2 interface is the interface a client uses to control what actually gets cached. The IOleCache interface expresses the basic functionality, with IOleCache2 adding the capability of the client to update any cached data that is maintained. The following shows the definitions of the interfaces; the member functions of both interfaces are described in Table 11-4.

interface IOleCache : IUnknown
    { 
    HRESULT Cache(FORMATETC *pFE, DWORD dwAdvf, DWORD *pdwConnection);
    HRESULT Uncache(DWORD dwConnection);
    HRESULT EnumCache(IEnumSTATDATA **ppEnum);
    HRESULT InitCache(IDataObject *pIDataObject);
    HRESULT SetData(FORMATETC *pFE, STGMEDIUM *pSTM, BOOL fRelease);
    }; 

interface IOleCache2 : IOleCache
    {
    HRESULT UpdateCache(IDataObject *pIDataObject, DWORD dwgrfUpdf
        , void **pvReserved);
    HRESULT DiscardCache(DWORD dwDiscardOptions);
    }

IOleCache and IOleCache2 Member Function		Behavior
Cache		Adds the given format to the list of those cached. If FORMATETC::cfFormat is 0, all formats are cached. If CF_BITMAP is cached, the cache will also save CF_DIB and vice versa. The ADVF_* flags specify how the cache relates to a remote object. (See "The IOleCacheControl Interface" later in this chapter.) Cache returns a connection key for use with Uncache.
Uncache		Removes a format from the list to cache by using the key returned from Cache and releases any data of this format from the cache. Also terminates any connection to a local or remote object for the format.
EnumCache		Enumerates the present cached formats (not the data) through IEnumSTATDATA, as described for IDataObject::EnumDAdvise in Chapter 10. The pAdvSink field of the enumerated structures holds IAdviseSink pointers to sinks implemented in the cache that are connected to a local or remote object.
InitCache		Fills the cache with all the data available from a data object. This is easily implemented by enumerating the formats in the data object, calling IDataObject::GetData for each and then saving each one by calling IOleCache2::SetData.
SetData		Saves a specific piece of data in the cache. The fRelease flag acts like the same argument to IDataObject::SetData.
UpdateCache (IOleCache2 only)	Updates the data in the cache in bulk from the data available in a data object according to dwgrfUpdf. These flags are fully described in the OLE Programmer's Reference.
DiscardCache (IOleCache2 only)	Flushes any data from memory but does not delete it from the cache. Only information about available formats remains in memory. The dwDiscardOptions flag allows the caller to save any data that has been changed or to simply discard it.

Table 11-4

Behavior of the data cache's IOleCache2 interface.

Basically, the data cache keeps data on disk as long as possible, bringing it into memory only when necessary. The IOleCache2::Cache and IOleCache2::Uncache members control the information list that determines what is available. Other than that, InitCache, SetData, UpdateCache, and DiscardCache do nothing more than control what will actually be saved, and EnumCache describes what is there.

Using the data cache, you can save any number of pieces of data that you want as long as each has a different FORMATETC (except for tymed). This means you can save CF_METAFILEPICT data for any number of aspects and for any number of target devices per aspect. You can also save an object's presentations for any number of printers, allowing the client to fully control the presentations and output quality that will be available when the object is not available itself. This is a tremendous benefit for OLE Documents because a client can save a cache for each embedded or linked object so that the cached presentations travel with the document wherever it goes. Even when the object's code is unavailable or when the source of linked data is unavailable, the client will still be able to view and print appropriate images.