IAdviseSink:IUnknown
This interface enables containers and other objects to receive notifications of data, view, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call's return.
The IAdviseSink interface enables containers and other objects to receive notifications of data changes, view changes, and compound-document changes occurring in objects of interest. Container applications, for example, require such notifications to keep cached presentations of their linked and embedded objects up-to-date. Calls to IAdviseSink methods are asynchronous, so the call is sent and then the next instruction is executed without waiting for the call's return.
For an advisory connection to exist, the object that is to receive notifications must implement IAdviseSink, and the objects in which it is interested must implement IOleObject::Advise and IDataObject::DAdvise. In-process objects and handlers may also implement IViewObject::SetAdvise. Objects implementing IOleObject must support all reasonable advisory methods. IViewObject (and its advisory methods) is implemented in the default handler.
As shown in the following table, an object that has implemented an advise sink registers its interest in receiving certain types of notifications by calling the appropriate method.
| Call this method | To register for these notifications |
|---|---|
| IOleObject::Advise | When a document is saved, closed, or renamed. |
| IDataObject::DAdvise | When a document's data changes. |
| IViewObject::SetAdvise | When a document's presentation changes. |
When an event occurs that applies to a registered notification type, the object application calls the appropriate IAdviseSink method. For example, when an embedded object closes, it calls the IAdviseSink::OnClose method to notify its container. These notifications are asynchronous, occurring after the events that trigger them.
When to Implement
Objects, such as container applications and compound documents, implement IAdviseSink to receive notification of changes in data, presentation, name, or state of their linked and embedded objects. Implementers register for one or more types of notification, depending on their needs.
Notifications of changes to an embedded object originate in the server and flow to the container by way of the object handler. If the object is a linked object, the OLE link object intercepts the notifications from the object handler and notifies the container directly. All containers, the object handler, and the OLE link object register for OLE notifications. The typical container also registers for view notifications. Data notifications are usually sent to the OLE link object and object handler.
When to Use
Servers call the methods of IAdviseSink to notify objects with which they have an advisory connection of changes in an object's data, view, name, or state.
**Note **OLE does not permit synchronous calls in the implementation of asynchronous methods, so you cannot make synchronous calls within any of the IAdviseSink interface's methods. For example, an implementation of IAdviseSink::OnDataChange cannot contain a call to IDataObject::GetData.
Methods
The following table shows the methods for this interface in alphabetical order. Like all COM interfaces, this interface inherits the methods for the IUnknown interface.
| Method | Description |
|---|---|
| IAdviseSink::OnClose | This method advises the sink that data has changed. |
| IAdviseSink::OnDataChange | This method advises the sink that an object view has changed. |
| IAdviseSink::OnRename | This method advises the sink that an object name has changed. |
| IAdviseSink::OnSave | This method advises the sink that an object has been saved to disk. |
| IAdviseSink::OnViewChange | This method advises the sink that an object has been closed. |
Remarks
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Requirements
OS Versions: Windows CE 2.0 and later.
Header: Objidl.h, Objidl.idl
Link Library: Oleaut32.lib, Uuid.lib.
See Also
OLE Interfaces | IDataObject::DAdvise | IDataObject::GetData | IOleObject | IOleObject::Advise | IUnknown | IViewObject | IViewObject::SetAdvise
Last updated on Wednesday, April 13, 2005
© 2005 Microsoft Corporation. All rights reserved.