strepsirrhini/libreoffice-online
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
libreoffice-online/loolwsd/protocol.txt
Tor Lillqvist bc7decb6ca No "disconnect" message is sent by our client JS code (and that is good) 
Having a separate "disconnect" message is a disgrace. There should be
no need for it. WebSocket has a perfectly fine graceful disconnect
mechanism already (CLOSE frames). The code needs to be prepared to
receive a CLOSE frame at any time. The code also needs to be prepared
for the underlying socket being bluntly closed by the other end,
without sending any WebSocket CLOSE frame. The only sane thing is to
handle a "disconnect" message in the same way as those situations
anyway, so why is it needed?
2016-02-24 17:44:17 +02:00

277 lines
9.1 KiB
Text
Raw Blame History

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.
downloadas name=<fileName> id=<id> format=<document format> options=<SkipImages, etc>
Exports the current document to the desired format and returns a download URL
The id identifies the request on the client.
getchildid
Requests the child id so that it knows where the files needs to be sent when it is
inserted in the document
gettextselection mimetype=<mimeType>
Request selection's content
paste mimetype=<mimeType>
<binaryPasteData>
Paste content at the current cursor position.
insertfile name=<name> type=<type>
Inserts the file with the name <name> into the document, we currently support type = 'graphic'
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 [part=<partNumber>] url=<url> [timestamp=<time>] [options=<options>]
part is an optional parameter. <partNumber> is a number.
timestamp is an optional parameter. <time> is provided in microseconds
since the Unix epoch - midnight, January 1, 1970.
options are the whole rest of the line, not URL-encoded
loolclient <major.minor[-patch]>
Upon connection, a client must announce the version number it supports.
Major: an integer that must always match between client and server,
otherwise there are no guarantees of any sensible
compatibility. This is bumped when API changes.
Minor: an integer is more flexible and is at the discretion of either party.
Security fixes that do not alter the API would bump the minor version number.
Patch: an optional string that is informational.
mouse type=<type> x=<x> y=<y> count=<count>
<type> is 'buttondown', 'buttonup' or 'move', others are numbers.
renderfont font=<font>
requests the rendering of the given font.
The font parameter is URL encoded
requestloksession
requests the initialization of a LOK process in an attempt to predict the user's
interaction with the document
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
styles
tile part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight>
All parameters are numbers.
tilecombine <parameters>
Accept same parameters as 'tile' message except parameters 'tileposx' and 'tileposy'
can be a comma separated list, and number of elements in both must be same.
unload [save|force]
unloads the document.
if 'save' is specified, the document is saved before unloading,
otherwise, changes are discarded.
if other users have the document open, and save not specified,
'force' is necessary to discard changes.
uno <command>
<command> is a line of text.
partpagerectangles
Invokes lok::Document::getPartPageRectangles().
clientvisiblearea x=<x> y=<y> width=<width> height=<height>
Invokes lok::Document::setClientVisibleArea().
server -> client
================
loolserver <major.minor[-patch]>
Upon connection, the server must announce the version number it supports.
Major: an integer that must always match between client and server,
otherwise there are no guarantees of any sensible
compatibility. This is bumped when API changes.
Minor: an integer is more flexible and is at the discretion of either party.
Security fixes that do not alter the API would bump the minor version number.
Patch: an optional string that is informational.
downloadas: jail=<jail directory> dir=<a tmp dir> name=<name> port=<port>
The client should then request http://server:port/jail/dir/name in order to download
the document
error: cmd=<command> kind=<kind> [code=<error_code>]
<freeErrorText>
<command> is the command part of the corresponding client->server
message that caused the error. <kind> is some single-word
classification
<code> (when provided) further specifies the error as forwarded from
LibreOffice
getchildid: id=<id>
Returns the child id
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'
styles: {"styleFamily": ["styles in family"], etc. }
partpagerectangles: <payload>
Payload format is the same as LOK_CALLBACK_TEXT_SELECTION.
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:
unocommandresult: <payload>
Callback that an UNO command has finished.
See LOK_CALLBACK_UNO_COMMAND_RESULT for details.
partscountchanged: action=<PartInserted|PartDeleted> part=<index>
Callback action performed:
PartInserted. The document parts has changed by the action
Insert.
PartDeleted. The document parts has changed by the action
Delete.
<index> The index of the part <PartInserted|PartDeleted>
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:
disconnect [reason]
Sent before disconnecting gracefully.
reason: optional human-readable reason to disconnect.
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.
saveas: url=<url>
<url> is a URL of the destination, encoded. Sent from the child to the
parent after a saveAs() completed.
Reference in a new issue View git blame Copy permalink