IDataAdviseHolder Interface

IID_IDataAdviseHolder

{00000110-0000-0000-C000-000000000046}

The IDataAdviseHolder interface contains methods that create and manage advisory connections between a data object and one or more advise sinks. Its methods are intended to be used to implement the advisory methods of IDataObject. IDataAdviseHolder is implemented on an advise holder object. Its methods establish and delete data advisory connections and send notification of change in data from a data object to an object that requires this notification, such as an OLE container, which must contain an advise sink.

Advise sinks are objects that require notification of change in the data the object contains and implement the IAdviseSink interface. Advise sinks are also usually associated with OLE compound document containers.

Your implementation of the advisory methods of IDataObject can call the methods in IDataAdviseHolder. The first time you receive a call to IDataObject::DAdvise, call the function CreateDataAdviseHolder to create an instance of the OLE-provided advise holder and get a pointer to its IDataAdviseHolder interface. Then, in implementing the IDataObject interface on the data object, you delegate implementations of the DAdvise, DUnadvise, and EnumDAdvise methods to the corresponding methods in IDataAdviseHolder.

When the data of interest to an advise sink actually changes, you call IDataAdviseHolder::SendOnDataChange from the 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.

Advise

FUNCTION IAdviseHolder_Advise ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pDataObject AS DWORD _

, BYREF pFetc AS FORMATETC _

, BYVAL advf AS DWORD _

, BYVAL pAdvise AS DWORD _

, BYREF pdwConnection AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IAdviseHolder_Advise (pthis, pDataObject, pFetc, advf, pAdvise, pdwConnection) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Unadvise

FUNCTION IAdviseHolder_Unadvise ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwConnection AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IAdviseHolder_Unadvise (pthis, dwConnection) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

EnumAdvise

FUNCTION IAdviseHolder_EnumAdvise ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppenumAdvise AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IAdviseHolder_EnumAdvise (pthis, ppenumAdvise) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SendOnDataChange

FUNCTION IAdviseHolder_SendOnDataChange ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pDataObject AS DWORD _

, BYVAL dwReserved AS DWORD _

, BYVAL advf AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IAdviseHolder_SendOnDataChange (pthis, pDataObject, dwReserved, advf) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION