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.