I have got really quite excited about this collaborative stuff, and
since the proposal did not suggest the transport mechanism, here comes a
suggestion for a basic protocol for communication between two AbiWord
processes. Please note (a) this is only a top level protocol, which
could be implemented on top of dbus or just a straigh TCP/IP, or some
other protocol; (b) I might be up to no good, and it almost certainly
not complete, hence RFC.
The proposed protocol is xml-based, so that we would use an xml listener
for parsing the messages as we do with AW importer; it means that our
change records and similar items would be easy to translate into the
protocol messages and vice versa.
A message passed between two processes has the following format
<abitalk version="1.0" [uid="xxxxx"] [token="xxxxx"]>
<%cmd%>[content]</%cmd%>[<%cmd%>[content]</%cmd%>]
</abitalk>
version: identifies the protocol version
uid: the uuid of the document which is the subject of conversation;
if not provided, the commands to follow will carry operations
only on the application, not documents.
token: authorisation token. The token is a standard uuid with time
stamp ajusted to indicate when the authoristation token
expires. Tokens are connected to a specific document uid.
If no token is provided the only legitimate commands to follow
are <token> and <getdoc> (see below).
Single message can contain one or more commands:
%cmd%: specific command name, which can be followed by set of
attributes
[content]: content specific to given command (optional)
Predefined commands
-------------------
The following commands are predefined by the protocol:
<getdoc name="xxxx"/>
Request for the entire document identified by name
<document name="xxxx">[doc]</document>
Sent in response to <getdoc> request. The content of this element
is raw document as contained in the document file and should be
passed directly to the AW importer chain.
<token [uid="xxxx"]/>
uid: the token in standard uuid format. The token is specific to
the document uid, and has a limited lifespan; the expiry time is
indicated by the uid time stamp.
If no uid is specified, the command is interpreted as request for
authorisation token.
If uid is specified, this command is a response to request for
authorisation token; uid is the token.
<release uid="xxxx"/>
uid: authorisation token.
This command is sent to release the token; as soon soon as this
command send, the token becomes invalid. This command is required
for the entire transation to be valid (see below notes on token
handling).
<error id="errno">[Verbose msg]</error>
id: UT_AbiTalk::Result
Verbose msg: optional verbose, human readable, error message.
All other commands are handled by command handlers registered via
UT_AbiTalk::registerHandler(); their number and meaning has not direct
impact on the protocol itself (i.e., the protocol can be easily expanded
as new features are added).
Token handling
--------------
A and B are communicating Abi processes. If A wishes to send commands to
B, A requests an authorisitation token. B issues the token and until
either the token expires or is released by A, B does not carry any other
operations on the document/process than those that are requested by A
using the authorisation token. At the same time, while A is in
possession of the token, it will turn down any request for authorisation
tokens from other parties, including B.
When finished with the whole command sequence, A has to release the
token by sending <release> command.
B keeps an eye on the life of the issued token; if the token expires
before the <release> cmd is received for the token, B reverses all
operation carried on the document by A using that token and dispatches
<error>Token expired</error> cmd to A. In response to the error A has to
request a new token and resend all commands.
Example command
---------------
A sample command (after the intial hanshake and token retrieval) could
look like:
<abitalk version="1.0" uuui="xxxxxx" token="yyyyyy">
<insertspan start=5 end=7 props="font-size:12pt">my span</insertspan>
</abitalk>
On receipt of the message, the AW process would translate it to an
insert Span change record and pass it to the document identified by the
uuid.
Enough for one night.
Tomas
Received on Tue May 17 23:11:22 2005
This archive was generated by hypermail 2.1.8 : Tue May 17 2005 - 23:11:22 CEST