Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

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 ADVFvalues 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 ADVFenumeration.

ADVF_ONLYONCE and ADVF_PRIMEFIRST can be combined to provide an asynchronous call to IDataObject::GetData.

pAdvSink

[out] Pointer to the IAdviseSinkinterface on the advisory sink that is to be informed of changes.

A NULL value deletes any existing advisory connection.

Return Value

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the values in the following table.

Value Description

S_OK

The advisory connection was 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 SetAdvisemethod 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::DAdviseseparately.

To remove an existing advisory connection, call the SetAdvisemethod with pAdvSinkset to NULL.

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

At any time, a given view object can support only one advisory connection. Therefore, when SetAdviseis 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.

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

Requirements

Header Oleidl.h, oleidl.idl
Library oleaut32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also