This method establishes 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.
At a Glance
| Header file: | Oleidl.h |
| Windows CE versions: | 2.0 and later |
Syntax
HRESULT SetAdvise( DWORD dwAspect, DWORD advf,
IAdviseSink * pAdvSink );
Parameters
dwAspect
[in] Specifies the view for which the advisory connection is being set up. Valid values are taken from the enumeration DVASPECT.
advf
[in] Contains a group of flags for controlling the advisory connection. Valid values are from the enumeration ADVF. However, only the following ADVF values are relevant for this method:
| 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. |
For more information about the following values, see the ADVF enumeration.
Note that the ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData.
pAdvSink
[out] Pointer to the IAdviseSink 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 values described in the following table.
| Value | Description |
| 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::DAdvise 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::OnViewChange 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.