IDataAdviseHolder - OLE Programmer's Reference (ole.hlp)

IDataAdviseHolder

The IDataAdviseHolder interface creates and manages connections between an advise sink and a data object so that the advise sink can receive notification of changes in the data object. The IDataAdviseHolder interface also sends the notifications to the advise sinks it currently knows about when changes occur.

The object or container wishing to receive notification of changes in your data object creates an advise sink object with the IAdviseSink interface. The object or container application then calls your IDataObject::DAdvise method.

Typically, in your IDataObject implementation, you delegate handling of the advise sinks to the OLE-provided IDataAdviseHolder interface. This interface has methods to keep track of any IDataObject::DAdvise calls that your data object has received and to send notification back to the advise sinks as necessary when data has changed.

When to implement
Typically, you use the OLE-provided implementation of IDataAdviseHolder to simplify your implementation of the DAdvise, DUnadvise, and EnumDAdvise methods in the IDataObject interface.

When to use
Your implementation of IDataObject can call the methods in IDataAdviseHolder. The first time you receive a call to IDataObject::DAdvise, you call the API function CreateDataAdviseHolder to create an instance of the OLE-provided implementation of IDataAdviseHolder. Then, you delegate your IDataObject implementations of the DAdvise, DUnadvise, and EnumDAdvise methods to the corresponding methods in the OLE-provided IDataAdviseHolder.

When the data of interest to an advise sink actually changes, you call IDataAdviseHolder::SendOnDataChange from your data object to carry out the necessary notifications.

Methods in VTable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.

IDataAdviseHolder Methods	Description
Advise	Creates a connection between an advise sink and a data object so the advise sink can receive notification of change in the data object.
Unadvise	Destroys a notification connection previously set up with the Advise method.
EnumAdvise	Returns an object that can be used to enumerate the current advisory connections.
SendOnDataChange	Sends a change notification back to each advise sink that is currently being managed.