6 The OLE-Server Library

6.5 Implementing local servers

To implement a local server, the basic structure of your application should be the same as any GUI application using the Microsoft Win32 API, with the following exceptions.

Define a subclass of <ole-server-framework> and implement the required Dylan methods described in Section 6.7.2 on page 273.
Make your application capable of self-registration with the Windows Registry. With self-registration, the application can record itself in the Registry as a server for the COM objects it implements. The OLE-Server contains utilities that make writing a self-registering local server application simpler.

: Wrap the body of the server application with a call to the function OLE-util-register-only?, page 283, which will test whether the application was passed arguments requiring it to perform a registration operation. Depending on the result of the call, the application can either run as normal, or perform the requested registration operation and exit.

  if (OLE-util-register-only?()) // just [un]register & terminate
   register-ole-server(class-id, prog-id, title-string, 
                       short-name: short-name-string);
  else // actually run the program
  ...
  end if;

: When the application is wrapped in this code, if it is run with the /RegServer option (typically done as part of an installation script), it will just register itself and terminate, or if run with the /UnregServer option, it will try to unregister itself and terminate. Otherwise, OLE-util-register-only? returns #f and the application continues to run normally.

Once it is past the self-registration wrapper, make your application call OLE-util-started-by-OLE?, page 314 to find out if it has been invoked by an OLE container. If the function returns #f, your application should just run as an independent application. If the function returns #t, your application should not show any of its windows; support code in the OLE-Server library will take care of that at the appropriate time.
If your application is running under OLE, then before it enters its event loop, it must make an instance of the Dylan class <class-factory>, page 320, passing it the application's COM Class ID and the Dylan object class to be instantiated -- that is, your subclass of <ole-server-framework>.

: COM's class factories are a means of creating multiple instances of a particular COM class. Instantiating the class factory takes care of registering your server application as the process that will serve objects of the given COM class, so that the container can connect to it.
: (This registration should not be confused with the registration procedure discussed earlier, which was for registering the application as a server for the COM class or classes it supports, so that the container knows which server application to run.)

When a container application connects to your server application, a single instance of your subclass is instantiated automatically by the class factory. The container will call QueryInterface on it to find the interfaces it needs. This object is the "controlling unknown" for all the low-level OLE interfaces; if necessary, your server could also call QueryInterface on it to obtain low-level interface pointers in order to extend the capabilities of the library.
When your server application terminates, it should call revoke-registration, page 319, on the instance of <class-factory>.
If your application is activated in-place, you must call the function OLE-util-translate-accelerator within the event loop to properly handle the top-level menu. It is harmless to call it in other contexts. Note that the COM interface object is created while events are being processed, so it cannot simply be placed in a local variable before entering the loop.
If your application has created an interface object, then before it terminates (such as when responding to a $WM-CLOSE message), it must make sure that the interface is properly disconnected from the container. To do this, call the function OLE-util-close-server on the interface object.

: Because the OLE-Server instantiates the COM interface object for your server automatically, rather than through calling make on your subclass of <ole-server-framework>, your application will not naturally have a name bound to the COM interface object upon which you can call <class-factory>. You must arrange to bind the instance to a name by defining an initialize method on your subclass of <ole-server-framework>.

Your application must have at least two windows: a top-level frame window (which includes the border and title bar), and a single child window that occupies the client area within the border, that is referred to as the document window. The document window can be subdivided into other child windows, but there must be a single window handle representing the whole client region.
In stand-alone execution, your server application should use ShowWindow to display the frame window, as any Windows application would. For out-of-place activation under OLE, your application's frame window is not shown until the support library calls your application's OLE-part-open-out method.
For in-place activation -- that is, activation as an embedded object -- the OLE-Server library calls the application's OLE-part-doc-window method to get the document window. The library then takes care of displaying the document window as a child of the container's window, and also automatically places a "hatch" border around it. Although the frame window is not used during in-place activation, it must still exist, to serve as the initial parent when creating the document window.
You must set up the code that actually draws to the document window by calling it from either of two contexts: in response to a $WM-PAINT message, or when the application's OLE-part-draw-metafile method is called to produce an image of the window that will be displayed by the container when the server is not active, and will be saved with the container's other data.
If your application has state information other than its screen image, as it most likely will, it will need to provide methods for handling that data's persistent storage. Even if it does not have such information it must provide methods, though they can do nothing. See the entries for OLE-part-Create-Streams, OLE-part-Open-Streams, OLE-part-Release-Streams, OLE-part-Save-To-Storage, and OLE-part-Load-From-Storage in Section 6.7.2.