157 lines
5.3 KiB
Text
157 lines
5.3 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
|
|
================
|
|
|
|
canceltiles
|
|
|
|
All outstanding tile messages from the client to the server are
|
|
dropped and will not be handled. There is no guarantee of exactly
|
|
which tile: messages might still be sent back to the client.
|
|
|
|
gettextselection mimetype=<mimeType>
|
|
|
|
Request selection's content
|
|
|
|
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> [timestamp=<time>]
|
|
|
|
timestamp is an optional parameter. <time> is provided in microseconds
|
|
since the Unix epoch - midnight, January 1, 1970.
|
|
|
|
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 and it can be empty
|
|
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, like the "loadtest" program in the loolwsd sources).
|
|
|
|
status: type=<typeName> parts=<numberOfParts> current=<currentPartNumber> width=<width> height=<height> [partNames]
|
|
|
|
<typeName> is 'text, 'spreadsheet', 'presentation', 'drawing' or 'other. Others are numbers.
|
|
if the document has multiple parts and those have names, part names follow separated by '\n'
|
|
|
|
textselectioncontent: <content>
|
|
|
|
Current selection's content
|
|
|
|
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.
|