Cleanup and extend protocol docs.
Change-Id: I51763f7e362c0aa048fe2d484f589d6558a67008
This commit is contained in:
parent
d2465f6915
commit
6f9ad8759b
1 changed files with 54 additions and 26 deletions
|
@ -27,19 +27,50 @@ Document conversion:
|
||||||
WOPI Extensions
|
WOPI Extensions
|
||||||
===============
|
===============
|
||||||
|
|
||||||
LibreOffice Online uses WOPI protocol to interact with hosts who wants to
|
LibreOffice Online uses a WOPI-like protocol to interact with hosts who
|
||||||
integrate LibreOffice Online in them.
|
want to integrate LibreOffice Online in them.
|
||||||
|
|
||||||
Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for detailed
|
Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for further
|
||||||
information. This documentation only mentions extensions to upstream WOPI protocol,
|
details on the protocol's inspiration.
|
||||||
WOPI extensions, that are implemented by LibreOffice Online backend in addition to
|
|
||||||
upstream WOPI protocol.
|
|
||||||
|
|
||||||
(Please note that upstream WOPI implementation is also not 100% complete)
|
|
||||||
|
|
||||||
CheckFileInfo response properties
|
CheckFileInfo response properties
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
|
BaseFileName
|
||||||
|
A string containing the basename of the file, omitting its path.
|
||||||
|
|
||||||
|
DisablePrint
|
||||||
|
Disables print functionality in libreoffice online backend. If
|
||||||
|
true, HidePrintOption is assumed to be true
|
||||||
|
|
||||||
|
OwnerID
|
||||||
|
A programmatic string identifier for the owner of the file.
|
||||||
|
|
||||||
|
PostMessageOrigin
|
||||||
|
A string for the domain the host page sends/receives
|
||||||
|
PostMessages from, we only listen to messages from this domain.
|
||||||
|
|
||||||
|
Size
|
||||||
|
Size of the file in bytes (64bit)
|
||||||
|
|
||||||
|
UserCanWrite
|
||||||
|
A boolean flag, indicating whether the user has permission
|
||||||
|
to edit and/or over-write the file. If not set PutFile will fail.
|
||||||
|
|
||||||
|
UserCanNotWriteRelative
|
||||||
|
A boolean flag indiciating that the user cannot Save-As on
|
||||||
|
this server, so PutFileRelative will fail.
|
||||||
|
|
||||||
|
UserId
|
||||||
|
A programmatic string identifier of the user.
|
||||||
|
|
||||||
|
UserFriendlyName
|
||||||
|
A string representing the name of the user for display in the UI.
|
||||||
|
|
||||||
|
|
||||||
|
CheckFileInfo extended response properties
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
HidePrintOption
|
HidePrintOption
|
||||||
If set to true, hides the print option from the filemenu bar in the UI
|
If set to true, hides the print option from the filemenu bar in the UI
|
||||||
|
|
||||||
|
@ -50,10 +81,6 @@ HideSaveOption
|
||||||
HideExportOption
|
HideExportOption
|
||||||
Hides 'Download as' option in the file menubar
|
Hides 'Download as' option in the file menubar
|
||||||
|
|
||||||
DisablePrint
|
|
||||||
Disables print functionality in libreoffice online backend. If true,
|
|
||||||
HidePrintOption is assumed to be true
|
|
||||||
|
|
||||||
DisableExport
|
DisableExport
|
||||||
Disables export functionality in backend. If set to true,
|
Disables export functionality in backend. If set to true,
|
||||||
HideExportOption is assumed to be true
|
HideExportOption is assumed to be true
|
||||||
|
@ -87,8 +114,9 @@ WatermarkText
|
||||||
If set to a non-empty string, is used for rendering a watermark-like
|
If set to a non-empty string, is used for rendering a watermark-like
|
||||||
text on each tile of the document
|
text on each tile of the document
|
||||||
|
|
||||||
Note that it is possible to just hide print,save,export options while still
|
Note that it is possible to just hide print, save, export options
|
||||||
being able to access them from WOPI hosts using PostMessage API (see loleaflet/reference.html)
|
while still being able to access them from other hosts using
|
||||||
|
PostMessage API (see loleaflet/reference.html)
|
||||||
|
|
||||||
Alternative authentication possibility
|
Alternative authentication possibility
|
||||||
--------------------------------------
|
--------------------------------------
|
||||||
|
@ -100,8 +128,8 @@ The 'access_header' can be eg. of a form
|
||||||
|
|
||||||
Authorization: Basic abcd1234==
|
Authorization: Basic abcd1234==
|
||||||
|
|
||||||
This header is then used in all the WOPI calls like PutFile, GetFile or
|
This header is then used in all the protocol calls like PutFile,
|
||||||
CheckFileInfo, allowing Basic authentication to work.
|
GetFile or CheckFileInfo, allowing Basic authentication to work.
|
||||||
|
|
||||||
PutFile headers
|
PutFile headers
|
||||||
---------------
|
---------------
|
||||||
|
@ -125,22 +153,22 @@ will have the value 'true' when the PutFile is triggered by autosave, and
|
||||||
Detecting external document change
|
Detecting external document change
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
The locking part of the WOPI protocol is left out, because it goes against how
|
Locking is omitted from our WOPI-like protocol since it goes against
|
||||||
the files are being used in many EFSS solutions. Instead, LibreOffice Online
|
common EFSS solutions usage. Instead, LibreOffice Online uses
|
||||||
uses timestamps to detect document changes.
|
timestamps to detect document changes.
|
||||||
|
|
||||||
When the document is updated in your storage while being edited in LibreOffice
|
When the document is updated in your storage while being edited in
|
||||||
Online and there are unsaved changes, we detect it as soon as possible and ask
|
LibreOffice Online and there are unsaved changes, we detect it as soon
|
||||||
the user if he/she would like to overwrite the changes or reload the new
|
as possible and ask the user if he/she would like to overwrite the
|
||||||
document from the storage.
|
changes or reload the new document from the storage.
|
||||||
|
|
||||||
In case there are no unsaved changes, we reload the new document without
|
In case there are no unsaved changes, we reload the new document without
|
||||||
asking the user.
|
asking the user.
|
||||||
|
|
||||||
To support this feature, wopi host implementation has to specify
|
To support this feature, the host implementation has to specify
|
||||||
LastModifiedTime field in both CheckFileInfo and PutFile calls.
|
LastModifiedTime field in both CheckFileInfo and PutFile calls.
|
||||||
|
|
||||||
Additionally, WOPI hosts must check for a header in PutFile response:
|
Additionally, hosts must check for a header in PutFile response:
|
||||||
|
|
||||||
X-LOOL-WOPI-Timestamp
|
X-LOOL-WOPI-Timestamp
|
||||||
|
|
||||||
|
@ -150,7 +178,7 @@ is present and its value does not match the file’s modified time in storage,
|
||||||
it indicates that document being edited is not the one that is present in the
|
it indicates that document being edited is not the one that is present in the
|
||||||
storage.
|
storage.
|
||||||
|
|
||||||
WOPI hosts should not save the file to storage in such cases and respond with
|
Hosts should not save the file to storage in such cases and respond with
|
||||||
HTTP 409 along with LibreOffice Online specific status code:
|
HTTP 409 along with LibreOffice Online specific status code:
|
||||||
|
|
||||||
HTTP 409 with JSON:
|
HTTP 409 with JSON:
|
||||||
|
|
Loading…
Reference in a new issue