| C & C++ Programming | MFC Programming | Download | Site Index |


 

 

 

 

Supplementary Note For MFC Programming Module 27:

Interface Definitions

 

 

 

 

 

 

 

What do we have in this Module?

  1. IOleObject

    1. When to Implement

    2. When to Use

    3. Methods in VTable Order

  2. IDataObject

    1. When to Implement

    2. When to Use

    3. Methods in VTable Order

  3. IOleContainer

    1. When to Implement

    2. When to Use

    3. Methods in VTable Order

  4. IOleClientSite

    1. Methods in VTable Order

  5. IAdviseSink

    1. When to Implement

    2. When to Use

    3. Methods in Vtable Order

  6. IAdviseSink2

    1. When to Implement

    2. When to Use

    3. Methods in Vtable Order

  7. IViewObject2

    1. When to Implement

    2. When to Use

    3. Methods in Vtable Order

 

IOleObject

 

The IOleObject interface is the principal means by which an embedded object provides basic functionality to, and communicates with, its container. The interface is declared in oleidl.h.

 

When to Implement

 

An object application must implement this interface, along with at least IDataObject and IPersistStorage, for each type of embedded object that it supports. Although this interface contains 21 methods, only three are nontrivial to implement and must be fully implemented: DoVerb(), SetHostNames(), and Close(). Six of the methods provide optional functionality, which, if not desired, can be implemented to return E_NOTIMPL: SetExtent(), InitFromData(), GetClipboardData(), SetColorScheme(), SetMoniker(), and GetMoniker(). The latter two methods are useful mainly for enabling links to embedded objects.

 

When to Use

 

Call the methods of this interface to enable a container to communicate with an embedded object. A container must call DoVerb() to activate an embedded object, SetHostNames() to communicate the names of the container application and container document, and Close() to move an object from a running to a loaded state. Calls to all other methods are optional.

 

Methods in VTable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 1.

 

 

IOleObject Methods

Description

SetClientSite()

Informs object of its client site in container.

GetClientSite()

Retrieves object's client site.

SetHostNames()

Communicates names of container application and container document.

Close()

Moves object from running to loaded state.

SetMoniker()

Informs object of its moniker.

GetMoniker()

Retrieves object's moniker.

InitFromData()

Initializes embedded object from selected data.

GetClipboardData()

Retrieves a data transfer object from the Clipboard.

DoVerb()

Invokes object to perform one of its enumerated actions ("verbs").

EnumVerbs()

Enumerates actions ("verbs") for an object.

Update()

Updates an object.

IsUpToDate()

Checks if object is up to date.

GetUserClassID()

Returns an object's class identifier.

GetUserType()

Retrieves object's user-type name.

SetExtent()

Sets extent of object's display area.

GetExtent()

Retrieves extent of object's display area.

Advise()

Establishes advisory connection with object.

Unadvise()

Destroys advisory connection with object.

EnumAdvise()

Enumerates object's advisory connections.

GetMiscStatus()

Retrieves status of object.

SetColorScheme()

Recommends color scheme to object application.

 

 Table 2.

 

IDataObject

 

The IDataObject interface specifies methods that enable data transfer and notification of changes in data. Data transfer methods specify the format of the transferred data along with the medium through which the data is to be transferred. Optionally, the data can be rendered for a specific target device. In addition to methods for retrieving and storing data, the IDataObject interface specifies methods for enumerating available formats and managing connections to advisory sinks for handling change notifications.

The term "data object" is used to mean any object that supports an implementation of the IDataObject interface. Implementations vary, depending on what the data object is required to do; in some data objects, the implementation of certain methods not supported by the object could simply be the return of E_NOTIMPL. For example, some data objects do not allow callers to send them data. Other data objects do not support advisory connections and change notifications. However, for those data objects that do support change notifications, OLE provides an object called a data advise holder. An interface pointer to this holder is available through a call to the helper function CreateDataAdviseHolder(). A data object can have multiple connections, each with its own set of attributes. The OLE data advise holder simplifies the task of managing these connections and sending the appropriate notifications. The interface is declared in objidl.h.

 

When to Implement

 

Implement the IDataObject interface if you are developing a container or server application that is capable of transferring data. For example, if your application allows its data to be pasted or dropped into another application, you must implement the IDataObject interface. OLE compound document object servers that support objects that can be embedded or linked must implement IDataObject. OLE provides implementations in its default object handler and its cache.

 

When to Use

 

Any object that can receive data calls the methods in the IDataObject interface. When you call the data transfer methods in the IDataObject interface, you specify a format, a medium, and, optionally, a target device for which the data should be rendered. Objects, such as containers, that want to be notified through their advise sinks when the data in the data object changes call the IDataObject advisory methods to set up an advisory connection through which notifications can be sent.

 

Methods in VTable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 3.

 

 

IDataObject Methods

Description

GetData()

Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure.

GetDataHere()

Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure allocated by the caller.

QueryGetData()

Determines whether the data object is capable of rendering the data described in the FORMATETC structure.

GetCanonicalFormatEtc()

Provides a potentially different but logically equivalent FORMATETC structure.

SetData()

Provides the source data object with data described by a FORMATETC structure and an STGMEDIUM structure.

EnumFormatEtc()

Creates and returns a pointer to an object to enumerate the FORMATETC supported by the data object.

DAdvise()

Creates a connection between a data object and an advise sink so the advise sink can receive notifications of changes in the data object.

DUnadvise()

Destroys a notification previously set up with the DAdvise() method.

EnumDAdvise()

