-
Notifications
You must be signed in to change notification settings - Fork 771
/
Copy pathprotocol.txt
1281 lines (824 loc) · 46 KB
/
protocol.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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.
windowselecttext id=<dialogId> swap=<true|false> x=<x_position> y=<y_position>
This protocol is used to notify the system about text selection within a window, including the option to swap the mark and cursor roles.
- id=<dialogId> : Specifies the ID of the dialog window where the selection is happening.
- swap=<true|false> : Indicates whether the mark/cursor roles should be swapped. If swap=true, the mark and cursor positions are swapped.
- x=<x_position> : The x-coordinate of the selection position.
- y=<y_position> : The y-coordinate of the selection position.
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 integer <value> is considered true (non-integer
values such as 'true' are not allowed). '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.
clientzoom tilepixelwidth=<width> tilepixelheight=<height> tiletwipwidth=<twipWidth> tiletwipheight=<twipHeight> dpiscale=<scale> zoom=<zoomLevel>
Requests an update of the client zoom level and tile size.
<width> and <height> define the tile dimensions in pixels.
<twipWidth> and <twipHeight> define the tile dimensions in twips.
<scale> is the scaling factor, e.g., 1 for non-HiDPI displays.
<zoomLevel> represents the zoom factor applied to the client view.
This command ensures that the rendered tiles match the correct zoom level and DPI scaling.
commandvalues command=<UNOCommand>[?param1=value1¶m2=value2...]
Sends a UNO command from the client to the server.
- <UNOCommand> is the command to be executed (e.g., .uno:ViewAnnotations).
- Optional query parameters can be appended to specify additional command details.
completefunction name=<FunctionName>
Requests the execution of a spreadsheet function in MobileWizard.Clients can request to complete a function name partially typed in the formula input box.
<FunctionName> is the name of the function to be applied, such as SUM, MIN, AVG, MAX, etc.
This command allows the client to request calculation functions dynamically.
dialogevent <windowId> { "id": "<objectId>", "cmd": "<eventType>", "data": "<data>", "type": "<objectType>" }
Sends an event message related to a dialog object within JSDialog.
- <windowId> is the identifier of the dialog window (e.g., the JSDialog ID).
- <objectId> is the ID of the object that triggered the event, such as "POPOVER", "numberformat", "masterslidebutton", etc.
- <eventType> represents the type of event that occurred, such as "selected", "Activate", "click", "close", "response", "keypress", "render", etc.
- <data> contains any object data entered by the user, which will dictate the action performed.
- <objectType> specifies the type of object, such as "combobox", "iconpreview", "toolbox", etc.
Example:
1.dialogevent 45 { "id": "linestylevalueset", "cmd": "click", "data": "0.19801980198019803;0.19130434782608696", "type": "drawingarea" }
2.dialogevent 21 {"id":"fontnamecombobox", "cmd": "render_entry", "data": "16;100;100", "type": "combobox"}
3.dialogevent 10 { "id": "-1" }
exportas url=<url>
This command allows for the seamless export of documents within the WOPI protocol framework.
Requests the export of a file, directing the server to handle it through a WOPI (Web Application Open Platform Interface) URL.
- <url> is the URL that specifies the location of the file to be exported. This URL is passed using the wopi protocol, encoded via encodeURIComponent to ensure the proper formatting for transfer.
formfieldevent { "type": "<objectType>", "cmd": "<eventType>", "data": "<data>" }
This command helps communicate form field interactions and pass relevant data back to the server or application for further processing.
This can be used to handle user actions like selecting a dropdown option or similar events
<type> Specifies the type of form field, such as "drop-down" etc
<cmd> Represents the event that occurred on the form field, such as "selected" etc
<data> Contains any relevant data tied to the event. This can include an index, value, or other information depending on the event type.
getslide hash=<slideHash> part=<slidePart> width=<canvasWidth> height=<canvasHeight> renderBackground=<backgroundRenderFlag> renderMasterPage=<masterPageRenderFlag> devicePixelRatio=<devicePixelRatio>
This command is used to request and render a slide with the appropriate properties for a specific device display and rendering conditions.
Requests a specific slide from the server, providing necessary parameters to ensure proper rendering based on the client's display settings.
<hash>: The hash value identifying the specific slide to be requested.
<part>: Specifies the part or index of the slide (useful for segmented or multi-part slides).
<width>: The width of the canvas in which the slide will be rendered.
<height>: The height of the canvas in which the slide will be rendered.
<renderBackground>: A flag indicating whether the slide background should be rendered. 0 for not rendered, 1 for rendered.
<renderMasterPage>: A flag indicating whether the master page of the slide should be rendered. 0 for not rendered, 1 for rendered.
<devicePixelRatio>: The device pixel ratio, typically window.devicePixelRatio, which adjusts the rendering quality for HiDPI displays.
resetaccesstoken <token=<accessToken>>
This command ensures that the client uses the updated access token for further requests.
Resets the access token for authentication or session management.
- <token>: The new access token that replaces the previous one.
renamefile <filename=<newFilename>>
Requests a file rename operation.
- `<filename>`: The new name for the file, URL-encoded to handle special characters.
This command updates the file name on the server, ensuring proper encoding for special characters in the filename.
a11ystate <enableA11y>
The a11ystate protocol is used to enable or disable accessibility (A11y) support in the UI.
geta11yfocusedparagraph
The geta11yfocusedparagraph protocol is used to retrieve information about the currently focused paragraph in an editable area, supporting accessibility (A11y) features.
a11ycaretposition
The a11ycaretposition protocol is used to notify or request the current caret position within an editable area, supporting accessibility (A11y) features.
notasync:
Warns when a non-asynchronous (blocking) dialog is used.
This message is triggered to notify that a dialog operation is not running asynchronously, which may affect performance or user experience.
getpresentationinfo
This adds support for getting the presentation info from core.
This change uses the new GetPresentationInfo() funciton that was added to the LOKit API.
removetextcontext id=<windowId> before=<before_position> after=<after_position>
This protocol is used to remove text context from a specified location in a document. It allows the deletion of multiple characters within a range by specifying the positions before and after the deletion.
- id=<windowId> : Specifies the ID of the window where the text removal operation is occurring.
- before=<before_position> : The position before the deletion starts.
- after=<after_position> : The position after the deletion ends.
browsersetting action=update key=<SettingKey> value=<SettingValue>
The browsersetting protocol modify specific UI settings.
- key=<SettingKey> : The name of the setting to update (e.g., ShowStatusBar).
- value=<SettingValue> : The new value for the setting (e.g., true or false).
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.
loaded: viewid=<viewId> views=<number of active views> isfirst=<true|false>
Sent after a view has been loaded successfully.
Best to rely on this to detect loading events (rather than status:).
<viewId> the unique ID of this view (meaningful only in LOKit).
<views> the total number of active views in the document after finishing loading this one.
<isfirst> "true" if this is the first view (i.e. the document has just loaded), otherwise "false".
See also unloaded:.
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 (deprecated, use loaded: instead). 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>
unloaded: viewid=<viewId> views=<number of active views>
Sent after a view has been unloaded successfully.
Best to rely on this to detect unloading events.
<viewId> the unique ID of this view (meaningful only in LOKit).
<views> the total number of active views in the document after finishing loading this one.
See also loaded:.
wopi -> server
===============
extractdocumentstructure url=<documentURL> filter=<filterType>
Extracts structured data from a document and returns it in JSON format.
- url=<documentURL> : Specifies the document location.
- filter=<filterType> : (Optional) Limits extraction to specific elements (e.g., contentcontrol, charts, docprops, slides). If omitted, all available data is extracted.
This command retrieves structured document data for further processing.
https://sdk.collaboraonline.com/docs/extract_transform_api.html#general-extraction
transformdocumentstructure url=<documentURL> transform=<JSONTransformation>
Modifies a document's structure based on a JSON transformation recipe.
url=<documentURL> : Specifies the document location.
transform=<JSONTransformation> : Defines the structural modifications in JSON format.
This command applies the transformation rules and returns the modified document.
https://sdk.collaboraonline.com/docs/extract_transform_api.html#general-transform
extractlinktargets url=<documentURL>
This command returns a list of link targets in JSON format, which includes various document elements such as tables, images, and bookmarks.
url=<documentURL> : Specifies the document location.
You can use the target in the URL to open the document at a specific position, for example: `&target=Table1|table`
getthumbnail x=<Width> y=<Height>
Generates a thumbnail image of a document or a specific element inside it.
- x=<Width> : Sets the width of the thumbnail.
- y=<Height> : Sets the height of the thumbnail.
Usage:
Sent via HTTP POST to /cool/get-thumbnail with the document file.
Optionally, specify a target to generate a thumbnail for a specific element (e.g., a table, image, or heading).
https://sdk.collaboraonline.com/docs/linking_api.html?highlight=thumbnail
rendersearchresult <searchResultXml>
This command generates an image (PNG) of a specific search result within a document.
- <searchResultXml>: The XML file representing the search results, detailing the position of the search hits within the document.
This adds a new service render-search-result, which renders an
image of the position where, the search fund a hit. The search
result contains the information in which object or paragraph,
which is just the node id and node type from the document model.
The service takes the document and the search result (xml file)
as the input and returns a PNG image as the output.
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