IOleCache::Cache - OLE Programmer's Reference (ole.hlp)

IOleCache::Cache

Specifies the format and other data to be cached inside an embedded object.

HRESULT Cache(

FORMATETC * pFormatetc,	//Points to the data and formats to be cached
DWORD advf,	//Flags that control the caching
DWORD * pdwConnection	//Identifies the connection for future calls to uncache
);

Parameters
pFormatetc

[in]Points to the format and other data to be cached. View caching is specified by passing a zero clipboard format in pFormatetc.

advf

[in]Contains a group of flags that control the caching. Valid values can be derived by using an OR operation on the values in the ADVF enumeration. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values and how they control caching. See the ADVF enumeration for a more detailed description.

ADVF Value	Description
ADVF_NODATA	Asks the data object to avoid sending data with the notifications. This flag is a way to override the default behavior of sending data with the notification. Typically, this flag is used when the iconic aspect of an object is cached. The cache can then be updated explicitly by calling IOleCache::SetData, IDataObject::SetData, or IOleCache2::UpdateCache.
ADVF_ONLYONCE	Causes the advisory connection to be destroyed after the first notification is sent.
ADVF_PRIMEFIRST	Causes an initial notification to be sent regardless of whether data has changed from its current state.
ADVFCACHE_NOHANDLER	Synonym for ADVFCACHE_FORCEBUILTIN.
ADVFCACHE_FORCEBUILTIN	For cache connections, this flag caches data that requires only code shipped with OLE or the underlying operating system to be present in order to produce it with IDataObject::GetData or IViewObject::Draw. By specifying this value, the container can ensure that the data can be retrieved even when the object or handler code is not available. This value is used by DLL object applications and object handlers that perform the drawing of their objects. ADVFCACHE_FORCEBUILTIN instructs OLE to cache presentation data to ensure that there is a presentation in the cache.
ADVFCACHE_ONSAVE	Updates the cached representation only when the object containing the cache is saved. The cache is also updated when the OLE object changes from the running state back to the loaded state (because a subsequent save operation would require running the object again).

pdwConnection
[out]Points to the location of a returned token that identifies this connection and can later be used to turn caching off (by passing it to IOleCache::Uncache). If this value is zero, the connection was not established. The OLE-provided implementation uses nonzero numbers for connection identifiers.

Return Values
S_OK

Requested data or view successfully cached.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Ran out of memory.

E_UNEXPECTED

An unexpected error occurred.

CACHE_S_FORMATETC_NOTSUPPORTED

Indicates the cache was created, but the object application does not support the specified format. Cache creation succeeds even if the format is not supported, allowing the caller to fill the cache. If, however, the caller does not need to keep the cache, call IOleCache::UnCache.

CACHE_S_SAMECACHE

Indicates a cache already exists for the FORMATETC passed to IOleCache::Cache. In this case, the new advise flags are assigned to the cache, and the previously assigned connection identifier is returned.

DV_E_LINDEX

Invalid value for lindex; currently only -1 is supported.

DV_E_TYMED

The value is not valid for pFormatetc->tymed.

DV_E_DVASPECT

The value is not valid for pFormatetc->dwAspect.

DV_E_CLIPFORMAT

The value is not valid for pFormatetc->cfFormat.

CO_E_NOTINITIALIZED

The cache's storage is not initialized.

DV_E_DVTARGETDEVICE

The value is not valid for pFormatetc->ptd.

OLE_E_STATIC

The cache is for static object and it already has a cache node.

Comments
IOleCache::Cache can specify either data caching by passing a valid data format in pFormatetc or view (presentation) caching by passing a zero data format in pFormatetc as follows:
pFormatetc->cfFormat == 0

With view caching, the cache object itself decides on the format to cache.

A custom object handler can choose not to store data in a given format. Instead, it can synthesize it on demand when requested.

The advf value of ADVFCACHE_FORCEBUILTIN ensures that presentation data can be retrieved after the container document has been moved where the object application or object handler is not available.

When an IOleCache::Cache call is made to cache either CF_DIB or CF_BITMAP, the OLE cache implementation will implicitly cache the other format. Thus, the enumerator (IOleCache::EnumCache) will have two entries (CF_DIB and CF_BITMAP) for the one cached format. Both of these entries have the same connection ID, so one call to IOleCache::Uncache will remove both. CF_DIB and CFBITMAP may also be explicitly cached separately (by two calls to IOleCache::Cache).