Creates and returns a pointer to an object to enumerate the current advisory connections.

 

 Table 4.

 

IOleContainer

 

The IOleContainer interface is used to enumerate objects in a compound document or lock a container in the running state. Container and object applications both implement this interface. The interface is declared in oleidl.h.

 

When to Implement

 

Applications that support links and links to embedded objects implement this interface to provide object enumeration, name parsing, and silent updates of link sources. Simple, non-linking containers do not need to implement IOleContainer if it is useful mainly to support links to embedded objects.

 

When to Use

 

Call IOleContainer to enumerate the objects in a compound document or to lock a container so that silent updates of link sources can occur without interruption until the container is explicitly released. Many applications inherit the functions of IOleContainer by implementing IOleItemContainer, which is used to bind item monikers.

 

Methods in VTable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 5.

 

IParseDisplayName

Method Description

ParseDisplayName()

Parses object's display name to form moniker.

 

 Table 6.

 

 

IOleContainer Methods

Description

EnumObjects()

Enumerates objects in a container.

LockContainer()

Keeps container running until explicitly released.

 

 Table 7.

 

IOleClientSite

 

The IOleClientSite interface is the primary means by which an embedded object obtains information about the location and extent of its display site, its moniker, its user interface, and other resources provided by its container. An object server calls IOleClientSite to request services from the container. A container must provide one instance of IOleClientSite for every compound-document object it contains. The interface is declared in oleidl.h.

 

Methods in VTable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 8.

 

IOleClientSite Methods

Description

SaveObject()

Saves embedded object.

GetMoniker()

Requests object's moniker.

GetContainer()

Requests pointer to object's container.

ShowObject()

Asks container to display object.

OnShowWindow()

Notifies container when object becomes visible or invisible.

RequestNewObjectLayout()

Asks container to resize display site.

 

 Table 9.

 

 

 

 

 

 

 

 

 

 

 

 

 

IAdviseSink

 

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. To simplify advisory notifications, OLE supplies implementations of the IDataAdviseHolder and IOleAdviseHolder, which keep track of advisory connections and send notifications to the proper sinks through pointers to their IAdviseSink interfaces. 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.

 

 Table 10.

 

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. The interface is declared in objidl.h.

 

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. 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 in Vtable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 11.

 

IAdviseSink Methods

Description

OnDataChange()

Advises that data has changed.

OnViewChange()

Advises that view of object has changed.

OnRename()

Advises that name of object has changed.

OnSave()

Advises that object has been saved to disk.

OnClose()

Advises that object has been closed.

 

 Table 12.

 

IAdviseSink2

 

The IAdviseSink2 interface is an extension of IAdviseSink, adding the method OnLinkSrcChange() to the contract to handle a change in the moniker of a linked object. This avoids overloading the implementation IAdviseSink::OnRename to handle the renaming of both embedded objects and linked objects. In applications where different blocks of code might execute depending on which of these two similar events has occurred, using the same method for both events complicates testing and debugging. The interface is declared in objidl.h.

 

When to Implement

 

If your application supports links, you should definitely implement IAdviseSink2. Even if your application does not support links, it may do so in future releases. In general, your code would implement just IAdviseSink2, which, because of contract inheritance, must include implementations of all of the IAdviseSink methods, along with the single additional method of IAdviseSink2.

 

When to Use

 

When a link source is renamed, the link object should notify its container by calling IAdviseSink::OnLinkSrcChange. If you are using the default handler, containing the OLE link object, you can still have both embedded and linked objects call IAdviseSink::OnRename, but for linked objects, the OLE link object maps the notification to IAdviseSink2::OnLinkSrcChange.

 

Methods in Vtable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 13.

 

IAdviseSink Methods

Description

OnDataChange()

Advises that data has changed.

OnViewChange()

Advises that view of object has changed.

OnRename()

Advises that name of object has changed.

OnSave()

Advises that object has been saved to disk.

OnClose()

Advises that object has been closed.

 

 Table 14.

 

IAdviseSink2 Method

Description

OnLinkSrcChange()

Advises that link source has changed.

 

 Table 15.

 

IViewObject2

 

The IViewObject2 interface is an extension to the IViewObject interface which returns the size of the drawing for a given view of an object. You can prevent the object from being run if it isn't already running by calling this method instead of IOleObject::GetExtent. Like the IViewObject interface, IViewObject2 cannot be marshaled to another process. This is because device contexts are only effective in the context of one process. The OLE-provided default implementation provides the size of the object in the cache. The interface is declared in oleidl.h.

 

When to Implement

 

Object handlers and in-process servers that manage their own presentations implement IViewObject2 for use by compound document containers.

 

When to Use

 

A container application or object handler calls the GetExtent() method in the IViewObject2 interface to get the object's size from its cache.

 

Methods in Vtable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

 Table 16.

 

IViewObject Methods

Description

Draw()

Draws a representation of the object onto a device context.

GetColorSet()

Returns the logical palette the object uses for drawing.

Freeze()

Freezes the drawn representation of an object so it will not change until a subsequent Unfreeze().

Unfreeze()

Unfreezes the drawn representation of an object.

SetAdvise()

Sets up a connection between the view object and an advise sink so that the advise sink can receive notifications of changes in the view object.

GetAdvise()

Returns the information on the most recent SetAdvise().

 

 Table 17.

 

IViewObject2 Method

Description

GetExtent()

Returns the size of the view object from the cache.

 

 Table 18.

 

 

 

 

 

 

 


| C & C++ Programming | MFC Programming | Download | Site Index |