The IOleObject Interface

As a container site implements IOleClientSite and IAdviseSink, these pointers must somehow find their way into the content object itself. We already know that the object will obtain an IAdviseSink through both IDataObject::DAdvise and IViewObject2::SetAdvise, but these connections only indicate that the container is interested in OnDataChange and OnViewChange notifications. Various members of the IOleObject interface, the presence of which marks an object as a content object, allow the container to pass its site pointers to the object:


interface IOleObject : IUnknown
{
HRESULT SetClientSite(IOleClientSite *pClientSite);
HRESULT GetClientSite(IOleClientSite **ppClientSite);

HRESULT SetHostNames(LPCOLESTR pszContainerApp
, LPCOLESTR pszContainerObj);

HRESULT Close(DWORD dwSaveOption);

HRESULT SetMoniker(DWORD dwWhichMoniker, IMoniker *pmk);
HRESULT GetMoniker(DWORD dwAssign, DWORD dwWhichMoniker
, IMoniker **ppmk);

HRESULT InitFromData(IDataObject *pDataObject, BOOL fCreation
, DWORD dwReserved);

HRESULT GetClipboardData(DWORD dwReserved
, IDataObject **ppDataObject);

HRESULT DoVerb(LONG iVerb, LPMSG lpmsg
, IOleClientSite *pActiveSite, LONG lindex
, HWND hwndParent, LPCRECT prc);

HRESULT EnumVerbs(IEnumOLEVERB **ppEnumOleVerb);
HRESULT Update(void);
HRESULT IsUpToDate(void);
HRESULT GetUserClassID(CLSID *pClsid);
HRESULT GetUserType(DWORD dwFormOfType, LPOLESTR *pszUserType);

HRESULT SetExtent(DWORD dwDrawAspect, SIZEL *psizel);
HRESULT GetExtent(DWORD dwDrawAspect, SIZEL *psizel);

HRESULT Advise(IAdviseSink *pAdvSink, DWORD *pdwConnection);
HRESULT Unadvise(DWORD dwConnection);
HRESULT EnumAdvise(IEnumSTATDATA **ppenumAdvise);

HRESULT GetMiscStatus(DWORD dwAspect, DWORD *pdwStatus);
HRESULT SetColorScheme(LOGPALETTE *pLogpal);
};

This interface rivals IMoniker for the distinction of having the most member functions around! It obviously has a lot of functionality, all of which has its purpose in the architecture of OLE Documents, as described in Table 17-1.

Member

Purpose

SetClientSite, GetClientSite

Provides the object with the container's IOleClientSite pointer or retrieves that pointer from the object.

SetHostNames

Provides the object with display names of its container and the compound document, which it displays in its caption bars and as menu items. (A caption bar is visible in Figure 17-5 on page 826.)

Close

Instructs the object to close, optionally saving changes or discarding them.

SetMoniker, GetMoniker

Provides the object with the moniker that names its location in the compound document or retrieves that moniker from the object. Used only for linking.

InitFromData

Instructs the object to perform a Paste operation from a given IDataObject. This allows the container to paste into an embedded object if it wants to.

GetClipboardData

Retrieves an IDataObject pointer from the object that encapsulates what the object would place on the clipboard if the user copied it directly.

DoVerb

Instructs the object to execute a verb.

EnumVerbs

Returns an enumerator for the OLEIVERB type. The container uses this to build a pop-up menu of available verbs.

Update

Ensures that the object is up-to-date. Embedded objects by themselves are always up-to-date unless they themselves contain other embeddings, in which case, this call is recursive to those other embeddings. Linked objects might be out-of-date if the source has changed since the last update.

IsUpToDate

Asks whether the object is up-to-date.

GetUserClassID

Returns the CLSID of the object that the user believes he or she is working with. This might change when emulation is being used.

GetUserType

Returns a user-readable string identifying the object type.

SetExtent, GetExtent

Instructs the object to change its size (reflected in its editing user interface) or retrieves the size of the object.

Advise, Unadvise,

Manages a connection between the object and

EnumAdvise

the site's IAdviseSink, specifically for the OnClose, OnSave, and OnRename members.

GetMiscStatus

Asks the object for its miscellaneous status flags from the enumeration OLEMISC, which describe small behavioral aspects.

SetColorScheme

Provides the object with the container's preferred color set. The object should use this set if it can. The color set is not a rendering palette but rather a set of preferred foreground, background, and fill colors.


Table 17-1

The IOleObject interface.

Much of what we'll be doing in the rest of this chapter and in those that follow will be exploring how this interface is used and where some of the information comes from. One source of such information is the registry, which holds a great deal of content object data.