OLE Server Specification

Overview

OLE or object linking and embedding allows an application to share data with a secondary or server application which can edit that data and return it. This allows compliant applications to gain features provided by specific graphics or text servers without having to re-implement those features.

This documentation defines the message passing protocols necessary for this kind of data sharing.

The client

A client application (such as Impression) may wish to edit data it is capable of loading and rendering (such as drawfiles). There are two options open for such an application. Either it can provide facilities to edit these files itself, or use an already resident editor by sharing the file with it. It seems sensible and easier to choose the second option, in which case the client needs to ask a 'compliant' server to engage in a two-way data sharing session. It does so by the use of a OLEServer$&lf;UniqueName> system variable which the server provides.

The server

Any application which provides its own file type and is capable of editing such files may set itself up to be an OLE server. To do so it needs to create a system variable, outlining the file type it can edit. This should be done in the applications boot file so it is present for use by a client whenever the application is seen by the filer.

The syntax of this variable is as follows

Variable name  = OLEServer$Type_XXX
Variable value = -N <UniqueName> -R <run><Run$Path>

X          = 0..9 | A..F
AlphaChar  = 0..9 | A..Z | a..z
UniqueName = [1..16]*<AlphaChar> (i.e. one to sixteen AlphaChars)
run        = 'run ' or '/'

Spaces must be used as separators.

Typical examples are

  OLEServer$Type_AFF : -N OLESupport -R /Desktop_OLESupport
  OLEServer$Type_FFF : -N StrongED -R /ADFS::Csite.$.Apps.!StrongED

Tokens

-N Name

This token specifies a unique name to identify the server in an OpenSession message. This message is broadcast so it is up to the server who recognises the name to respond. This string can be up to 16 characters long. When passed in messages it should be specified as a 16 byte string with all unused bytes zeroed.

Note the server name should be modelled on the application name such as 'OLESupport' used by the support module or 'StrongED' as used by the StrongED text editor.

-R Run

This token allows a potential client to Wimp_StartTask the server. It must provide a run$path string which uniquely locates the server. This could be an expanded pathname or more usually a system variable. It should be preceded with a run command so the whole string can be passed straight to Wimp_StartTask.

    eg 'run <Draw$Dir>'.
       '/<Draw$Dir>' etc

Creating an OLE session

An OLE session should be opened by a client application which cannot itself edit a particular data format and wishes to share the data with a server in order to do so.

A Server's point of view

Setting the environment variable

The !boot file of the server should set an OLEServer$Type_XXX variable for each type of file it wishes to serve. The -R value should start the server

Opening the session

The server gets an OLEOpenSession User_Message_Recorded (type 18) message.

   Message_OLEOpenSession (&80E21)
   -------------------------------
    +0 = length of block
    +4 = task handle of the sender
    +8 = my_ref
   +12 = 0
   +16 = message number (&80E21)
   +20 = 16 byte unique name padded with zeros
   +36 = window handle of display holding file
   +40 = x offset of data in window
   +44 = y offset of data in window
   +48 = format number
    format = 0 or 1 (edit file)
     +52 = Session number
     +56 = file type
     +60 = full pathname of data, zero terminated
   format = 2 (re-edit file)
     +52 = Session number
   format > 2 (reserved for future expansion)

The messages to start a new session are format 0 or 1. The server should check that the message, which was broadcast, should be handled by it.

• It should check that the Unique name at +20 refers to it.
• It should check that the file type at +56 is a type it wants to handle.

If either check fails, the server should simply ignore the message. If the server does want to handle the session, it should call Wimp_SendMessage to send a User_Message_Acknowledge (19) message. The content of the message is the same as the message it received, with the original my_ref copied to your_ref (at +12).

It must then use Wimp_SendMessage to send an OLEOpenSessionAck (&80E22) User_Message (17) message to the client. The message block is again the same as the client's message, with my_ref copied to your_ref. This message will inform the client of the server's task handle.

The server can now start editing the file, whose path was given in the message block (at +60). Make sure to attach the client's task handle (+4) and the Session number (+52) to this particular edit session.

Note EG: I'm not sure what should be done first: sending the OLEOpenSessionAck message or start editing the file. Probably send the message first. This will allow the client to prepare for OLEFileChanged messages.

For the handling of format 2 messages see below.

File changes

