ADVF

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

These enumeration contains values used by a container object to specify the requested behavior when setting up an advise sink or a caching connection with an object. These values have different meanings, depending on the type of connection in which they are used, and each interface uses its own subset of the flags.

Syntax

typedef enum tagADVF { 
  ADVF_NODATA = 1, 
  ADVF_PRIMEFIRST = 2, 
  ADVF_ONLYONCE = 4, 
  ADVFCACHE_NOHANDLER = 8, 
  ADVFCACHE_FORCEBUILTIN = 16, 
  ADVFCACHE_ONSAVE = 32, 
  ADVF_DATAONSTOP = 64 
} ADVF; 

Elements

• ADVF_NODATA
  For data advisory connections IDataObject::DAdvise this flag requests the data object not to send data when it calls IAdviseSink::OnDataChange.

  The recipient of the change notification can later request the data by calling IDataObject::GetData.

  The data object can honor the request by passing TYMED_NULL in the STGMEDIUM parameter, or it can provide the data anyway. For example, the data object might have multiple advisory connections, not all of which specified ADVF_NODATA, in which case the object might send the same notification to all connections.

  Regardless of the container's request, its IAdviseSink implementation must check the STGMEDIUM parameter because it is responsible for releasing the medium if it is not TYMED_NULL.

  ADVF_NODATA is not a valid flag for view advisory connections, IViewObject::SetAdvise, and it returns E_INVALIDARG.

• ADVF_PRIMEFIRST
  Requests that the object not wait for the data or view to change before making an initial call to IAdviseSink::OnDataChange for data or view advisory connections or updating the cache for cache connections.

  Used with ADVF_ONLYONCE, this parameter provides an asynchronous IDataObject::GetData call.

• ADVF_ONLYONCE
  Requests that the object make only one change notification or cache update before deleting the connection.

  ADVF_ONLYONCE automatically deletes the advisory connection after sending one data or view notification. The advisory sink receives only one IAdviseSink call.

  A nonzero connection identifier is returned if the connection is established, so the caller can use it to delete the connection prior to the first change notification.

  For data change notifications, the combination of ADVF_ONLYONCE and ADVF_PRIMEFIRST provides, in effect, an asynchronous IDataObject::GetData call.

  When used with caching, ADVF_ONLYONCE updates the cache one time only, on receipt of the first OnDataChange notification. 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_DATAONSTOP
  For data advisory connections, assures accessibility to data. This flag indicates that when the data object is closing, it should call IAdviseSink::OnDataChange, providing data with the call.

  Typically, this value is used in combination with ADVF_NODATA. Without this value, by the time an OnDataChange call without data reaches the sink, the source might have completed its shutdown and the data might not be accessible.

  Sinks that specify this value should accept data provided in OnDataChange if it is being passed, because they may not get another chance to retrieve it.

  For cache connections, this flag indicates that the object should update the cache as part of object closure.

  ADVF_DATAONSTOP is not a valid flag for view advisory connections.

• ADVFCACHE_NOHANDLER
  Synonym for ADVFCACHE_FORCEBUILTIN, which is used more often.

• ADVFCACHE_FORCEBUILTIN
  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.

  This value is not a valid flag for data or view advisory connections.

  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.

• ADVFCACHE_ONSAVE
  For cache connections, this flag updates the cached representation only when the object containing the cache is saved.

  The cache is also updated when the OLE object transitions from the running state back to the loaded state (because a subsequent save operation would require rerunning the object).

  This value is not a valid flag for data or view advisory connections.

Remarks

For a data or view advisory connection, the container uses the ADVF constants when setting up a connection between an IAdviseSink instance and either an IDataObject or IViewObject instance. These connections are set up using the IDataObject::DAdvise, IDataAdviseHolder::Advise, or IViewObject::SetAdvise methods.

These constants are also used in the advf member of the STATDATA structure.

This structure is used by IEnumSTATDATA to describe the enumerated connections, and the advf member indicates the flags that were specified when the advisory or cache connection was established.

When STATDATA is used for an IOleObject::EnumAdvise enumerator, the advf member is indeterminate.

Requirements

See Also

Reference

IAdviseSink
IEnumSTATDATA
IViewObject
IOleObject::EnumAdvise
STGMEDIUM