IDataObject::DAdvise

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method is called by an object supporting an advise sink to create a connection between a data object and the advise sink. This enables the advise sink to be notified of changes in the data of the object.

Syntax

HRESULT DAdvise(
  FORMATETC* pFormatetc,
  DWORD advf,
  IAdviseSink* pAdvSink,
  DWORD* pdwConnection
);

Parameters

• pFormatetc
  [in] Pointer to a FORMATETC structure that defines the format, target device, aspect, and medium that will be used for future notifications.

  For example, one sink may want to know only when the bitmap representation of the data in the data object changes. Another sink may be interested in only the metafile format of the same object.

  Each advise sink is notified when the data of interest changes. This data is passed back to the advise sink when notification occurs.

• advf
  [in] DWORD that specifies a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only some of the possible ADVF values are relevant for this method. See the Remarks section for more information.

• pAdvSink
  Pointer to the IAdviseSink interface on the advisory sink that will receive the change notification.

• pdwConnection
  [out] Pointer to a DWORD token that identifies this connection.

  You can use this token later to delete the advisory connection by passing it to IDataObject::DUnadvise.

  If this value is zero, the connection was not established.

Return Value

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY.

The following table shows the additional return values for this method.

Remarks

The following table describes the relevant values for the advf parameter.

IDataObject::DAdvise creates a change notification connection between a data object and the caller. The caller provides an advisory sink to which the notifications can be sent when the object's data changes.

Objects used simply for data transfer typically do not support advisory notifications and return OLE_E_ADVISENOTSUPPORTED from IDataObject::DAdvise.

The object supporting the advise sink calls IDataObject::DAdvise to set up the connection, specifying the format, aspect, medium, and target device of interest in the FORMATETC structure passed in.

If the data object does not support one or more of the requested attributes or the sending of notifications at all, it can refuse the connection by returning OLE_E_ADVISENOTSUPPORTED.

Containers of linked objects can set up advisory connections directly with the bound link source or indirectly through the standard OLE link object that manages the connection. Connections set up with the bound link source are not automatically deleted.

The container must explicitly call IDataObject::DUnAdvise on the bound link source to delete an advisory connection. The OLE link object, manipulated through the IOleLink interface, is implemented in the default handler.

Connections set up through the OLE link object are destroyed when the link object is deleted.

The OLE default link object creates a wildcard advise with the link source so OLE can maintain the time of last change. This advise is specifically used to note the time that anything changed.

OLE ignores all data formats that may have changed, noting only the time of last change.

To allow wildcard advises, set the FORMATETC members as shown in the following code example before calling IDataObject::DAdvise.

cf == 0;

ptd == NULL;

dwAspect == -1;

lindex == -1

tymed == -1;

The advise flags should also include ADVF_NODATA. Wildcard advises from OLE should always be accepted by applications.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

See Also

Reference

IAdviseSink
ADVF
FORMATETC
STGMEDIUM