IOleCache::Cache
Specifies the
format and other data to be cached inside an embedded object.
HRESULT Cache(
|
FORMATETC
* pFormatetc, |
//Pointer to the format and data to be cached |
|
DWORD advf, |
//Flags that control the caching |
|
DWORD * pdwConnection |
//Pointer to the connection for future calls to
uncache |
|
); |
|
Parameters
pFormatetc
[in] Pointer
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. When used in this context, for a
cache, these values have specific meanings, which are outlined in the Remarks.
Refer to the ADVF enumeration for a more detailed description.
pdwConnection
[out] Pointer
to a returned DWORD 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
This method
supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and
E_UNEXPECTED, as well as the following:
S_OK
Requested
data or view successfully cached.
CACHE_S_FORMATETC_NOTSUPPORTED
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
A cache
already exists for the FORMATETC passed to IOleCache::Uncache. 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 a static object and it already has a cache node.
Remarks
IOleCache::Cache can specify either data caching or view
(presentation) caching. To specify data caching, a valid data format must be
passed in pFormatetc. For view caching, the cache object itself decides
on the format to cache, so a caller would pass a zero data format in pFormatetc
as follows:
pFormatetc->cfFormat == 0
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 specifies a member of the ADVF enumeration. When one of these values (or an OR d
combination of more than one value) is used in this context, these values mean
the following:
|
ADVF Value |
Description |
|
ADVF_NODATA |
The cache
is not to be updated by changes made to the running object. Instead, the
container will update the cache by explicitly calling IOleCache::SetData,
IDataObject::SetData,
or IOleCache2::UpdateCache. This flag is usually used when the iconic
aspect of an object is being cached. |
|
ADVF_ONLYONCE |
Update the
cache one time only. After the update is complete, the advisory connection
between the object and the cache is disconnected. The source object for the
advisory connection calls the IAdviseSink::Release method. |
|
ADVF_PRIMEFIRST |
The object
is not to wait for the data or view to change before updating the cache. OR d
with ADVF_ONLYONCE, this parameter provides an asynchronous GetData
call. |
|
ADVFCACHE_NOHANDLER |
Synonym for
ADVFCACHE_FORCEBUILTIN. |
|
ADVFCACHE_FORCEBUILTIN |
Used by DLL
object applications and object handlers that draw their objects to cache
presentation data to ensure that there is a presentation in the cache. This
ensures that the data can be retrieved even when the object or handler code
is not available. |
|
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). |
See Also