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.
||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
||Causes an initial notification to be sent regardless of whether data has
changed from its current state.
||Synonym for 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.
||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.
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.
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
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.
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
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages