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 an advisory connection between an OLE object and the calling object's advise sink, through which the calling object receives notification when the compound document object is renamed, save, or closed.

Syntax 

HRESULT Advise( 
  IAdviseSink* 
pAdvSink, 
  DWORD* 
pdwConnection
);

Parameters

pAdvSink

[in] Pointer to the IAdviseSinkinterface on the advisory sink that should be informed of changes.

pdwConnection

[out] Pointer to a token that can be passed to the IOleAdviseHolder::Unadvisemethod to delete the advisory connection.

The calling object is responsible for calling both IUnknown::AddRefand IUnknown::Releaseon this pointer.

Return Value

This method supports the standard return value E_INVALIDARG, as well as S_OK, which indicates that advisory connections set up successfully.

Remarks

Containers, object handlers, and link objects create advise sinks to receive notification of changes in compound-document objects of interest, such as embedded or linked objects.

OLE objects of interest to these objects must implement the IOleObjectinterface, which includes several advisory methods, including IOleObject::Advise.

A call to this method must set up an advisory connection with any advise sink that calls it, and maintain each connection until it is closed. It must be able to handle more than one advisory connection at a time.

IOleAdviseHolder::Adviseis intended to be used to simplify the implementation of IOleObject::Advise.

You can get a pointer to the OLE implementation of IOleAdviseHolderby calling CreateOleAdviseHolder, and then, to implement IOleObject::Advise, delegate the call to IOleAdviseHolder::Advise.

Other IOleAdviseHoldermethods are intended to implement other IOleObjectadvisory methods.

If the attempt to establish an advisory connection is successful, the object receiving the call returns a nonzero value through pdwConnection. If the attempt fails, the object returns a zero.

To delete an advisory connection, the object with the advise sink passes this nonzero token back to the object by calling IOleAdviseHolder::Unadvise.

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