An Interface Summary

Following is a summary of the important OLE interfaces we'll be using in the remaining examples in this chapter. The function lists are by no means complete, nor are the parameter lists. See MSDN Online Help or Brockschmidt's book for the complete specifications.

The IOleObject Interface

Embedded components implement this interface. The client site maintains an IOleObject pointer to an embedded object.

HRESULT Advise(IAdviseSink* AdvSink, DWORD* pdwConnection);

The handler calls this function to establish one of the two advisory connections from the component to the handler. The component usually implements Advise with an OLE advise holder object, which can manage multiple advisory connections.

HRESULT Close(DWORD dwSaveOption);

The container calls Close to terminate the component application but to leave the object in the loaded state. Containers call this function when the user clicks outside an in-place-active component's window. Components that support in-place activation should clean up and terminate.

HRESULT DoVerb(LONG iVerb, …, IOleClientSite* pActiveSite, …);

Components support numeric verbs as defined in the Registry. A sound component might support a "Play" verb, for example. Embedded components should support the OLEIVERB_SHOW verb, which instructs the object to show itself for editing or viewing. If the component supports in-place activation, this verb starts the Visual Editing process; otherwise, it starts the component program in a window separate from that of its container. The OLEIVERB_OPEN verb causes an in-place-activation-capable component to start in a separate window.

HRESULT GetExtent(DWORD dwDrawAspect, SIZEL* pSizel);

The component returns the object extent in HIMETRIC dimensions. The container uses these dimensions to size the rectangle for the component's metafile. Sometimes the container uses the extents that are included in the component's metafile picture.

HRESULT SetClientSite(IOleClientSite* pClientSite);

The container calls SetClientSite to enable the component to store a pointer back to the site in the container.

HRESULT SetExtent(DWORD dwDrawAspect, SIZEL* pSizel);

Some containers call this function to impose extents on the component.

HRESULT SetHostNames(LPCOLESTR szContainerApp, PCOLESTR szContainerObj);

The container calls SetHostNames so that the component can display the container program's name in its window caption.

HRESULT Unadvise(DWORD* dwConnection);

This function terminates the advisory connection set up by Advise.

The IViewObject2 Interface

Embedded component handlers implement this interface. Handlers are a type of COM component for dealing with certain client-side aspects of linking and embedding. The default handler (the one provided by Microsoft) lives in a DLL named "OLE32.DLL." The container calls its functions, but the component program itself doesn't implement them. An IViewObject2 interface cannot be marshaled across a process boundary because it's associated with a device context.

HRESULT Draw(DWORD dwAspect, …, const LPRECTL lprcBounds, …);

The container calls this function to draw the component's metafile in a specified rectangle.

HRESULT SetAdvise(DWORD dwAspect, …, IAdviseSink* pAdvSink);

The container calls SetAdvise to set up the advisory connection to the handler, which in turn sets up the advisory connection to the component.

The IOleClientSite Interface

Containers implement this interface. There is one client site object per component object.

HRESULT GetContainer(IOleContainer** ppContainer);

The GetContainer function retrieves a pointer to the container object (document), which can be used to enumerate the container's sites.

HRESULT OnShowWindow(BOOL fShow);

The component program calls this function when it switches between the running and the loaded (or active) state. When the object is in the loaded state, the container should display a hatched pattern on the embedded object's rectangle.

HRESULT SaveObject(void);

The component program calls SaveObject when it wants to be saved to its storage. The container calls IPersistStorage::Save.

The IAdviseSink Interface

Containers implement this interface. Embedded object handlers call its functions in response to component notifications.

void OnClose(void);

Component programs call this function when they are being terminated.

void OnViewChange(DWORD dwAspect, …);

The handler calls OnViewChange when the metafile has changed. Because the component program must have been running for this notification to have been sent, the handler can call the component's IDataObject::GetData function to get the latest metafile for its cache. The container can then draw this metafile by calling IViewObject2::Draw.