OLE Server Specification: Difference between revisions

From RISC OS
Jump to navigationJump to search
(Wikified)
(→‎OLECloseSession: More clarification in the examples. Server should not delete the file.)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
This page is intended as a full description of the [[Computer Concepts]] [[OLE]] protocol as seen from the '''server''' side. A programmer writing an application should be able to find here all the information required to let the application work as an OLE server. To let the application work as an OLE client, see the [[OLE Client 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.




Line 26: Line 5:


Any application which provides its own file type and is capable of editing
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
such files may set itself up to be an OLE server. To do so it needs to be able
to send and accept OLE messages, and announce itself as a server by setting
a system variable, outlining the file type it can edit. This should be done
an environment variable for each file type it can handle.
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
===Setting the environment variable===
:''For the syntax of the OLEServer$Type_XXX variable see the [[OLE Client Specification#The Server Variable|OLE Client Specification]].''
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, and the -N value should be a string which can be recognised
by the server as referring to itself. The name of the server application
is usually a good choice, possibly extended with some characters to
prevent confusion with other servers.


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.


==An OLE session==
Typical examples are
OLEServer$Type_AFF : -N OLESupport -R /Desktop_OLESupport
OLEServer$Type_FFF : -N StrongED -R /ADFS::Csite.$.Apps.!StrongED


An OLE session will be initiated by a client application. The server simply waits
until a request comes in.


===Tokens===
===Opening the session===
A client that wants to open a session will
save the data as a temporary file and broadcast
an OLEOpenSession User_Message_Recorded (type 18) message.
Messages intended for your server will contain the same string at
offset +20 as you set in the -N parameter of the environment variable.
The message also contains the type of the file that the client wishes to be edited.


If the server recognises the string and the file type, it should acknowledge the message by sending an OLEOpenSessionAck message. It should set up internal data describing the OLE session, read the temporary file (its path is given in the message) and offer it to the user to edit.
;-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.


===File changes===
;-R Run
When the user saves the file being edited, the server should send an
: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.
OLEFileChanged message to the appropriate client.
eg 'run <Draw$Dir>'.
The server can choose to either
'/<Draw$Dir>' etc
*save the file to the same path as the original (recommended) and send a format 1 message
*save the modified file to a different temporary location, and send a format 0 message.


Note: though the client is obliged
to check if the format of the file is correct, the server should take care
to only write valid data.


==Creating an OLE session==
===Closing the edit===
When the user closes the file being edited, the server should send an
OLECloseSession message to the appropriate client.
The server can consider the session closed. (For an exception, see the Format 2
OLEOpenSession message.)


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.


==Actions the server should take==


===Setup===
==A Server's point of view==
The server should setup environment variable for each file type it
is willing to handle in its !Boot file.


When the server is started, it should be ready to receive OLE messages and have handlers
===Setting the environment variable===
in place for them.
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===
===A file changes===
Whenever the user saves changes to a file, the server should check its
The server gets an OLEOpenSession User_Message_Recorded (type 18) message.
internal data to see if the file is part of an OLE session. If so, it should send

an OLEFileChanged message to the client.
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)
Message_OLEFileChanged (&80E1E)
-------------------------------
-------------------------------
SWI Wimp_SendMessage
SWI Wimp_SendMessage
On entry - R0 = User message (17)
On entry - R0 = 17 (User message)
- R1 = ^Block
- R1 = ^Block
+0 = length of block
+0 = length of block
+4 = 0 (not used on entry)
+4 = task handle of sender (not used on entry)
+8 = 0 (not used on entry)
+8 = my_ref (not used on entry)
+12 = 0 (original message)
+12 = your_ref = 0 (original message)
+16 = message number (&80E1E)
+16 = message number (&80E1E)
+20 = format number
+20 = format number
Line 147: Line 87:
- R2 = Task handle of client
- R2 = Task handle of client


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


If the server application saves a file to the same path, it should send a format 1 message. If it saves to a different file, it should send a format 0 message, passing the changed path name in the 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===
===An edit is closed===
When the user closes the file being edited, the server should send an
When the user ends an editing session, usually by closing the editing
window, the server should check its internal data to see if the file
OLECloseSession message to the appropriate client.
is part of an OLE session. If so, it should
send an OLECloseSession message to the client.


Message_OLECloseSession (&80E23)
Message_OLECloseSession (&80E23)
Line 167: Line 104:
- R1 = ^Block
- R1 = ^Block
+0 = length of block
+0 = length of block
+4 = 0 (not used on entry)
+4 = task handle of the sender (not used on entry)
+8 = 0 (not used on entry)
+8 = my_ref (not used on entry)
+12 = 0 (original message)
+12 = your_ref = 0 (original message)
+16 = message number (&80E23)
+16 = message number (&80E23)
+20 = format number
+20 = format number
Line 177: Line 114:
- R2 = Task handle of client
- R2 = Task handle of client


The task handle of the client and the Session number should be those
The task handle of the client in R2 and the Session number at offset +24 should be those
associated with the file that was edited.
associated with the file that was edited.


The server can consider
===Incoming Close Session===
the session ended and remove any internal data associated with the
session. The client will be responsible for the removal of the
temporary file.


Alternatively, a server may keep the contents of the edited data in its
The server should respond to OLECloseSession messages.
internal memory and keep the session information in its list, merely marking
the session as closed. It can then accept format 2 OLEOpenSession messages
for this data in the future.

===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 to inform all clients which may have a session open with
it that it should close those sessions. Note that the server does
not really need to check if it actually has any sessions open. It
can simply broadcast the message and let the clients work out if
they have sessions that need to be closed.

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

Note: the server should not feel it owns the file and thus should not
attempt to delete the file during emergencies.

==Messages to be handled by the server==

===OLEOpenSession===

====Format 0 and 1====
These messages indicate that a client wishes to start a new OLE session. From the server's point of view there is no difference between a format 0 and a format 1 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)

If an OLEOpenSession message comes in, the server
should check that the message is intended for it.
*It should check that the Unique name at +20 is equal to the value of the -N parameter it set in the environment variable(s).
*It should check that the file type at +56 is a type it wants to handle (as encoded in the name of the environment variable).
If either check fails, the server should simply ignore the message.

If the server wants to handle the session, it should
send a copy of the message back as a User_Message (17), with the original my_ref
code at +8 copied to the your_ref field, and the message number set to
the code for OLEOpenSessionAck (&80E22).

Message_OLEOpenSessionAck (&80E22)
----------------------------------
SWI Wimp_SendMessage
On entry - R0 = User message (17)
- R1 = ^Block
+0 = length of block (unchanged)
+4 = task handle of sender (not used on entry)
+8 = my_ref (not used on entry)
+12 = your_ref: a copy of the my_ref of the OLEOpenSession message
+16 = message number (&80E22)
+20 The rest of the message unchanged from the OLEOpenSession message
- R2 = Task handle of client, from block+4 of the OLEOpenSession message

This will have the following effects:
*It tells the WIMP that the original recorded message is acknowledged (because my_ref was copied to your_ref), so that message won't bounce back to the client.
*It sends the new OLEOpenSessionAck message, so the client will know this server has accepted the session.
*It informs the client of the task handle of the server.

The server can now start editing the file, whose path was given in the
message block (at +60). The server should remember the client's task handle
(+4) and the Session number (+52), as the combination of these numbers
uniquely identifies the session.

====Format 2====
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 servers which allow documents to be
closed, but not lost from memory (eg ArtWorks) a chance to reopen an
edit window on the data. Note that a message of this format does not include
a path for a temporary file created by the client, so this format only works
if the server still has the file data in its memory.

Servers which do not keep data from closed edits can simply ignore this message.
The client will eventually send a format 0 or 1 OLEOpenSession message, which the
server can handle in the normal way.

If a server wants to handle a format 2 request, it should check the client's task handle and the session number to see if it knows the OLE session, and still has the data. If not, the server should ignore the message.

If the server knows the session and still has the data, it can acknowledge the message in the same way as for format 0 and format 1 OLEOpenSession messages, mark the session open in its internal data, and offer the data to the user for editing.

===OLECloseSession===


These are sent by a client when it abandons the object for which an
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
OLE session is active. For example, a DTP editor
(the client in this example) may have a table
included in it's document. The user wanted to edit the table, so the
included in its document. The user wanted to edit the table, so the
DTP editor started an OLE session with a server that can handle 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
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,
from the document. This means that the OLE session can be abandoned,
and the DTP editor sends an OLECloseSession to the server.
and the DTP editor (the client) sends an OLECloseSession to the server
with the Session number associated with this session at +24.


In another case, the client may quit. In that case, it will broadcast
In another case, if the client quits, this implies that all the
sessions it has open must be closed. To do so,
it will broadcast
an OLECloseSession message with Session number -1.
an OLECloseSession message with Session number -1.


Line 198: Line 254:
--------------------------------
--------------------------------
+0 = length of block
+0 = length of block
+4 = task handle of client
+4 = task handle of the sender
+8 = my ref
+8 = my_ref
+12 = 0
+12 = 0
+16 = message number (&80E23)
+16 = message number (&80E23)
Line 207: Line 263:
format > 0 reserved for future extensions
format > 0 reserved for future extensions


The server should check the combination of task handle and session
The server should check the combination of task handle (at +4)
and session number (at +24)
number against the documents it is editing. When a document matches it
against the documents it is editing. When a document matches,
the server
should quit the edit of that file.
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
If the Session number is -1, the server should quit all edits of
documents that are associated with the task handle of the client.
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.''


In either case the server should not feel it owns the file associated
with a session and thus should not attempt to delete it.
Deletion of the file should be left to the client.


==See Also==
==Session numbers & task handles==
*[[OLE]]
*[[OLE Specification]]
*[[OLE Client Specification]]
*[[User Messages]]


[[Category:Protocols]]
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.

Latest revision as of 11:01, 16 January 2014

This page is intended as a full description of the Computer Concepts OLE protocol as seen from the server side. A programmer writing an application should be able to find here all the information required to let the application work as an OLE server. To let the application work as an OLE client, see the OLE Client Specification.


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 be able to send and accept OLE messages, and announce itself as a server by setting an environment variable for each file type it can handle.

Setting the environment variable

For the syntax of the OLEServer$Type_XXX variable see the OLE Client Specification.

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, and the -N value should be a string which can be recognised by the server as referring to itself. The name of the server application is usually a good choice, possibly extended with some characters to prevent confusion with other servers.


An OLE session

An OLE session will be initiated by a client application. The server simply waits until a request comes in.

Opening the session

A client that wants to open a session will save the data as a temporary file and broadcast an OLEOpenSession User_Message_Recorded (type 18) message. Messages intended for your server will contain the same string at offset +20 as you set in the -N parameter of the environment variable. The message also contains the type of the file that the client wishes to be edited.

If the server recognises the string and the file type, it should acknowledge the message by sending an OLEOpenSessionAck message. It should set up internal data describing the OLE session, read the temporary file (its path is given in the message) and offer it to the user to edit.

File changes

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

  • save the file to the same path as the original (recommended) and send a format 1 message
  • save the modified file to a different temporary location, and send a format 0 message.

Note: though the client is obliged to check if the format of the file is correct, the server should take care to only write valid data.

Closing the edit

When the user closes the file being edited, the server should send an OLECloseSession message to the appropriate client. The server can consider the session closed. (For an exception, see the Format 2 OLEOpenSession message.)


Actions the server should take

Setup

The server should setup environment variable for each file type it is willing to handle in its !Boot file.

When the server is started, it should be ready to receive OLE messages and have handlers in place for them.

A file changes

Whenever the user saves changes to a file, the server should check its internal data to see if the file is part of an OLE session. If so, it should send an OLEFileChanged message to the client. 

   Message_OLEFileChanged (&80E1E)
   -------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = 17 (User message)
            - R1 = ^Block
                +0 = length of block
                +4 = task handle of sender (not used on entry)
                +8 = my_ref (not used on entry)
               +12 = your_ref = 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 in R2 and the Session number at offset +24 should be those associated with the file that is edited.

If the server application saves a file to the same path, it should send a format 1 message. If it saves to a different file, it should send a format 0 message, passing the changed path name in the message.

An edit is closed

When the user ends an editing session, usually by closing the editing window, the server should check its internal data to see if the file is part of an OLE session. If so, it should send an OLECloseSession message to the client. 

   Message_OLECloseSession (&80E23)
   --------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = User message (17)
            - R1 = ^Block
                +0 = length of block
                +4 = task handle of the sender (not used on entry)
                +8 = my_ref (not used on entry)
               +12 = your_ref = 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 in R2 and the Session number at offset +24 should be those associated with the file that was edited.

The server can consider the session ended and remove any internal data associated with the session. The client will be responsible for the removal of the temporary file.

Alternatively, a server may keep the contents of the edited data in its internal memory and keep the session information in its list, merely marking the session as closed. It can then accept format 2 OLEOpenSession messages for this data in the future.

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 to inform all clients which may have a session open with it that it should close those sessions. Note that the server does not really need to check if it actually has any sessions open. It can simply broadcast the message and let the clients work out if they have sessions that need to be closed. 

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

Note: the server should not feel it owns the file and thus should not attempt to delete the file during emergencies.

Messages to be handled by the server

OLEOpenSession

Format 0 and 1

These messages indicate that a client wishes to start a new OLE session. From the server's point of view there is no difference between a format 0 and a format 1 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)

If an OLEOpenSession message comes in, the server should check that the message is intended for it.

  • It should check that the Unique name at +20 is equal to the value of the -N parameter it set in the environment variable(s).
  • It should check that the file type at +56 is a type it wants to handle (as encoded in the name of the environment variable).

If either check fails, the server should simply ignore the message.

If the server wants to handle the session, it should send a copy of the message back as a User_Message (17), with the original my_ref code at +8 copied to the your_ref field, and the message number set to the code for OLEOpenSessionAck (&80E22). 

   Message_OLEOpenSessionAck (&80E22)
   ----------------------------------
   SWI Wimp_SendMessage
   On entry - R0 = User message (17)
            - R1 = ^Block
                +0 = length of block (unchanged)
                +4 = task handle of sender (not used on entry)
                +8 = my_ref (not used on entry)
               +12 = your_ref: a copy of the my_ref of the OLEOpenSession message
               +16 = message number (&80E22)
               +20 The rest of the message unchanged from the OLEOpenSession message 
            - R2 = Task handle of client, from block+4 of the OLEOpenSession message

This will have the following effects:

  • It tells the WIMP that the original recorded message is acknowledged (because my_ref was copied to your_ref), so that message won't bounce back to the client.
  • It sends the new OLEOpenSessionAck message, so the client will know this server has accepted the session.
  • It informs the client of the task handle of the server.

The server can now start editing the file, whose path was given in the message block (at +60). The server should remember the client's task handle (+4) and the Session number (+52), as the combination of these numbers uniquely identifies the session.

Format 2

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 servers which allow documents to be closed, but not lost from memory (eg ArtWorks) a chance to reopen an edit window on the data. Note that a message of this format does not include a path for a temporary file created by the client, so this format only works if the server still has the file data in its memory.

Servers which do not keep data from closed edits can simply ignore this message. The client will eventually send a format 0 or 1 OLEOpenSession message, which the server can handle in the normal way.

If a server wants to handle a format 2 request, it should check the client's task handle and the session number to see if it knows the OLE session, and still has the data. If not, the server should ignore the message.

If the server knows the session and still has the data, it can acknowledge the message in the same way as for format 0 and format 1 OLEOpenSession messages, mark the session open in its internal data, and offer the data to the user for editing.

OLECloseSession

These are sent by a client when it abandons the object for which an OLE session is active. For example, a DTP editor (the client in this example) may have a table included in its 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 (the client) sends an OLECloseSession to the server with the Session number associated with this session at +24.

In another case, if the client quits, this implies that all the sessions it has open must be closed. To do so, it will broadcast an OLECloseSession message with Session number -1. 

   Message_OLECloseSession (&80E23)
   --------------------------------
    +0 = length of block
    +4 = task handle of the sender
    +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 (at +4) and session number (at +24) against the documents it is editing. When a document matches, the server should quit the edit of that file.

If the Session number is -1, the server should quit all edits of documents that are associated with the task handle of the client.

In either case the server should not feel it owns the file associated with a session and thus should not attempt to delete it. Deletion of the file should be left to the client.

See Also

Retrieved from "http://www.riscos.info/index.php?title=OLE_Server_Specification&oldid=5844"