IViewObject::SetAdvise N4Q1RC

Sets up a connection between the view object and an advise sink so that the advise sink can be notified about changes in the object s view.

HRESULT SetAdvise(

DWORD dwAspect,	//View for which notification is being requested
DWORD advf,	//Information about the advise sink
IAdviseSink * pAdvSink	//Pointer to the advise sink that is to receive change notifications
);

Parameters

dwAspect

[in] View for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT1BLGLB9. See the DVASPECT enumeration for more information.

advf

[in] Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVFJW0._0. However, only some of the possible ADVF values are relevant for this method. The following table briefly describes the relevant values. See the ADVF enumeration for a more detailed description.

ADVF Value	Description
ADVF_ONLYONCE	Causes the advisory connection to be destroyed after the first notification is sent.
ADVF_PRIMEFIRST	Causes an initial notification to be sent regardless of whether data has changed from its current state.

Note that the ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData81EL5_.

pAdvSink

[out] Pointer to the IAdviseSink3F9W.KC interface on the advisory sink that is to be informed of changes. A NULL value deletes any existing advisory connection.

Return Values

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The advisory connection was successfully established.

OLE_E_ADVISENOTSUPPORTED

Advisory notifications are not supported.

DV_E_DVASPECT

Invalid value for dwAspect.

Remarks

A container application that is requesting a draw operation on a view object can also register with the IViewObject::SetAdvise method to be notified when the presentation of the view object changes. To find out about when an object s underlying data changes, you must call IDataObject::DAdvise38JBOZP separately.

To remove an existing advisory connection, call the IViewObject::SetAdvise method with pAdvSink set to NULL.

If the view object changes, a call is made to the appropriate advise sink through its IAdviseSink::OnViewChange11_6YI7 method.

At any time, a given view object can support only one advisory connection. Therefore, when IViewObject::SetAdvise is called and the view object is already holding on to an advise sink pointer, OLE releases the existing pointer before the new one is registered.