libreoffice-online/loolwsd/protocol.txt
Tor Lillqvist a608aaee90 Add an invalidate: message that is in LOOL style with named parameters
The invalidatetiles: message as generated directly from the
LOK_CALLBACK_INVALIDATE_TILES will be dropped soon.
2015-05-29 09:44:39 +03:00

139 lines
4.7 KiB
Text

All communication consists of messages that are one line of
human-readable UTF-8 text optionally followed by a single newline and
binary data.
The protocol is not a request-response one. Messages may be sent in
either direction at any time, either in response to some message, or
spontaneously. For 'tile' messages, the client may send a bunch of
tile requests without waiting for return messages. The server may send
tiles proactively (guessing what the client might need). Etc.
client -> server
================
invalidatetiles part=<partNumber> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight>
All parameters are numbers. Makes the server remove any cached
tiles intersecting with the given area (in twips).
key type=<type> char=<charcode> key=<keycode>
<type> is 'input' or 'up', <charcode> and <keycode> are numbers.
load <pathname>
Deprecated.
load url=<url>
mouse type=<type> x=<x> y=<y> count=<count>
<type> is 'buttondown', 'buttonup' or 'move', others are numbers.
resetselection
saveas url=<url> format=<format> options=<options>
<url> is a URL, encoded. <format> is also URL-encoded, i.e. spaces as %20
options are the whole rest of the line, not URL-encoded, and can be empty
selecttext type=<type> x=<x> y=<y>
<type> is 'start', 'end' or 'reset', <x> and <y> are numbers.
selectgraphic type=<type> x=<x> y=<y>
<type> is 'start' or 'end' <x> and <y> are numbers.
status
tile part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight>
All parameters are numbers.
uno <command>
<command> is a line of text.
server -> client
================
error: cmd=<command> kind=<kind>
<freeErrorText>
<command> is the command part of the corresponding client->server
message that caused the error. <kind> is some single-word
classification
invalidate: part=<partNumber> x=<x> y=<y> width=<width> height=<height>
All parameters are numbers. Tells the client to invalidate any
cached tiles for the document area specified (in twips), at any
zoom level.
The client should handle either this message or the
invalidatetiles: message, which has a different syntax, with
payload directly from the LOK_CALLBACK_INVALIDATE_TILES
callback. (The latter does not contain a part number, and as the
protocol is asynchronous, it is unclear whether a client can be
sure, or find out with certainty, for what part the
invalidatetiles: message is. The invalidatetiles: message will be
dropped soon.)
nextmessage: size=<byteSize>
<byteSize> is the size, in bytes, of the next message, in case it
is "large". (In practice, nextmessage: messages precede each tile:
message). Can be ignored by clients using an API that can read
arbitrarily large buffers from a WebSocket (like JavaScript), but
must be handled by clients that cannot (like those using Poco
1.6.0).
status: type=<typeName> parts=<numberOfParts> current=<currentPartNumber> width=<width> height=<height>
<typeName> is 'text, 'spreadsheet', 'presentation', 'drawing' or 'other. Others are numbers.
tile: part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight>
<binaryPngImage>
The parameters from the corresponding 'tile' command.
Each LOK_CALLBACK_FOO_BAR callback causes a corresponding message to
the client, consisting of the FOO_BAR part in lowercase, without
underscore, followed by a colon, space and the callback payload. For
instance:
invalidatecursor:
invalidatetiles: <payload>
The communication between the parent process (the one keeping open the
Websocket connections to the clients) and a child process (handling
one document through LibreOfficeKit) uses the same protocol, with
the following additions and changes:
child -> parent
===============
child <id>
Must be the first message sent from the child to the parent. The
parent has passed the id (a 64-bit random number) to the child
when starting it, so this is how the child identificates itself.
curpart: part=<partNumber>
Sent to the parent process before certain messages that the parent
needs to act on in addition to passing them on to the client, like
invalidatetiles:
nextmessage: size=<upperlimit>
each tile: message sent from the child to the parent is preceded
by a nextmessage: message that gives an upper limit on the size of
the tile: message that will follow. (We assume it is only tile:
messages that can be "large".) Once we depend on Poco 1.6.1, where
one doesn't need to use a pre-allocated buffer when receiving
WebSocket messages, this will go away.