OLE Server Specification
From RISC OS
Jump to navigationJump to 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.
