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


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



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


[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
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.
Causes the advisory connection to be destroyed after the first notification is sent.
Causes an initial notification to be sent regardless of whether data has changed from its current state.
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.
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).


[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


Requested data or view successfully cached.


One or more arguments are invalid.


Ran out of memory.


An unexpected error occurred.


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.


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.


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


The value is not valid for pFormatetc->tymed.


The value is not valid for pFormatetc->dwAspect.


The value is not valid for pFormatetc->cfFormat.


The cache's storage is not initialized.


The value is not valid for pFormatetc->ptd.


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


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

See Also

ADVF, IOleCache::Uncache

Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database