OLE Server Specification

From RISC OS

Revision as of 17:41, 30 January 2009 by Erik Groenhuis (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
 ---------------------------------------------------------------------------
 $Id: OLEServer.txt 1.11 2009-01-16 15:39:00+01 erikgrnh Exp $
 ---------------------------------------------------------------------------

 Originator - Mike
 Purpose    - Specification of generic 'OLE' interface and mechanisms
 Version    - $Revision: 1.11 $
 Started    - 14th August 1993

 $Log: OLEServer.txt $
 Revision 1.11  2009-01-16 15:39:00+01  erikgrnh
 Corrected some typos. Minor clarifications. Some added comments.
 All comments from the author are now in the form "[Note EG: ... ]".

 Revision 1.10  2004-02-29 19:56:10+01  erikgrnh
 Split the specification into a description for the client and a
 description for the server. Embelished with more detail.

 ---------------------------------------------------------------------------

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$<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
========================

(1) 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

(2) 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.

(3) 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.

(4) 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.


The server should also handle some exceptional situations

(5) 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.

(6) 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

(7) 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.

Personal tools