1035 lines
35 KiB
Plaintext
1035 lines
35 KiB
Plaintext
All communication consists of messages that are one line of
|
|
human-readable UTF-8 text (with no terminating newline), optionally
|
|
followed by a single newline and arbitrary (potentially even binary)
|
|
data.
|
|
|
|
The WebSocket distinction between 'text' and 'binary' frames has no
|
|
meaning for us for messages that don't contain additional binary data;
|
|
such messages can be either 'binary' or 'text' from the WebSocket
|
|
point of view even if we require them (the single line) to be
|
|
UTF-8. In other words, an implementation is free to send such a
|
|
single-line message as a WebSocket 'binary' frame, and the receiving
|
|
implementation must treat that equally as if it was a 'text' frame.
|
|
|
|
The WebSocket protocol says that 'text' frames are to be "interpreted"
|
|
as UTF-8, so it is probably best to indeed use 'binary' frames for
|
|
messages that contain optional non-UTF-8 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.
|
|
|
|
The original intent was that the parameters of the messages can be in
|
|
any order, as they are in a name=value form anyway and the name
|
|
indicates which parameter is which. Sadly, this was not explicitly
|
|
mentioned in this document, or tested by unit tests. So now we have
|
|
code here and there that assumes that parameters are in a specific
|
|
order anyway, thus losing the benefits of the named parameters. Oh
|
|
well.
|
|
|
|
When the document is password protected, it already implies that the
|
|
document didn't load, and that with the proper password we should try
|
|
again. Similarly for when the password given is wrong. However, if
|
|
loading fails and it isn't a password-related failure,
|
|
faileddocloading error is returned and in this case the client handles
|
|
it as a final error (that requires reloading to retry).
|
|
|
|
client -> server
|
|
================
|
|
|
|
A convention: Messages that have the first token (keyword) in
|
|
UPPERCASE are related to debugging and tracing of the client and
|
|
server software and not related to the user's actions.
|
|
|
|
DEBUG <rest of message>
|
|
|
|
The rest of the message (without the DEBUG keyword), possibly
|
|
multiple lines, is logged by the server as LOG_DBG.
|
|
|
|
ERROR <rest of message>
|
|
|
|
The rest of the message (without the ERROR keyword), possibly
|
|
multiple lines, is logged by the server as LOG_ERR.
|
|
|
|
TRACEEVENT name=<name> ph=<letter> ts=<timestamp> <more parameters>... [ args=<JSON.stringify-string> ]
|
|
|
|
Timestamps and durations are in microseconds, from
|
|
performance.now(), multiplied by 1000, and rouded to an integer.
|
|
|
|
name is a string of non-space characters.
|
|
|
|
ts is the timestamp when the trace event was generated.
|
|
|
|
ph is one of the following, and the rest of the parameters depend
|
|
on what it is.
|
|
|
|
args is an optional parameter, and its value is a JSON string
|
|
where the keys and values are strings with no spaces in them.
|
|
|
|
'i': An "Instant" event.
|
|
|
|
'S', 'F': The start and finish of an "Async" event. In addition to
|
|
the name, the messages have an "id" parameter, a unique number
|
|
that must be the same for the 'S' and 'F' messages.
|
|
|
|
'X': A "complete" event. The "dur" parameter is the duration
|
|
between the beginning of the thing being timed and the time when
|
|
the 'X' message was emitted, also in microseconds.
|
|
|
|
tileprocessed wids=<wid1,wid2,...>
|
|
|
|
Previously sent tile (server -> client) arrived and processed by the client.
|
|
We send a list of wire-ids back for tiles that have been received.
|
|
|
|
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. id can take following values:
|
|
* 'print': When request for download is basically for print purposes
|
|
* 'slideshow': When request for download is for showing slideshow
|
|
* 'export': Just a simple download
|
|
|
|
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, which is returned via 'textselectioncontent', if the selection is text-only and relatively small.
|
|
However, for selections containing images and other embedded objects, or if the selection is a large text blob,
|
|
the response is 'complexselection'.
|
|
|
|
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': The file has been previously uploaded using insertfile POST
|
|
|
|
type = 'graphicurl': The file is supposed to be downloaded by the core
|
|
itself; it does so from the URL provided in 'name'
|
|
|
|
selectbackground name=<name>
|
|
|
|
Inserts a graphic file with the name <name> into the document as background.
|
|
|
|
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>] [lang=<locale>] [deviceFormFactor=<device type>] [timezone=<timezone>] [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.
|
|
|
|
lang specifies the locale to which we should switch before loading the
|
|
document
|
|
|
|
deviceFormFactor specifies the form factor of the device the client is running on
|
|
it can be one of the following: 'desktop', 'tablet', 'mobile'
|
|
|
|
timestamp is in tzfile(5) format. For example: Pacific/Auckland.
|
|
|
|
options are the whole rest of the line, not URL-encoded, and must be valid JSON.
|
|
|
|
coolclient <major.minor[-patch]> [ <timestamp> <perfcounter> ]
|
|
|
|
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.
|
|
|
|
timestamp: the value of the JavaScript Date.now(), i.e. integer number of milliseconds since
|
|
the Unix epoch.
|
|
|
|
perfcounter: the value of the JavaScript performance.now() function at the same time.
|
|
This is also in milliseconds but can be a floating point number and can be up to
|
|
microsecond precision.
|
|
|
|
The timestamp and perfcounter are used by the server to translate performance
|
|
counter values from the client for Trace Event logging into absolute timestamps.
|
|
|
|
mouse type=<type> x=<x> y=<y> count=<count>
|
|
|
|
<type> is 'buttondown', 'buttonup' or 'move', others are numbers.
|
|
|
|
ping
|
|
|
|
requests a 'pong' server message.
|
|
|
|
renderfont font=<font> char=<characters>
|
|
|
|
requests the rendering of the given font.
|
|
The font parameter is URL encoded
|
|
The char parameter is URL encoded
|
|
|
|
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
|
|
If <url> uses 'wopi:' as the protocol, the path is treated as the path on
|
|
the wopi host.
|
|
|
|
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.
|
|
|
|
setclientpart part=<partNumber>
|
|
|
|
Informs the server that the client changed to part <partNumber>.
|
|
|
|
selectclientpart part=<partNumber>
|
|
|
|
Informs the server that the client changed the selection state of <partNumber>.
|
|
|
|
moveselectedclientparts position=<positionNumber>
|
|
|
|
Moves the selected parts to a new position.
|
|
|
|
setpage page=<pageNumber>
|
|
|
|
Valid only for text documents.
|
|
Informs the server that the client changed to page <pageNumber>.
|
|
|
|
status
|
|
|
|
styles
|
|
|
|
tile part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight> [timestamp=<time>] [id=<id>] [oldwid=<wireId>]
|
|
|
|
Parameters are numbers except wireId which is an opaque string
|
|
identifier unique to this tile.
|
|
|
|
Note: id must be echoed back in the response verbatim. It is used
|
|
when rendering slide previews of presentation documents, and not
|
|
for anything else. It is only useful to JS part and will break it
|
|
if not returned in the response.
|
|
|
|
tilecombine <parameters>
|
|
|
|
Accepts same parameters as the 'tile' message except that
|
|
parameters 'tileposx', 'tileposy' and 'oldwid are
|
|
comma-separated lists, and the number of elements in each must be
|
|
same.
|
|
|
|
if oldwid=0 this forces returning from the previous keyframe
|
|
for this tile - suitable for force-refreshing the data.
|
|
|
|
dialog <command>
|
|
|
|
<command> is unique identifier for the dialog that needs to be painted.
|
|
|
|
uno <command> [arguments]
|
|
|
|
<command> is a line of text.
|
|
[argments] - JSON encoded arguments for the UNO command
|
|
|
|
save dontTerminateEdit=<value> dontSaveIfUnmodified=<value>
|
|
|
|
A wrapper over UNO save command. A non-zero <value> is considered true.
|
|
'dontTerminateEdit' means not terminating the edit session in
|
|
spreadsheets when saving the document. In most cases, you should set it to
|
|
non-zero. 'dontSaveIfUnmodified' when set to non-zero skips saving the document when it is
|
|
unmodified.
|
|
|
|
savetostorage force=<value>
|
|
|
|
Saves the files to storage. A 'save' command automatically saves the file to
|
|
storage almost always except in the case where there is a document conflict
|
|
i.e document in the storage is changed behind our back. We might need to do
|
|
call this command with force=1 in that case to forcefully save it to storage
|
|
after asking from the user.
|
|
|
|
clientvisiblearea x=<x> y=<y> width=<width> height=<height>
|
|
|
|
Invokes lok::Document::setClientVisibleArea().
|
|
|
|
outlinestate type=<type> level=<level> index=<index> state=<state>
|
|
|
|
<type> is 'column' or 'row', <level> and <index> are numbers, <state> is 'visible' or 'hidden'.
|
|
|
|
Invokes lok::Document::setOutlineState().
|
|
|
|
useractive
|
|
|
|
Sent when the user regains focus or clicks within the active area to
|
|
disable the inactive state.
|
|
Will send invalidation and update notifications to force refreshing the screen.
|
|
|
|
See 'userinactive'.
|
|
|
|
userinactive
|
|
|
|
Sent when the user has switched tabs or away from the Browser altogether.
|
|
It should throttle updates until the user is active again.
|
|
|
|
See 'useractive'.
|
|
|
|
closedocument
|
|
|
|
This gives document owners the ability to terminate all sessions currently
|
|
having that document opened. This functionality is enabled only in case WOPI
|
|
host mentions 'EnableOwnerTermination' flag in its CheckFileInfo response
|
|
|
|
versionrestore <action>
|
|
|
|
Version restore related messages.
|
|
|
|
<action> can take the following values:
|
|
- prerestore: The storage is about to restore the document to an earlier
|
|
revision.
|
|
|
|
asksignaturestatus
|
|
|
|
Requests a signing status of the document.
|
|
|
|
rendershapeselection mimetype=<mimeType>
|
|
|
|
Request rendering of selected shapes into an SVG format.
|
|
By now only SVG mimetype is handled (image/svg+xml)
|
|
|
|
removesession <viewid>
|
|
|
|
Requests the removal of a given view from the document. Lower
|
|
privilege views cannot remove higher ones, eg. a readonly view
|
|
can't remove an editor.
|
|
|
|
traceeventrecording <start/stop>
|
|
|
|
Starts or stops comphelper::TraceEvent recording.
|
|
|
|
sallogoverride <string>
|
|
|
|
Overrides the SAL_LOG value, or stops overriding if no parameter
|
|
or parameter is "default".
|
|
|
|
loggingleveloverride <default|max|verbose|terse|none|fatal|critical|error|warning|notice|information|debug|trace>
|
|
|
|
Override the Online logging level for the thread(s) and Kit
|
|
processes handling this particular client.
|
|
|
|
The value is either one of the log level names, or the special
|
|
value "default" (meaning whatever is the log level specified in
|
|
the "logging.level" configuration setting), "verbose", or "terse")
|
|
(meaning the most or least verbose level allowed, the
|
|
"logging.most_verbose_level_settable_from_client" or
|
|
"logging.least_verbose_level_settable_from_client" configuration
|
|
setting).
|
|
|
|
paintwindow <id> rectangle=<x>,<y>,<width>,<height> dpiscale=<scale>
|
|
|
|
Requests painting the area of a window.
|
|
|
|
<id> is the window's int ID.
|
|
|
|
<x>,<y>,<width>,<height> is the area of the dialog to be rendered.
|
|
|
|
<scale> is a scaling factor, e.g. 1 for non-HiDPI.
|
|
|
|
contentcontrolevent <JSON>
|
|
*Properties:
|
|
type - date,drop-down
|
|
selected:
|
|
- for drop-down: zero based index of item that is selected
|
|
- for date: date which is selected by date picker
|
|
|
|
server -> client
|
|
================
|
|
|
|
coolserver <coolwsd version> <coolwsd git hash> <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.
|
|
|
|
lokitversion <JSON string>
|
|
|
|
JSON string contains version information in format:
|
|
{ProductName: <>, ProductVersion: <>, ProductExtension: <>, BuildId: <>}
|
|
|
|
Eg: {"ProductName": "LibreOffice",
|
|
"ProductVersion": "5.3",
|
|
"ProductExtension": ".0.0.alpha0",
|
|
"BuildId": "<full 40 char git hash>"}
|
|
|
|
osinfo: <string>
|
|
|
|
string that contains OS name and version.
|
|
|
|
clipboardkey: <token>
|
|
|
|
Send access token for web clipboard use, may arrive periodically
|
|
Current and previous hash remain valid for that period, always use
|
|
the latest.
|
|
|
|
contextmenu: <json description of the context menu>
|
|
|
|
When the user right-clicks in the document, the content of the context
|
|
menu is sent back via this callback.
|
|
|
|
The structure of the context menu is a JSON, and looks like:
|
|
|
|
{
|
|
"menu": [
|
|
{ "text": "label text1", "type": "command", "command": ".uno:Something1", "enabled": "true" },
|
|
{ "text": "label text2", "type": "command", "command": ".uno:Something2", "enabled": "false" },
|
|
{ "type": "separator" },
|
|
{ "text": "label text2", "type": "menu", "menu": [ { ... }, { ... }, ... ] },
|
|
...
|
|
]
|
|
}
|
|
|
|
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>] [params=1,2,3,...,N]
|
|
<freeErrorText>
|
|
|
|
<command> is the command part of the corresponding client->server
|
|
message that caused the error.
|
|
|
|
<command> can also take following values:
|
|
'internal': for errors generated without directly corresponding to a client
|
|
message.
|
|
'storage': for errors pertaining to storage (filesysytem, wopi etc.)
|
|
|
|
<kind> is some single-word classification
|
|
|
|
<code> (when provided) further specifies the error as forwarded from
|
|
LibreOffice
|
|
|
|
close: <reason>
|
|
|
|
Ask a client to close the websocket connection with <reason>.
|
|
Exactly similar fields are also available in WebSocket protocol's
|
|
CLOSE frame, but some browser implementation (google-chrome) doesn't seem to
|
|
handle that well. This is a temporary application-level close websocket
|
|
to circumvent the same.
|
|
|
|
<reason> can have following values:
|
|
* ownertermination - If the session close is due to 'Document owner'
|
|
terminating the session.
|
|
(Document owner is the one who has the file ownership and hence have the
|
|
ability to kill all other sessions if EnableOwnerTermination flag in WOPI
|
|
CheckFileInfo is 'true' (assumed to be 'false' by default).
|
|
|
|
* shuttingdown - Sent when the server is going down in a graceful fashion.
|
|
The server doesn't disconnect from clients yet, but starts
|
|
saving document and tearing down internals.
|
|
|
|
* recycling - The last message sent from the server when it is gracefully
|
|
shutting down to let clients know they can try connecting
|
|
after a short interval.
|
|
|
|
* documentconflict - All sessions of this document are going down
|
|
because file was changed in storage and we want to load the new document
|
|
from the storage.
|
|
|
|
* versionrestore payload - Version restore message is also sent as part of
|
|
the close frame. See `versionrestore:` message for details.
|
|
|
|
getchildid: id=<id>
|
|
|
|
Returns the child id
|
|
|
|
invalidatetiles: part=<partNumber> x=<x> y=<y> width=<width> height=<height> wid=<wid>
|
|
|
|
All parameters are numbers. Tells the client to invalidate any
|
|
cached tiles for the document area specified (in twips), at any
|
|
zoom level.
|
|
|
|
invalidatetiles: EMPTY, <partNumber>, <mode>, wid=<wid>
|
|
|
|
Tells the client to invalidate all cached tiles.
|
|
|
|
pong rendercount=<num>
|
|
|
|
sent in reply to a 'ping' message, where <num> is the total number
|
|
of rendered tiles of the document.
|
|
|
|
saveas: url=<url> name=<name>
|
|
|
|
<url> is a wopi URL of the newly created file, including the access token.
|
|
<name> is the resulting name (without path) that was created on the wopi
|
|
host. It can differ from what was requested in case the file already existed.
|
|
|
|
status: type=<typeName> parts=<numberOfParts> current=<currentPartNumber> width=<width> height=<height> viewid=<viewId> hiddenparts=<part1,part2,...> selectedparts=<part1,part2,...> [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'
|
|
|
|
statusupdate: type=<typeName> parts=<numberOfParts> current=<currentPartNumber> width=<width> height=<height> viewid=<viewId> hiddenparts=<part1,part2,...> selectedparts=<part1,part2,...> [partNames]
|
|
|
|
Same as status: but issued whenever the document parts have updated significantly.
|
|
status: implies document loading. statusupdate: is just an update.
|
|
|
|
styles: {"styleFamily": ["styles in family"], etc. }
|
|
|
|
statechanged: <key>=<value>
|
|
|
|
Notifies client of state changed events of <key>.
|
|
Eg: 'statechanged: .uno:Undo=enabled'
|
|
|
|
textselectioncontent:
|
|
<JSON>
|
|
|
|
Current selection's content, only for text-only selections of a reasonably limited size.
|
|
For complex selection and large texts, selectioncontent message is returned.
|
|
The keys of the JSON are MIME types (text/html, text/plain;charset=utf-8),
|
|
the values are the content of the selection in that format.
|
|
For debug/test purposes, in case a single MIME type is requested, that's
|
|
returned as-is, not inside a JSON.
|
|
|
|
complexselection:
|
|
|
|
Complex selections with embedded objects and large text selections need special export handling.
|
|
This response signifies that the payload is large and/or complex and needs to be retrieved via the clipboard API.
|
|
|
|
tile: part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight> [timestamp=<time>] [wid=<wireId>]
|
|
<binaryPngImage>
|
|
|
|
The parameters from the corresponding 'tile' command.
|
|
|
|
WireId is a monotonically incrementing, unique reference to a
|
|
state of the document on the server, and can be included by
|
|
the client in the next 'tile' message requesting the same tile.
|
|
|
|
the tile message has at least one keyframe, followed by any
|
|
number of concatentated compressed deltas.
|
|
|
|
delta: part=<partNumber> width=<width> height=<height> tileposx=<xpos> tileposy=<ypos> tilewidth=<tileWidth> tileheight=<tileHeight> [timestamp=<time>] [wid=<wireId>]
|
|
|
|
A delta command is like a tile: command but the payload is purely
|
|
an incremental patch on top of a previous tile.
|
|
|
|
commandresult: <payload>
|
|
|
|
This is used to acknowledge the commands from the client.
|
|
<payload> is { command: <command name>, success: 'true' }
|
|
|
|
Each LOK_CALLBACK_FOO_BAR callback except
|
|
LOK_CALLBACK_INVALIDATE_TILES 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. (LOK_CALLBACK_INVALIDATE_TILES causes an invalidatetiles:
|
|
message as documented above.) For instance:
|
|
|
|
invalidatecursor: <payload>
|
|
|
|
The payload contains a rectangle describing the cursor position
|
|
and the id of the view which triggered the invalidation. JSON 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.
|
|
|
|
invalidateviewcursor:
|
|
|
|
Per-view cursor position invalidation. JSON payload.
|
|
|
|
textviewselection:
|
|
|
|
Per-view text selection bounds. JSON payload.
|
|
|
|
cellviewcursor:
|
|
|
|
Per-view cell cursor position. JSON payload.
|
|
|
|
graphicviewselection:
|
|
|
|
Per-view graphic selection. JSON payload.
|
|
|
|
viewcursorvisible:
|
|
|
|
Per-view cursor visible. JSON payload.
|
|
|
|
viewlock:
|
|
|
|
Per-view lock rectangle. JSON payload.
|
|
|
|
viewinfo: <payload>
|
|
|
|
Message is sent everytime there is any change in view information.
|
|
<payload> consists of an array of JSON objects. Structure of JSON
|
|
objects is like : {"id": <viewid>, "username": <Full Name of the user>}
|
|
|
|
redlinetablechanged:
|
|
|
|
Signals that the redlines table has been modified.
|
|
Redlines are used for tracking changes.
|
|
|
|
comment:
|
|
|
|
Signals that comment has either been added, removed or modified. See
|
|
LOK_CALLBACK_COMMENT for JSON structure.
|
|
|
|
celladdress: <payload>
|
|
|
|
Message is sent anytime the content of the address input box should be updated.
|
|
The <payload> is a string representing the new content.
|
|
|
|
stats: <key> <value>
|
|
|
|
Contains statistical data. Eg: 'stats: wopiloadduration 5' means that
|
|
wopi calls made in loading of document took 5 seconds.
|
|
|
|
perm: <permission>
|
|
|
|
<permission> can be one of 'edit', 'view', 'readonly'. Client must
|
|
change the UI accordingly (disabling buttons etc.)
|
|
|
|
wopi: <JSON>
|
|
|
|
Sent only in case storage is WOPI. Contains WOPI related
|
|
capabilities/information for JS part to act accordingly.
|
|
|
|
Properties mentioned:
|
|
+ PostMessageOrigin: See WOPI specs for more information
|
|
+ HideSaveOption: (boolean): If Collabora Online should hide the save options
|
|
+ HidePrintOption: (boolean): If Collabora Online should hide print options
|
|
+ HideExportOption: (boolean): If Collabora Online should hide the export options
|
|
this implies 'Download as' options in file menu
|
|
+ HideRepairOption: (boolean): If Collabora Online should hide the Repair
|
|
undo functionality
|
|
|
|
versionrestore: <action>
|
|
|
|
Possible values for <action>:
|
|
|
|
- prerestore_ack: The host can go ahead with restoring the document to an
|
|
earlier revision.
|
|
|
|
clipboardchanged: <selection>
|
|
|
|
Sent when the content of the internal clipboard has changed.
|
|
|
|
context: <applicationId> <context>
|
|
|
|
Sent when the editing context changes in the application; like when the
|
|
user switches from editing a textframe to editing a graphic object, etc.
|
|
Can be used eg. for contextual change of the toolbars.
|
|
|
|
signaturestatus: <sign status>
|
|
Possible values:
|
|
0xffff - Unknown
|
|
0 - NOSIGNATURES
|
|
1 - OK
|
|
2 - BROKEN
|
|
3 - INVALID (signature is OK, but doc is modified now)
|
|
4 - NOTVALIDATED (signature is OK, but certificate could not be validated)
|
|
5 - PARTIAL_OK (signature and certificate are ok, but not all files are signed - old documents only)
|
|
|
|
shapeselectioncontent: <content>
|
|
|
|
Current selection's content
|
|
|
|
mobile: <event>
|
|
|
|
Available only in the mobile (Android and iOS) apps. When you send
|
|
'mobile: eventname', the socket code will fire a 'eventname' event on the
|
|
map.
|
|
|
|
windowpaint: id=<id> width=<width> height=<height> rectangle=<x>,<y>,<width>,<height> hash=<hash> nopng
|
|
|
|
Sent to the client when the server rendered the bitmap of a dialog.
|
|
|
|
<id> is the window's int ID.
|
|
|
|
<width> is the pixel width of the returned bitmap.
|
|
|
|
<height> is the pixel height of the returned bitmap.
|
|
|
|
<x>,<y>,<width>,<height> is the rendered area of the dialog
|
|
|
|
<hash> is the hash key of this bitmap in the pixmap cache
|
|
|
|
nopng appears when the the bitmap was already in the cache, so no PNG
|
|
encoding happened.
|
|
|
|
contentcontrol: <JSON>
|
|
*Properties
|
|
- action - show, hide, change-picture
|
|
- rectangles - rectangle coordinates (x-coordinate, y-coordinate, width, height)
|
|
- date - boolean to indicate date content control
|
|
- items - array of items for dropdown
|
|
|
|
canonicalidchange: viewid=<id> canonicalid=<id> viewrenderedstate=<Light|Dark|Empty>
|
|
|
|
child -> parent
|
|
===============
|
|
|
|
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:
|
|
|
|
errortoall: cmd=<command> kind=<kind> [code=<error_code>]
|
|
|
|
Causes the parent to send the corresponding error: message to all
|
|
clients.
|
|
|
|
saveas: url=<url> filename=<filename>
|
|
|
|
<url> is a URL of the destination, encoded. Sent from the child to the
|
|
parent after a saveAs() completed.
|
|
<filename> is the resulting jailed filename of the newly created file.
|
|
|
|
client-<sessionId> <Payload Message>
|
|
|
|
Forwarding message between a child and its parent session.
|
|
The payload message is forwarded to the ClientSession.
|
|
|
|
procmemstats: pid=<pid> pss=<pss in kb> dirty=<private dirty in kb>
|
|
|
|
Memory information sent periodically to parent process by each of
|
|
the kit processes.
|
|
|
|
clipboardcontent:
|
|
|
|
in reply to a getclipboard: message.
|
|
|
|
mime_type\n
|
|
length\n
|
|
<binary selection content>
|
|
...
|
|
|
|
traceevent:
|
|
forcedtraceevent:
|
|
|
|
Followed by a number of lines consisting of Chrome Trace Event
|
|
formatted data recorded by the comphelper::TraceEvent API in the
|
|
core parts of the kit process.
|
|
|
|
The forcedtraceevent variant causes the data to be written to the
|
|
output file even if Trace Event recording is not turned on at the
|
|
moment. This is for metadata information.
|
|
|
|
parent -> child
|
|
===============
|
|
|
|
child-<sessionId> <Payload Message>
|
|
|
|
Forwarding message between a parent and its child session.
|
|
The payload message is forwarded to the ChildSession.
|
|
|
|
child-<sessionId> getclipboard:
|
|
|
|
fetches the complete clipboard for this view and returns
|
|
a clipboardcontent message.
|
|
|
|
child-<sessionId> setclipboard:
|
|
|
|
Sets the clipboard content for this view.
|
|
|
|
mime_type\n
|
|
length\n
|
|
<binary selection content>
|
|
...
|
|
|
|
disconnect
|
|
|
|
Signals to the child that the client for the respective connection
|
|
has disconnected.
|
|
|
|
exit
|
|
|
|
Signals to the child that the process must end and exit.
|
|
|
|
|
|
Admin console
|
|
===============
|
|
|
|
Client can query admin console to get information about currently opened
|
|
documents. Following information about the document is exposed:
|
|
|
|
* PID of the process hosting the document
|
|
* Number of client views opening this document
|
|
* Name of the document (URL encoded)
|
|
* Memory consumed by the process (in kilobytes)
|
|
* Elapsed time since first view of document was opened (in seconds)
|
|
|
|
Admin console can also opt to get notified of various events on the server. For
|
|
example, getting notified when a new document is opened or closed. Notifications
|
|
are commands sent from server to the client over established websocket.
|
|
|
|
Before doing anything, clients must authenticate by providing an auth token with
|
|
'auth' command.
|
|
|
|
client -> admin
|
|
==============
|
|
|
|
auth jwt=<jwtToken>
|
|
|
|
Authenticate the client with provided jwtToken. This is necessary before any
|
|
other command.
|
|
|
|
subscribe <space separated list of commands>
|
|
|
|
Where list of commands are the ones that client wants to get notified
|
|
about. For eg. 'subscribe adddoc rmdoc'
|
|
|
|
version
|
|
|
|
Queries the server for current version of lokit and coolserver. See
|
|
'lokitversion' and 'coolserver' in admin -> client for the format of
|
|
response message.
|
|
|
|
documents
|
|
|
|
Queries the server for list of opened documents. See `documents` command
|
|
in admin -> client section for format of the response message
|
|
|
|
history
|
|
|
|
Queries the server for list of opened and expired documents with their
|
|
snapshots. Returns a json object and it looks like:
|
|
|
|
{ "History" :
|
|
{
|
|
"documents": [
|
|
{
|
|
"filename":"hello-world.odt",
|
|
"start":1492104619,
|
|
"end":1492104680,
|
|
"pid":12302,
|
|
"snapshots": [
|
|
{
|
|
"creationTime":1492104619,
|
|
"memoryDirty":0,
|
|
"activeViews":1,
|
|
"views":["0008", ...],
|
|
"lastActivity":1492104619
|
|
},
|
|
{
|
|
...
|
|
}
|
|
]
|
|
},
|
|
{
|
|
...
|
|
}
|
|
],
|
|
"expiredDocuments" : [...]
|
|
}
|
|
}
|
|
|
|
mem_consumed
|
|
sent_bytes
|
|
recv_bytes
|
|
|
|
Queries for total memory or bandwidth being consumed by the server
|
|
in kilobytes. For mem_consumed this includes processes - coolwsd,
|
|
coolforkit, and child processes hosting various documents. For
|
|
sent/recv_bytes this includes only external traffic.
|
|
|
|
active_docs_count
|
|
|
|
Returns total number of documents opened
|
|
|
|
active_users_count
|
|
|
|
Returns total number of users connected. This is a summation of number
|
|
of views opened of each document.
|
|
|
|
settings
|
|
|
|
Queries the server for configurable settings from admin console.
|
|
|
|
log_lines
|
|
Gets last n lines from "coolwsd.log" file.
|
|
|
|
channel_list
|
|
Gets the log channels list with their respective log levels.
|
|
|
|
update-log-levels
|
|
Updates the log channels' log levels with the given log levels. Format is: "update-log-levels channel1name=loglevel channel2name=loglevel".
|
|
|
|
set <setting1=value1> <setting2=value2> ...
|
|
|
|
Sets a particular setting (must be one returned as response to
|
|
`settings` command) to value.
|
|
|
|
There are only 4 configurable settings as of now.
|
|
|
|
mem_stats_size: Number of memory consumed values that server caches
|
|
atmost.
|
|
mem_stats_interval: Time after which server calculates its total memory
|
|
consumption
|
|
cpu_stats_size: Number of cpu usage values that server caches atmost.
|
|
cpu_stats_interval: Time after which server calculates its total cpu
|
|
usage.
|
|
|
|
Note: cpu stats gathering is a TODO, so not functional as of now.
|
|
|
|
kill <pid>
|
|
|
|
<pid> process id of the document to kill. All sessions of document would be
|
|
killed. There is no way yet to kill individual sessions.
|
|
|
|
wopiSrcMap
|
|
|
|
get map of wopiSrc<->routeToken
|
|
|
|
verifyauth jwt=<jwt_token> id=<unique_identifier>
|
|
|
|
verify jwt token without shutting down the socket connection, works only with monitor
|
|
|
|
admin -> client
|
|
===============
|
|
|
|
Commands marked with [*] are notifications that are delivered only if client is
|
|
subscribed to these commands using `subscribe` (see client->admin
|
|
section). Others are just response messages to some client command.
|
|
|
|
[*] adddoc <pid> <filename> <sessionid> <username> <userid> <memory consumed> <wopiHost> <isViewReadOnly> <wopiSrc>
|
|
|
|
<pid> process id hosting the document
|
|
<filename> URL encoded name of the file
|
|
<sessionid> string identifying the view of this document
|
|
<memory consumed> RSS of <pid> in kilobytes
|
|
<wopihost> storage host on which document exist
|
|
|
|
[*] rmdoc <pid> <sessionid>
|
|
|
|
<pid> process id hosting the document
|
|
<sessionid> view which was closed
|
|
|
|
[*] mem_stats <memory consumed>
|
|
|
|
<memory consumed> in kilobytes sent from admin -> client after every
|
|
mem_stats_interval (see `set` command for list of settings)
|
|
|
|
[*] propchange <pid> <property> <new-value>
|
|
|
|
Notifies of a property change on a pid's property. Properties can
|
|
include:
|
|
"mem" <memory consumed> - in kilobytes of the process.
|
|
|
|
[*] resetidle <pid>
|
|
|
|
<pid> process id hosting the document
|
|
reset the idle time counter for the document
|
|
|
|
[*] updateroutetoken <JSON string>
|
|
|
|
<JSON string> contains the map of serverId as key and routeToken as value
|
|
|
|
[*] routing_rmdoc <wopiSrc>
|
|
|
|
<wopiSrc> of the document that is getting removed, fired when all the views gets expired
|
|
|
|
note: This might get additional parameters in future
|
|
|
|
[*] wopiSrcMap <JSON string>
|
|
|
|
wopiSrcMap:
|
|
{
|
|
"routeToken": "abcpqr"
|
|
"wopiSrc" : ["wopiSrc1", "wopiSrc2"]
|
|
}
|
|
<JSON string> contains the map wopiSrc<->routeToken
|
|
|
|
InvalidAuthToken
|
|
|
|
This is sent when invalid auth token is provided in 'auth' and 'verifyauth' command. See
|
|
above.
|
|
|
|
NotAuthenticated
|
|
|
|
When client sends an admin command that requires authentication.
|
|
|
|
ValidAuthToken
|
|
|
|
This is sent when valid token is provided in 'verifyauth' command. See above
|
|
|
|
documents <pid> <filename> <number of views> <memory consumed> <elapsed time> <idle time>
|
|
<pid> <filename> ....
|
|
...
|
|
|
|
<elapsed time> is in seconds since the first view of the document was opened
|
|
<idle time> is in seconds since some user did something in his view of the document (even just moving
|
|
the insertion cursor)
|
|
<number of views> Number of users/views opening this(<pid>) document
|
|
Other parameters are same as mentioned in `adddoc`
|
|
|
|
Each set document attributes is separated by a newline.
|
|
|
|
mem_consumed <memory>
|
|
Total memory being consumed by Collabora Online.
|
|
total_avail_mem <memory>
|
|
Total memory available to whole Collabora Online. This takes into account
|
|
the memproportion setting, if set by the user, when calculating the amount
|
|
of memory available to the process.
|
|
|
|
sent_bytes <memory>
|
|
recv_bytes <memory>
|
|
|
|
<memory> in kilobytes
|
|
|
|
active_docs_count <count>
|
|
|
|
active_users_count <count>
|
|
|
|
settings <setting1=value1> <setting2=value2> ...
|
|
|
|
Current value of each configurable setting.
|
|
|
|
mem_stats <comma separated list of memory consumed values>
|
|
|
|
The length of the list is equal to the value of setting
|
|
mem_stats_size`
|
|
|
|
coolserver <JSON string>
|
|
|
|
The returned JSON string contains information in the following format:
|
|
{Version: <>, Hash: <>}
|
|
|
|
Eg: {"Version": "master..",
|
|
"Hash": "4897710"}
|
|
|
|
lokitversion <JSON string>
|
|
|
|
JSON string contains version information in format:
|
|
{ProductName: <>, ProductVersion: <>, ProductExtension: <>, BuildId: <>}
|
|
|
|
Eg: {"ProductName": "LibreOffice",
|
|
"ProductVersion": "5.3",
|
|
"ProductExtension": ".0.0.alpha0",
|
|
"BuildId": "<full 40 char git hash>"}
|