When the user saves the file being edited, the server should send an OLEFileChanged message to the appropriate client.

   Message_OLEFileChanged (&80E1E)
   -------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = User message (17)
            - R1 = ^Block
                +0 = length of block
                +4 = 0 (not used on entry)
                +8 = 0 (not used on entry)
               +12 = 0 (original message)
               +16 = message number (&80E1E)
               +20 = format number
                 format = 0 (saved to a different file) then
                  +24 = Session number
                  +28 = full pathname of data, zero terminated
                 format = 1 (saved to the same file) then
                  +24 = Session number
                        (format used by OLESupport)
                 format > 1 then
                  +24... reserved for future extensions
            - R2 = Task handle of client

The task handle of the client and the Session number should be those associated with the file that is edited. If the path of the file being saved is unchanged, send a format 1 message. If it has changed, send a format 0 message.

Note: the server should not feel it owns the file and thus should not attempt to delete the file during emergencies. If the server corrupts the file, the client should be capable of working out that the file format has been compromised, when it receives an OLEFileChanged.

Closing the session

When the user closes the file being edited, the server should send an OLECloseSession message to the appropriate client.

   Message_OLECloseSession (&80E23)
   --------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = User message (17)
            - R1 = ^Block
                +0 = length of block
                +4 = 0 (not used on entry)
                +8 = 0 (not used on entry)
               +12 = 0 (original message)
               +16 = message number (&80E23)
               +20 = format number
                 format = 0 then
                   +24 = Session number (-1 means all sessions are closing)
                 format > 0 reserved for future extensions
            - R2 = Task handle of client

The task handle of the client and the Session number should be those associated with the file that was edited.

Incoming Close Session

The server should respond to OLECloseSession messages.

These are sent by a client when it abandons the object for which an OLE session is active. For example, a DTP editor may have a table included in it's document. The user wanted to edit the table, so the DTP editor started an OLE session with a server that can handle the table. While this session is going, the user decides to cut the table from the document. This means that the OLE session can be abandoned, and the DTP editor sends an OLECloseSession to the server.

In another case, the client may quit. In that case, it will broadcast an OLECloseSession message with Session number -1.

   Message_OLECloseSession (&80E23)
   --------------------------------
    +0 = length of block
    +4 = task handle of client
    +8 = my ref
   +12 = 0
   +16 = message number (&80E23)
   +20 = format number
     format = 0 then
       +24 = Session number (-1 means all sessions are closing)
     format > 0 reserved for future extensions

The server should check the combination of task handle and session number against the documents it is editing. When a document matches it should quit the edit of that file.

Note EG: it is unclear to me who is responsible for removing the file. It is very probable that the client should remove any files. These can be either the original file or any files with a new path written by the server. This needs to be thought through and specified in these documents, to prevent temporary files from being left behind.

If the Session number is -1, the server should quit all edits of documents that are associated with the task handle of the client. Note that clients may broadcast this message, so the server should always check the task handle of the client and only close the edits belonging to that client.

The server quits

When the server quits (e.g. because the user selects Quit from the menu), it should broadcast an OLECLoseSession message with Session number -1.

   Message_OLECloseSession (&80E23)
   --------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = User message (17)
            - R1 = ^Block
                +0 = length of block
                +4 = 0 (not used on entry)
                +8 = 0 (not used on entry)
               +12 = 0 (original message)
               +16 = message number (&80E23)
               +20 = format number
                 format = 0 then
                   +24 = Session number (-1 means all sessions are closing)
                 format > 0 reserved for future extensions
            - R2 = 0 for broadcast

Re-edit

The client may request to re-edit the same file.

It can then send a format 2 message which will inform a server that the user has tried to perform an OLE action on the same data a second time. This gives those applications which allow documents to be closed, but not lost from memory (eg ArtWorks) a chance to reopen an edit window on the data. Obviously it is up to the client to decide what to do here when it receives a format 2 message.

Note EG: the last sentence is one again very cryptic. Clients receiving this message? Maybe it should be "it is up to the server to decide what to do here". Obviously the intent here is that the session still exists, as it is enough to refer to it only by the session number. Presumably the server is expected to remember previous sessions and consider them open again when it receives this message.

Session numbers & task handles

To provide context for OLE sessions a session number and task handle should be kept by the client and server for each session opened. Session numbers must be allocated by the client task in a way which makes them unique for the run time of the program. The client should also keep a copy of the server's task handle which it will receive via Message_OLEOpenSessionAck. This way it can inform the server whenever it closes down.