Servers: Server Items
The latest version of this topic can be found at Servers: Server Items.
When a container launches a server so that a user can edit an embedded or linked OLE item, the server application creates a "server item." The server item, which is an object of a class derived from COleServerItem, provides an interface between the server document and the container application.
The COleServerItem class defines several overridable member functions that are called by OLE, usually in response to requests from the container. Server items can represent part of the server document or the entire document. When an OLE item is embedded in the container document, the server item represents the entire server document. When the OLE item is linked, the server item can represent a part of the server document or the whole document, depending on whether the link is to a part or to the whole.
In the HIERSVR sample, for example, the server-item class, CServerItem, has a member that is a pointer to an object of the class CServerNode. The CServerNode object is a node in the HIERSVR application's document, which is a tree. When the CServerNode object is the root node, the CServerItem object represents the whole document. When the CServerNode object is a child node, the CServerItem object represents a part of the document. See the MFC OLE sample HIERSVR for an example of this interaction.
Implementing Server Items
If you use the application wizard to produce "starter" code for your application, all you have to do to include server items in your starter code is to choose one of the server options from the OLE Options page. If you are adding server items to an existing application, perform the following steps:
To implement a server item
Derive a class from
COleServerItem.In your derived class, override the
OnDrawmember function.The framework calls
OnDrawto render the OLE item into a metafile. The container application uses this metafile to render the item. Your application's view class also has anOnDrawmember function, which is used to render the item when the server application is active.Implement an override of
OnGetEmbeddedItemfor your server-document class. For further information, see the article Servers: Implementing Server Documents and the MFC OLE sample HIERSVR.Implement your server-item class's
OnGetExtentmember function. The framework calls this function to retrieve the size of the item. The default implementation does nothing.
A Tip for Server-Item Architecture
As noted in Implementing Server Items, server applications must be able to render items both in the server's view and in a metafile used by the container application. In the Microsoft Foundation Class Library's application architecture, the view class's OnDraw member function renders the item when it is being edited (see CView::OnDraw in the Class Library Reference). The server item's OnDraw renders the item into a metafile in all other cases (see COleServerItem::OnDraw).
You can avoid duplication of code by writing helper functions in your server-document class and calling them from the OnDraw functions in your view and server-item classes. The MFC OLE sample HIERSVR uses this strategy: the functions CServerView::OnDraw and CServerItem::OnDraw both call CServerDoc::DrawTree to render the item.
The view and the item both have OnDraw member functions because they draw under different conditions. The view must take into account such factors as zooming, selection size and extent, clipping, and user-interface elements such as scroll bars. The server item, on the other hand, always draws the entire OLE object.
For more information, see CView::OnDraw, COleServerItem, COleServerItem::OnDraw, and COleServerDoc::OnGetEmbeddedItem in the Class Library Reference.