IOleAdviseHolder::Advise method

Establishes an advisory connection between an OLE object and the calling object's advise sink. Through that sink, the calling object can receive notification when the OLE object is renamed, saved, or closed.

Syntax


HRESULT Advise(
  [in]  IAdviseSink *pAdvise,
  [out] DWORD       *pdwConnection
);

Parameters

pAdvise [in]

A pointer to the IAdviseSink interface on the advisory sink that should be informed of changes.

pdwConnection [out]

A pointer to a token that can be passed to the IOleAdviseHolder::Unadvise method to delete the advisory connection. The calling object is responsible for calling both IUnknown::AddRef and IUnknown::Release on this pointer.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return codeDescription
E_INVALIDARG

The supplied IAdviseSink interface pointer is invalid.

 

Remarks

Containers, object handlers, and link objects all 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 IOleObject interface, 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::Advise is intended to be used to simplify the implementation of IOleObject::Advise. You can get a pointer to the OLE implementation of IOleAdviseHolder by calling CreateOleAdviseHolder, and then, to implement IOleObject::Advise, just delegate the call to IOleAdviseHolder::Advise. Other IOleAdviseHolder methods are intended to implement other IOleObject advisory 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::Advise.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OleIdl.h

IDL

OleIdl.Idl

IID

IID_IOleAdviseHolder is defined as 00000111-0000-0000-C000-000000000046

See also

IOleAdviseHolder
IOleAdviseHolder::EnumAdvise
IOleAdviseHolder::Unadvise
IOleObject::Advise

 

 

Show: