From 43ca2eb7bc0eeef74ac497a8477a59fbcd63e31b Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 13 Apr 2023 14:30:30 +0200 Subject: [PATCH 01/20] Improve webdav documentation Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 282 +++++++++++++++--- 1 file changed, 235 insertions(+), 47 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 26a668d4a..57d01eda2 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -5,51 +5,73 @@ Basic APIs ========== This document provides a quick overview of the WebDAV operations supported in Nextcloud, to keep things readable it won't go into many details -for each operation, further information for each operation can be found in the corresponding rfc where applicable +for each operation, further information for each operation can be found in the corresponding RFC where applicable. WebDAV basics ------------- The base url for all WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`. -All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies. +All requests need to provide authentication information, either as a basic auth header or by passing a set of valid session cookies. -If your Nextcloud installation uses an external auth provider (such as an OIDC server) you may have to create an app password. To do that browse to your user Settings > Security and create one. It will provide a username and password which you can use within the Basic Auth header. +If your Nextcloud installation uses an external auth provider (such as an OIDC server) you may have to create an app password. To do that, go to your personal security settings and create one. It will provide a username and password which you can use within the Basic Auth header. -Testing requests with curl --------------------------- +Testing requests +---------------- -All WebDAV requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PROPFIND`, :code:`PUT`, etc) and setting a request body where needed. +With curl +^^^^^^^^^ -For example: you can perform a :code:`PROPFIND` request to find files in a folder using +All WebDAV requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PROPFIND`, :code:`PUT`, ...) and providing a request body where needed. +For example: you can perform a :code:`PROPFIND` request to find files in a folder using: .. code-block:: bash - curl -u username:password 'https://cloud.example.com/remote.php/dav/files/username/folder' -X PROPFIND --data ' - - - - - - - - - - ' + curl 'https://cloud.example.com/remote.php/dav/files/username/folder' \ + --user username:password \ + --request PROPFIND \ + --data ' + + + + + + + + + + ' +Making requests in JavaScript +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Listing folders (rfc4918_) --------------------------- +Here is a JavaScript code sample to get you started: -The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder. +.. code-block:: javascript -.. code:: + import { createClient } from 'webdav' + import { generateRemoteUrl } from '@nextcloud/router' + import { getCurrentUser } from '@nextcloud/auth' - PROPFIND remote.php/dav/files/user/path/to/folder + const client = createClient(generateRemoteUrl('dav')) + const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { + details: true, + data: ` + + + + + + + + + + `, + }) Requesting properties -^^^^^^^^^^^^^^^^^^^^^ +--------------------- By default, a :code:`PROPFIND` request will only return a small number of properties for each file: last modified date, file size, whether it's a folder, etag and mime type. @@ -80,26 +102,168 @@ You can request additional properties by sending a request body with the :code:` The following properties are supported: -- :code:`{DAV:}getlastmodified` -- :code:`{DAV:}getetag` -- :code:`{DAV:}getcontenttype` -- :code:`{DAV:}resourcetype` -- :code:`{DAV:}getcontentlength` -- :code:`{http://owncloud.org/ns}id` The fileid namespaced by the instance id, globally unique -- :code:`{http://owncloud.org/ns}fileid` The unique id for the file within the instance -- :code:`{http://owncloud.org/ns}favorite` -- :code:`{http://owncloud.org/ns}comments-href` -- :code:`{http://owncloud.org/ns}comments-count` -- :code:`{http://owncloud.org/ns}comments-unread` -- :code:`{http://owncloud.org/ns}owner-id` The user id of the owner of a shared file -- :code:`{http://owncloud.org/ns}owner-display-name` The display name of the owner of a shared file -- :code:`{http://owncloud.org/ns}share-types` -- :code:`{http://owncloud.org/ns}checksums` -- :code:`{http://nextcloud.org/ns}has-preview` -- :code:`{http://owncloud.org/ns}size` Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder. -- :code:`{http://nextcloud.org/ns}rich-workspace` this property is provided by the text app -- :code:`{http://nextcloud.org/ns}contained-folder-count` The number of folders directly contained in the folder (not recursively) -- :code:`{http://nextcloud.org/ns}contained-file-count` The number of files directly contained in the folder (not recursively) + +getlastmodified +^^^^^^^^^^^^^^^ +- Id: ``{DAV:}getlastmodified`` +- Property: ```` +- Description: The latest modification time. +- Example: ``"Wed, 20 Jul 2022 05:12:23 GMT"`` + +getetag +^^^^^^^ +- Id: ``{DAV:}getetag`` +- Property: ```` +- Description: The file's etag. +- Example: ``""6436d084d4805""`` + +getcontenttype +^^^^^^^^^^^^^^ +- Id: ``{DAV:}getcontenttype`` +- Property: ```` +- Description: The mime type of the file. +- Example: ``"image/jpeg"`` + +resourcetype +^^^^^^^^^^^^ +- Id: ``{DAV:}resourcetype`` +- Property: ```` +- Description: Specifies the nature of the resource. +- Example: ```` for a folder + +getcontentlength +^^^^^^^^^^^^^^^^ +- Id: ``{DAV:}getcontentlength`` +- Property: ```` +- Description: The size if it is a file. +- Example: ``3030237`` + +id +^^ +- Id: ``{http://owncloud.org/ns}id`` +- Property: ```` +- Description: The fileid namespaced by the instance id, globally unique + +fileid +^^^^^^ +- Id: ``{http://owncloud.org/ns}fileid`` +- Property: ```` +- Description: The unique id for the file within the instance + +permissions +^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}permissions`` +- Property: ```` +- Description: The permissions that the user has over the file. ``true`` or ``false`` + +mount-type +^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}mount-type`` +- Property: ```` +- Description: The type of mount. +- Example: ``''`` = local; ``'shared'`` = received share; ``'external'`` or ``'external-session'`` = external storage + +is-encrypted +^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}is-encrypted`` +- Property: ```` +- Description: Whether the file is end-to-end encrypted + +favorite +^^^^^^^^ +- Id: ``{http://owncloud.org/ns}favorite`` +- Property: ```` +- Description: The favorite state. +- Example: ``0`` for not favourited, ``1`` for favourited + +comments-href +^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-href`` +- Property: ```` +- Description: The DAV endpoint to fetch teh comments + +comments-count +^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-count`` +- Property: ```` +- Description: The number of comments + +comments-unread +^^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-unread`` +- Property: ```` +- Description: The number of unread comments + +owner-id +^^^^^^^^ +- Id: ``{http://owncloud.org/ns}owner-id`` +- Property: ```` +- Description: The user id of the owner of a shared file + +owner-display-name +^^^^^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}owner-display-name`` +- Property: ```` +- Description: The display name of the owner of a shared file + +share-types +^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}share-types`` +- Property: ```` +- Description: The list of type share. +- Example: ``0`` = user; ``1`` = group; ``3`` = public link; ``4`` = email; ``6`` = federated cloud share; ``7`` = circle; ``10`` = Talk conversation + +share-permissions +^^^^^^^^^^^^^^^^^ +- Id: ``{http://open-collaboration-services.org/ns}share-permissions`` +- Property: ``{http://open-collaboration-services.org/ns}share-permissions`` +- Description: The permissions that the user has over the share. +- Example: Create = ``4``; Read = ``1``; Update = ``2``; Delete = ``8``; Share = ``16``; All = ``31``; + +checksums +^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}checksums`` +- Property: ```` +- Description: +has-preview +^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}has-preview`` +- Property: ```` +- Description: Whether a preview of the file is available + +size +^^^^ +- Id: ``{http://owncloud.org/ns}size`` +- Property: ```` +- Description: Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder + +rich-workspace +^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}rich-workspace`` +- Property: ```` +- Description: This property is provided by the text app + +contained-folder-count +^^^^^^^^^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}contained-folder-count`` +- Property: ```` +- Description: The number of folders directly contained in the folder (not recursively) + +contained-file-count +^^^^^^^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}contained-file-count`` +- Property: ```` +- Description: The number of files directly contained in the folder (not recursively) + + +Listing folders (rfc4918_) +-------------------------- + +The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder. + +.. code:: + + PROPFIND remote.php/dav/files/user/path/to/folder Getting properties for just the folder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -118,7 +282,7 @@ A file can be downloaded by sending a :code:`GET` request to the WebDAV url of t Uploading files --------------- -A file can be uploading by sending a :code:`PUT` request to the file and sending the raw file contents as the request body. +A file can be uploaded by sending a :code:`PUT` request to the file and sending the raw file contents as the request body. .. code:: @@ -144,7 +308,7 @@ A file or folder can be deleted by sending a :code:`DELETE` request to the file DELETE remote.php/dav/files/user/path/to/file -When deleting a folder, it's contents will be deleted recursively. +When deleting a folder, its contents will be deleted recursively. Moving files and folders (rfc4918_) ----------------------------------- @@ -187,7 +351,7 @@ A file or folder can be marked as favorite by sending a :code:`PROPPATCH` reques -Setting the :code:`oc:favorite` property to 1 marks a file as favorite, setting it to 0 un-marks it as favorite. +Setting the :code:`oc:favorite` property to ``1`` marks a file as favorite, setting it to ``0`` un-marks it as favorite. Listing favorites ----------------- @@ -209,3 +373,27 @@ File properties can be requested by adding a :code:`` element to the re When listing favorites, the request will find all favorites in the folder recursively, all favorites for a user can be found by sending the request to :code:`remote.php/dav/files/user` .. _rfc4918: https://tools.ietf.org/html/rfc4918 + + +Special Headers +--------------- + +Request Headers +^^^^^^^^^^^^^^^ + +You can set some special headers that Nextcloud will interpret. + +- ``X-OC-MTIME``: allow to specify a mtime. The response will contain the header ``X-OC-MTime: accepted`` if the mtime was accepted. +- ``X-OC-CTIME``: allow to specify a creation time. The response will contain the header ``X-OC-CTime: accepted`` if the ctime was accepted. +- ``OC-CHECKSUM``: allow to specify a checksum. +- ``X-HASH``: allow to request the file's hash from the server. Possible values are ``md5``, ``sha1``, and ``sha256``. The server will return the hash in a header named either ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. +- ``OC-CHUNKED``: specify that the sent data is part of a chunk upload. +- ``OC-Total-Length``: contains the total size of the file during a chunk upload. This allow the server to abort faster if the remaining user's quota is not enough. + +Response Headers +---------------- + +Nextcloud will answer with + +- ``OC-Etag``: On creation, move and copy, the response contain the etag of the file. +- ``OC-FileId``: On creation, move and copy, the response contain the fileid of the file. Format: ````. Example: ``"00000259oczn5x60nrdu"`` From 4b483ec1cd145b1c575be1bd7bc82246189fa418 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 13 Apr 2023 16:49:50 +0200 Subject: [PATCH 02/20] Use table formatting for dav properties and headers Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 265 +++++++----------- 1 file changed, 106 insertions(+), 159 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 57d01eda2..8a664bf65 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -102,158 +102,81 @@ You can request additional properties by sending a request body with the :code:` The following properties are supported: ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| Property | Description | Example | ++===============================+===================================================+=============================================+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The permissions that the user has over the file. | ``true`` or ``false`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The number of comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The list of type share. | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``10`` = Talk conversation | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The permissions that the user has over the share. | | ``4`` = Create | +| | | | ``1`` = Read | +| | | | ``2`` = Update | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Whether a preview of the file is available | ``true`` or ``false`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | Unlike :code:`getcontentlength`, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | This property is provided by the text app. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | The number of files directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ -getlastmodified -^^^^^^^^^^^^^^^ -- Id: ``{DAV:}getlastmodified`` -- Property: ```` -- Description: The latest modification time. -- Example: ``"Wed, 20 Jul 2022 05:12:23 GMT"`` -getetag -^^^^^^^ -- Id: ``{DAV:}getetag`` -- Property: ```` -- Description: The file's etag. -- Example: ``""6436d084d4805""`` - -getcontenttype -^^^^^^^^^^^^^^ -- Id: ``{DAV:}getcontenttype`` -- Property: ```` -- Description: The mime type of the file. -- Example: ``"image/jpeg"`` - -resourcetype -^^^^^^^^^^^^ -- Id: ``{DAV:}resourcetype`` -- Property: ```` -- Description: Specifies the nature of the resource. -- Example: ```` for a folder - -getcontentlength -^^^^^^^^^^^^^^^^ -- Id: ``{DAV:}getcontentlength`` -- Property: ```` -- Description: The size if it is a file. -- Example: ``3030237`` - -id -^^ -- Id: ``{http://owncloud.org/ns}id`` -- Property: ```` -- Description: The fileid namespaced by the instance id, globally unique - -fileid -^^^^^^ -- Id: ``{http://owncloud.org/ns}fileid`` -- Property: ```` -- Description: The unique id for the file within the instance - -permissions -^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}permissions`` -- Property: ```` -- Description: The permissions that the user has over the file. ``true`` or ``false`` - -mount-type -^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}mount-type`` -- Property: ```` -- Description: The type of mount. -- Example: ``''`` = local; ``'shared'`` = received share; ``'external'`` or ``'external-session'`` = external storage - -is-encrypted -^^^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}is-encrypted`` -- Property: ```` -- Description: Whether the file is end-to-end encrypted - -favorite -^^^^^^^^ -- Id: ``{http://owncloud.org/ns}favorite`` -- Property: ```` -- Description: The favorite state. -- Example: ``0`` for not favourited, ``1`` for favourited - -comments-href -^^^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}comments-href`` -- Property: ```` -- Description: The DAV endpoint to fetch teh comments - -comments-count -^^^^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}comments-count`` -- Property: ```` -- Description: The number of comments - -comments-unread -^^^^^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}comments-unread`` -- Property: ```` -- Description: The number of unread comments - -owner-id -^^^^^^^^ -- Id: ``{http://owncloud.org/ns}owner-id`` -- Property: ```` -- Description: The user id of the owner of a shared file - -owner-display-name -^^^^^^^^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}owner-display-name`` -- Property: ```` -- Description: The display name of the owner of a shared file - -share-types -^^^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}share-types`` -- Property: ```` -- Description: The list of type share. -- Example: ``0`` = user; ``1`` = group; ``3`` = public link; ``4`` = email; ``6`` = federated cloud share; ``7`` = circle; ``10`` = Talk conversation - -share-permissions -^^^^^^^^^^^^^^^^^ -- Id: ``{http://open-collaboration-services.org/ns}share-permissions`` -- Property: ``{http://open-collaboration-services.org/ns}share-permissions`` -- Description: The permissions that the user has over the share. -- Example: Create = ``4``; Read = ``1``; Update = ``2``; Delete = ``8``; Share = ``16``; All = ``31``; - -checksums -^^^^^^^^^ -- Id: ``{http://owncloud.org/ns}checksums`` -- Property: ```` -- Description: -has-preview -^^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}has-preview`` -- Property: ```` -- Description: Whether a preview of the file is available - -size -^^^^ -- Id: ``{http://owncloud.org/ns}size`` -- Property: ```` -- Description: Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder - -rich-workspace -^^^^^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}rich-workspace`` -- Property: ```` -- Description: This property is provided by the text app - -contained-folder-count -^^^^^^^^^^^^^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}contained-folder-count`` -- Property: ```` -- Description: The number of folders directly contained in the folder (not recursively) - -contained-file-count -^^^^^^^^^^^^^^^^^^^^ -- Id: ``{http://nextcloud.org/ns}contained-file-count`` -- Property: ```` -- Description: The number of files directly contained in the folder (not recursively) Listing folders (rfc4918_) @@ -383,17 +306,41 @@ Request Headers You can set some special headers that Nextcloud will interpret. -- ``X-OC-MTIME``: allow to specify a mtime. The response will contain the header ``X-OC-MTime: accepted`` if the mtime was accepted. -- ``X-OC-CTIME``: allow to specify a creation time. The response will contain the header ``X-OC-CTime: accepted`` if the ctime was accepted. -- ``OC-CHECKSUM``: allow to specify a checksum. -- ``X-HASH``: allow to request the file's hash from the server. Possible values are ``md5``, ``sha1``, and ``sha256``. The server will return the hash in a header named either ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. -- ``OC-CHUNKED``: specify that the sent data is part of a chunk upload. -- ``OC-Total-Length``: contains the total size of the file during a chunk upload. This allow the server to abort faster if the remaining user's quota is not enough. ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| Header | Description | Example | ++=================+=================================================================+==================================+ +| X-OC-MTime | | Allow to specify a mtime. | ``1675789581`` | +| | | The response will contain the header ``X-OC-MTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-CTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| OC-Checksum | Allow to specify a checksum. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``sha256`` | +| | | The server will return the hash in a header named either: | | +| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| OC-Chunked | Specify that the sent data is part of a chunk upload. | ``true`` | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | +| | | This allow the server to abort faster if the remaining | | +| | | user's quota is not enough. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ Response Headers ---------------- -Nextcloud will answer with +Nextcloud will sometime answer with the following headers: -- ``OC-Etag``: On creation, move and copy, the response contain the etag of the file. -- ``OC-FileId``: On creation, move and copy, the response contain the fileid of the file. Format: ````. Example: ``"00000259oczn5x60nrdu"`` ++-----------+------------------------------------------------+-----------------------------------------+ +| Header | Description | Example | ++===========+================================================+=========================================+ +| OC-Etag | | On creation, move and copy, | ``"50ef2eba7b74aa84feff013efee2a5ef"`` | +| | | the response contain the etag of the file. | | ++-----------+------------------------------------------------+-----------------------------------------+ +| OC-FileId | | On creation, move and copy, | | Format: ````. | +| | | the response contain the fileid of the file. | | Example: ``00000259oczn5x60nrdu`` | ++-----------+------------------------------------------------+-----------------------------------------+ From b4e7d2c96f6697e39d717fb3a0cc156166b2dc0c Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 13 Apr 2023 17:31:22 +0200 Subject: [PATCH 03/20] Add more share types Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 8a664bf65..ce822cd46 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -149,7 +149,12 @@ The following properties are supported: | | | | ``4`` = Email | | | | | ``6`` = Federated cloud share | | | | | ``7`` = Circle | +| | | | ``8`` = Guest | +| | | | ``9`` = Remote group | +| | | | ``7`` = Circle | | | | | ``10`` = Talk conversation | +| | | | ``12`` = Deck | +| | | | ``15`` = Science mesh | +-------------------------------+---------------------------------------------------+---------------------------------------------+ | | The permissions that the user has over the share. | | ``4`` = Create | | | | | ``1`` = Read | From bb5f5a29510604cde38a205f15624e40e9e56fa1 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 13 Apr 2023 18:51:38 +0200 Subject: [PATCH 04/20] Add information about namespaces Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 33 +++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index ce822cd46..23ac20210 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -100,7 +100,36 @@ You can request additional properties by sending a request body with the :code:` -The following properties are supported: +A note about namespaces +^^^^^^^^^^^^^^^^^^^^^^^ + +When building the body of your DAV request, you will request properties that are available under specific namespace. +It is usual to declare shortcuts for those namespace in the ``d:propfind`` element of the body. + +Here is the list of available namespace: + +========================================= ======== + Namespace Shortcut +========================================= ======== +DAV: d +http://owncloud.org/ns oc +http://nextcloud.org/ns nc +http://open-collaboration-services.org/ns ocs +========================================= ======== + +And here is how it should look in the body of your DAV request: + +.. code-block:: xml + + + + +Supported properties +^^^^^^^^^^^^^^^^^^^^ +-------------------------------+---------------------------------------------------+---------------------------------------------+ | Property | Description | Example | @@ -182,8 +211,6 @@ The following properties are supported: +-------------------------------+---------------------------------------------------+---------------------------------------------+ - - Listing folders (rfc4918_) -------------------------- From 385357ff8f44814a3558cbc2b8d76d82f61aac98 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 17 Apr 2023 17:53:02 +0200 Subject: [PATCH 05/20] Add more props and improve descriptions and examples Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 254 ++++++++++-------- 1 file changed, 141 insertions(+), 113 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 23ac20210..e830ede7a 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -32,14 +32,14 @@ For example: you can perform a :code:`PROPFIND` request to find files in a folde --user username:password \ --request PROPFIND \ --data ' - - - - - - - - + + + + + + + + ' @@ -58,8 +58,8 @@ Here is a JavaScript code sample to get you started: const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { details: true, data: ` - - + + @@ -115,6 +115,7 @@ DAV: d http://owncloud.org/ns oc http://nextcloud.org/ns nc http://open-collaboration-services.org/ns ocs +http://open-cloud-mesh.org/ns ocm ========================================= ======== And here is how it should look in the body of your DAV request: @@ -127,88 +128,116 @@ And here is how it should look in the body of your DAV request: xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns" xmlns:ocs="http://open-collaboration-services.org/ns"> + xmlns:ocm="http://open-cloud-mesh.org/ns"> Supported properties ^^^^^^^^^^^^^^^^^^^^ -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| Property | Description | Example | -+===============================+===================================================+=============================================+ -| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The file's etag. | ``""6436d084d4805""`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The mime type of the file. | ``"image/jpeg"`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | Specifies the nature of the resource. | ```` for a folder | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The size if it is a file. | ``3030237`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | | The fileid namespaced by the instance id. | | -| | | Globally unique. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The unique id for the file within the instance. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The permissions that the user has over the file. | ``true`` or ``false`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The type of mount. | | ``''`` = local | -| | | | ``'shared'`` = received share | -| | | | ``'external'`` = external storage | -| | | | ``'external-session'`` = external storage | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | -| | | | ``1`` for ``true`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The favorite state. | | ``0`` for not favourited | -| | | | ``1`` for favourited | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The DAV endpoint to fetch the comments. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The number of comments. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The number of unread comments. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The user id of the owner of a shared file. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The display name of the owner of a shared file. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The list of type share. | | ``0`` = User | -| | | | ``1`` = Group | -| | | | ``3`` = Public link | -| | | | ``4`` = Email | -| | | | ``6`` = Federated cloud share | -| | | | ``7`` = Circle | -| | | | ``8`` = Guest | -| | | | ``9`` = Remote group | -| | | | ``7`` = Circle | -| | | | ``10`` = Talk conversation | -| | | | ``12`` = Deck | -| | | | ``15`` = Science mesh | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | The permissions that the user has over the share. | | ``4`` = Create | -| | | | ``1`` = Read | -| | | | ``2`` = Update | -| | | | ``8`` = Delete | -| | | | ``16`` = Share | -| | | | ``31`` = All | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | Whether a preview of the file is available | ``true`` or ``false`` | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | | Unlike :code:`getcontentlength`, | | -| | | this property also works | | -| | | for folders, reporting the size | | -| | | of everything in the folder. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | This property is provided by the text app. | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | | The number of folders directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ -| | | The number of files directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+---------------------------------------------------+---------------------------------------------+ ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| Property | Description | Example | ++===============================+==================================================+=============================================+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The URL to download the file. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The permissions that the user has over the file. | | S: Shared | +| | | | R: Shareable | +| | | | M: Mounted | +| | | | G: Readable | +| | | | D: Deletable | +| | | | NV: Updateable, Renameable, Moveable | +| | | | W: Updateable (file) | +| | | | CK: Creatable | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'group'`` = group folder | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | List of user specified tags. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The number of comments. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The list of type share. | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``8`` = Guest | +| | | | ``9`` = Remote group | +| | | | ``10`` = Talk conversation | +| | | | ``12`` = Deck | +| | | | ``15`` = Science mesh | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | The permissions that the | | ``1`` = Read | +| | | user has over the share. | | ``2`` = Update | +| | | | ``4`` = Create | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | The permissions that the | ``share``, ``read``, ``write`` | +| | | user has over the share. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The list of share recipient. | | - id | +| | | | - display-name | +| | | | - share type | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | Whether a preview of the file is available. | ``true`` or ``false`` | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | Unlike ```getcontentlength``, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The workspace file. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | The content of the workspace file. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | Date this file was uploaded. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | Share note. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | The number of files directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ +| | | Used by the clients to find out | | +| | | if a backup has been restored. | | ++-------------------------------+--------------------------------------------------+---------------------------------------------+ Listing folders (rfc4918_) @@ -338,35 +367,34 @@ Request Headers You can set some special headers that Nextcloud will interpret. -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| Header | Description | Example | -+=================+=================================================================+==================================+ -| X-OC-MTime | | Allow to specify a mtime. | ``1675789581`` | -| | | The response will contain the header ``X-OC-MTime: accepted`` | | -| | | if the mtime was accepted. | | -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | -| | | The response will contain the header ``X-OC-CTime: accepted`` | | -| | | if the mtime was accepted. | | -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| OC-Checksum | Allow to specify a checksum. | | -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``sha256`` | -| | | The server will return the hash in a header named either: | | -| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. | | -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| OC-Chunked | Specify that the sent data is part of a chunk upload. | ``true`` | -+-----------------+-----------------------------------------------------------------+----------------------------------+ -| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | -| | | This allow the server to abort faster if the remaining | | -| | | user's quota is not enough. | | -+-----------------+-----------------------------------------------------------------+----------------------------------+ ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| Header | Description | Example | ++=================+=================================================================+==========================================+ +| X-OC-MTime | | Allow to specify a modification time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-MTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-CTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| OC-Checksum | | A list of space-separated checksum | ``md5:04c36b75222cd9fd47f2607333029106`` | +| | | that will be stored in the DB. | | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``sha256`` | +| | | The server will return the hash in a header named either: | | +| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. | | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| OC-Chunked | Specify that the sent data is part of a chunk upload. | ``true`` | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ +| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | +| | | This allow the server to abort faster if the remaining | | +| | | user's quota is not enough. | | ++-----------------+-----------------------------------------------------------------+------------------------------------------+ Response Headers ---------------- -Nextcloud will sometime answer with the following headers: - +-----------+------------------------------------------------+-----------------------------------------+ | Header | Description | Example | +===========+================================================+=========================================+ From 62f63a266847ea1cd590398a16a4ffdecf1c6c72 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 20 Apr 2023 09:27:16 +0200 Subject: [PATCH 06/20] Improve OC-Checksum description Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index e830ede7a..818f38ae6 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -378,8 +378,8 @@ You can set some special headers that Nextcloud will interpret. | | | The response will contain the header ``X-OC-CTime: accepted`` | | | | | if the mtime was accepted. | | +-----------------+-----------------------------------------------------------------+------------------------------------------+ -| OC-Checksum | | A list of space-separated checksum | ``md5:04c36b75222cd9fd47f2607333029106`` | -| | | that will be stored in the DB. | | +| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` | +| | | The server will not do any sort of validation. | | +-----------------+-----------------------------------------------------------------+------------------------------------------+ | X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``sha256`` | | | | The server will return the hash in a header named either: | | From adeae621d226352af38de945562c7fa1946c36a3 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 24 Apr 2023 14:48:23 +0200 Subject: [PATCH 07/20] Add quota and share-attributes props Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 219 +++++++++--------- 1 file changed, 114 insertions(+), 105 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 818f38ae6..f43a42d16 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -133,111 +133,120 @@ And here is how it should look in the body of your DAV request: Supported properties ^^^^^^^^^^^^^^^^^^^^ -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| Property | Description | Example | -+===============================+==================================================+=============================================+ -| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The file's etag. | ``""6436d084d4805""`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The mime type of the file. | ``"image/jpeg"`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | Specifies the nature of the resource. | ```` for a folder | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The size if it is a file. | ``3030237`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | The fileid namespaced by the instance id. | | -| | | Globally unique. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The unique id for the file within the instance. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The URL to download the file. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The permissions that the user has over the file. | | S: Shared | -| | | | R: Shareable | -| | | | M: Mounted | -| | | | G: Readable | -| | | | D: Deletable | -| | | | NV: Updateable, Renameable, Moveable | -| | | | W: Updateable (file) | -| | | | CK: Creatable | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The type of mount. | | ``''`` = local | -| | | | ``'shared'`` = received share | -| | | | ``'group'`` = group folder | -| | | | ``'external'`` = external storage | -| | | | ``'external-session'`` = external storage | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | -| | | | ``1`` for ``true`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | List of user specified tags. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The favorite state. | | ``0`` for not favourited | -| | | | ``1`` for favourited | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The DAV endpoint to fetch the comments. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The number of comments. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The number of unread comments. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The user id of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The display name of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The list of type share. | | ``0`` = User | -| | | | ``1`` = Group | -| | | | ``3`` = Public link | -| | | | ``4`` = Email | -| | | | ``6`` = Federated cloud share | -| | | | ``7`` = Circle | -| | | | ``8`` = Guest | -| | | | ``9`` = Remote group | -| | | | ``10`` = Talk conversation | -| | | | ``12`` = Deck | -| | | | ``15`` = Science mesh | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | The permissions that the | | ``1`` = Read | -| | | user has over the share. | | ``2`` = Update | -| | | | ``4`` = Create | -| | | | ``8`` = Delete | -| | | | ``16`` = Share | -| | | | ``31`` = All | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | The permissions that the | ``share``, ``read``, ``write`` | -| | | user has over the share. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The list of share recipient. | | - id | -| | | | - display-name | -| | | | - share type | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | Whether a preview of the file is available. | ``true`` or ``false`` | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | Unlike ```getcontentlength``, | | -| | | this property also works | | -| | | for folders, reporting the size | | -| | | of everything in the folder. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The workspace file. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | The content of the workspace file. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | Date this file was uploaded. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | Share note. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | The number of folders directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | The number of files directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ -| | | Used by the clients to find out | | -| | | if a backup has been restored. | | -+-------------------------------+--------------------------------------------------+---------------------------------------------+ ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| Property | Description | Example | ++===============================+==================================================+=======================================================================+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The URL to download the file. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The permissions that the user has over the file. | | S: Shared | +| | | | R: Shareable | +| | | | M: Mounted | +| | | | G: Readable | +| | | | D: Deletable | +| | | | NV: Updateable, Renameable, Moveable | +| | | | W: Updateable (file) | +| | | | CK: Creatable | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'group'`` = group folder | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | List of user specified tags. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The number of comments. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The list of type share. | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``8`` = Guest | +| | | | ``9`` = Remote group | +| | | | ``10`` = Talk conversation | +| | | | ``12`` = Deck | +| | | | ``15`` = Science mesh | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | The permissions that the | | ``1`` = Read | +| | | user has over the share. | | ``2`` = Update | +| | | | ``4`` = Create | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | The permissions that the | ``share``, ``read``, ``write`` | +| | | user has over the share. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | User set attributes. | ``[{ "scope" => , "key" => , "enabled" => }]`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The list of share recipient. | | - id | +| | | | - display-name | +| | | | - share type | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Whether a preview of the file is available. | ``true`` or ``false`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | Unlike ```getcontentlength``, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Amount of bytes used in the folder. | ``3950773`` | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Amount of available bytes in the folder. | | ``3950773`` | +| | | | ``-1`` Uncomputed free space. | +| | | | ``-2`` Unknown free space. | +| | | | ``-3`` Unlimited free space. | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The workspace file. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | The content of the workspace file. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Date this file was uploaded. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | Share note. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | The number of files directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ +| | | Used by the clients to find out | | +| | | if a backup has been restored. | | ++-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ Listing folders (rfc4918_) From 36cd32c66f73344706e193200fed94c580ef1cf0 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 24 Apr 2023 15:14:38 +0200 Subject: [PATCH 08/20] Remove extra ` Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index f43a42d16..446cfac0c 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -218,7 +218,7 @@ Supported properties +-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ | | Whether a preview of the file is available. | ``true`` or ``false`` | +-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | Unlike ```getcontentlength``, | | +| | | Unlike ``getcontentlength``, | | | | | this property also works | | | | | for folders, reporting the size | | | | | of everything in the folder. | | From 726306d988d122d3d6ce8e89f24802a9f127a08f Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 24 Apr 2023 15:54:40 +0200 Subject: [PATCH 09/20] Add more native DAV properties Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 249 ++++++++++-------- 1 file changed, 135 insertions(+), 114 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 446cfac0c..d61f89a73 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -133,120 +133,141 @@ And here is how it should look in the body of your DAV request: Supported properties ^^^^^^^^^^^^^^^^^^^^ -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| Property | Description | Example | -+===============================+==================================================+=======================================================================+ -| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The file's etag. | ``""6436d084d4805""`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The mime type of the file. | ``"image/jpeg"`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Specifies the nature of the resource. | ```` for a folder | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The size if it is a file. | ``3030237`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | The fileid namespaced by the instance id. | | -| | | Globally unique. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The unique id for the file within the instance. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The URL to download the file. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The permissions that the user has over the file. | | S: Shared | -| | | | R: Shareable | -| | | | M: Mounted | -| | | | G: Readable | -| | | | D: Deletable | -| | | | NV: Updateable, Renameable, Moveable | -| | | | W: Updateable (file) | -| | | | CK: Creatable | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The type of mount. | | ``''`` = local | -| | | | ``'shared'`` = received share | -| | | | ``'group'`` = group folder | -| | | | ``'external'`` = external storage | -| | | | ``'external-session'`` = external storage | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | -| | | | ``1`` for ``true`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | List of user specified tags. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The favorite state. | | ``0`` for not favourited | -| | | | ``1`` for favourited | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The DAV endpoint to fetch the comments. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The number of comments. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The number of unread comments. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The user id of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The display name of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The list of type share. | | ``0`` = User | -| | | | ``1`` = Group | -| | | | ``3`` = Public link | -| | | | ``4`` = Email | -| | | | ``6`` = Federated cloud share | -| | | | ``7`` = Circle | -| | | | ``8`` = Guest | -| | | | ``9`` = Remote group | -| | | | ``10`` = Talk conversation | -| | | | ``12`` = Deck | -| | | | ``15`` = Science mesh | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | The permissions that the | | ``1`` = Read | -| | | user has over the share. | | ``2`` = Update | -| | | | ``4`` = Create | -| | | | ``8`` = Delete | -| | | | ``16`` = Share | -| | | | ``31`` = All | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | The permissions that the | ``share``, ``read``, ``write`` | -| | | user has over the share. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | User set attributes. | ``[{ "scope" => , "key" => , "enabled" => }]`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The list of share recipient. | | - id | -| | | | - display-name | -| | | | - share type | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Whether a preview of the file is available. | ``true`` or ``false`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | Unlike ``getcontentlength``, | | -| | | this property also works | | -| | | for folders, reporting the size | | -| | | of everything in the folder. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Amount of bytes used in the folder. | ``3950773`` | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Amount of available bytes in the folder. | | ``3950773`` | -| | | | ``-1`` Uncomputed free space. | -| | | | ``-2`` Unknown free space. | -| | | | ``-3`` Unlimited free space. | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The workspace file. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | The content of the workspace file. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Date this file was uploaded. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | Share note. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | The number of folders directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | The number of files directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ -| | | Used by the clients to find out | | -| | | if a backup has been restored. | | -+-------------------------------+--------------------------------------------------+-----------------------------------------------------------------------+ + + ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| Property | Description | Example | ++===============================+==================================================+==========================================================================+ +| | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The language of the content. | ``en`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | A name suitable for presentation. | ``File name`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Describes the active locks on a resource. | | [ { | +| | | | locktype: ``write`` | +| | | | lockscope: ``exclusive`` | +| | | | depth: ``0`` | +| | | | owner: ``Jane Smith`` | +| | | | timeout: ``Infinite`` | +| | | | locktoken: { href: ``urn:uuid:f81de2ad-7f3d-a1b2-4f3c-`` } | +| | | | lockroot: { href: ``http://www.example.com/container/`` } | +| | | | } ] | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | Provide the lock capabilities | [ { lockscope: ``exclusive``, locktype: ``write`` } ] | +| | | supported by the resource. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The URL to download the file. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The permissions that the user has over the file. | | S: Shared | +| | | | R: Shareable | +| | | | M: Mounted | +| | | | G: Readable | +| | | | D: Deletable | +| | | | NV: Updateable, Renameable, Moveable | +| | | | W: Updateable (file) | +| | | | CK: Creatable | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'group'`` = group folder | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | List of user specified tags. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The number of comments. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The list of type share. | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``8`` = Guest | +| | | | ``9`` = Remote group | +| | | | ``10`` = Talk conversation | +| | | | ``12`` = Deck | +| | | | ``15`` = Science mesh | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | The permissions that the | | ``1`` = Read | +| | | user has over the share. | | ``2`` = Update | +| | | | ``4`` = Create | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | The permissions that the | ``share``, ``read``, ``write`` | +| | | user has over the share. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | User set attributes. | ``[{ "scope" => , "key" => , "enabled" => }]`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The list of share recipient. | | - id | +| | | | - display-name | +| | | | - share type | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Whether a preview of the file is available. | ``true`` or ``false`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | Unlike ``getcontentlength``, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Amount of bytes used in the folder. | ``3950773`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Amount of available bytes in the folder. | | ``3950773`` | +| | | | ``-1`` Uncomputed free space. | +| | | | ``-2`` Unknown free space. | +| | | | ``-3`` Unlimited free space. | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The workspace file. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | The content of the workspace file. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Date this file was uploaded. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Share note. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | The number of files directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | | Used by the clients to find out | | +| | | if a backup has been restored. | | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ Listing folders (rfc4918_) From 9c9b92ff02c0bda5ce80825145f2696b96ef0622 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 24 Apr 2023 16:00:48 +0200 Subject: [PATCH 10/20] Add creation_time property Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index d61f89a73..a232fe2f5 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -140,6 +140,8 @@ Supported properties +===============================+==================================================+==========================================================================+ | | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Same as ``creationdate``, but as a timestamp. | ``0`` | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The file's etag. | ``""6436d084d4805""`` | From 44d4859b555bc225b02ae15abe766af9ad03dbb4 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Mon, 24 Apr 2023 16:09:51 +0200 Subject: [PATCH 11/20] Improve sharees doc Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index a232fe2f5..b0fd9a7b9 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -233,9 +233,7 @@ Supported properties +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | User set attributes. | ``[{ "scope" => , "key" => , "enabled" => }]`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The list of share recipient. | | - id | -| | | | - display-name | -| | | | - share type | +| | The list of share recipient. | ``{ id, display-name, share type }`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ From b1420f2caf964ab2c02a827d9807751fcaa1f9ff Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Wed, 3 May 2023 13:10:17 +0200 Subject: [PATCH 12/20] Improve examples Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 90 ++++++++++--------- 1 file changed, 47 insertions(+), 43 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index b0fd9a7b9..48bfd6ab0 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -58,7 +58,7 @@ Here is a JavaScript code sample to get you started: const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { details: true, data: ` - + @@ -80,7 +80,7 @@ You can request additional properties by sending a request body with the :code:` .. code-block:: xml - + @@ -100,25 +100,25 @@ You can request additional properties by sending a request body with the :code:` -A note about namespaces -^^^^^^^^^^^^^^^^^^^^^^^ +A note about namespaces URI +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When building the body of your DAV request, you will request properties that are available under specific namespace. -It is usual to declare shortcuts for those namespace in the ``d:propfind`` element of the body. +When building the body of your DAV request, you will request properties that are available under specific namespace URI. +It is usual to declare prefixes for those namespace in the ``d:propfind`` element of the body. Here is the list of available namespace: -========================================= ======== - Namespace Shortcut -========================================= ======== +========================================= ====== + URI Prefix +========================================= ====== DAV: d http://owncloud.org/ns oc http://nextcloud.org/ns nc http://open-collaboration-services.org/ns ocs http://open-cloud-mesh.org/ns ocm -========================================= ======== +========================================= ====== -And here is how it should look in the body of your DAV request: +And here is how it should look in your DAV request: .. code-block:: xml @@ -129,19 +129,16 @@ And here is how it should look in the body of your DAV request: xmlns:nc="http://nextcloud.org/ns" xmlns:ocs="http://open-collaboration-services.org/ns"> xmlns:ocm="http://open-cloud-mesh.org/ns"> + ... Supported properties ^^^^^^^^^^^^^^^^^^^^ - - +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | Property | Description | Example | +===============================+==================================================+==========================================================================+ | | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Same as ``creationdate``, but as a timestamp. | ``0`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The file's etag. | ``""6436d084d4805""`` | @@ -156,18 +153,18 @@ Supported properties +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | A name suitable for presentation. | ``File name`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Describes the active locks on a resource. | | [ { | -| | | | locktype: ``write`` | -| | | | lockscope: ``exclusive`` | -| | | | depth: ``0`` | -| | | | owner: ``Jane Smith`` | -| | | | timeout: ``Infinite`` | -| | | | locktoken: { href: ``urn:uuid:f81de2ad-7f3d-a1b2-4f3c-`` } | -| | | | lockroot: { href: ``http://www.example.com/container/`` } | -| | | | } ] | +| | | Dummy endpoint for class 2 WebDAV support. | ```` | +| | | Should return the list of lock, but | | +| | | always return an empty response. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | Provide the lock capabilities | [ { lockscope: ``exclusive``, locktype: ``write`` } ] | -| | | supported by the resource. | | +| | | Dummy endpoint for class 2 WebDAV support. | | ```` | +| | | Always provide the same lock capabilities. | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | | The fileid namespaced by the instance id. | | | | | Globally unique. | | @@ -176,14 +173,16 @@ Supported properties +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The URL to download the file. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The permissions that the user has over the file. | | S: Shared | -| | | | R: Shareable | -| | | | M: Mounted | -| | | | G: Readable | -| | | | D: Deletable | -| | | | NV: Updateable, Renameable, Moveable | -| | | | W: Updateable (file) | -| | | | CK: Creatable | +| | | The permissions that the user has over the | | ``S``: Shared | +| | | file. The value is a string containing letters | | ``R``: Shareable | +| | | for all available permissions. | | ``M``: Mounted | +| | | | ``G``: Readable | +| | | | ``D``: Deletable | +| | | | ``NV``: Updateable, Renameable, Moveable | +| | | | ``W``: Updateable (file) | +| | | | ``CK``: Creatable | ++-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ +| | Same as ``creationdate``, but as a timestamp. | ``0`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The type of mount. | | ``''`` = local | | | | | ``'shared'`` = received share | @@ -194,7 +193,7 @@ Supported properties | | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | | | | | ``1`` for ``true`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | List of user specified tags. | | +| | List of user specified tags. | ``test`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The favorite state. | | ``0`` for not favourited | | | | | ``1`` for favourited | @@ -209,7 +208,8 @@ Supported properties +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The display name of the owner of a shared file. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The list of type share. | | ``0`` = User | +| | XML array of share types. | | ``{shareTypeId}`` | +| | | | ``0`` = User | | | | | ``1`` = Group | | | | | ``3`` = Public link | | | | | ``4`` = Email | @@ -228,14 +228,18 @@ Supported properties | | | | ``16`` = Share | | | | | ``31`` = All | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The permissions that the | ``share``, ``read``, ``write`` | -| | | user has over the share. | | +| | | The permissions that the user has | ``['share', 'read', 'write']`` | +| | | over the share as a JSON array. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | User set attributes. | ``[{ "scope" => , "key" => , "enabled" => }]`` | +| | User set attributes as a JSON array. | ``[{ "scope" => , "key" => , "enabled" => }]`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The list of share recipient. | ``{ id, display-name, share type }`` | +| | The list of share recipient. | | ```` | +| | | | ``alice`` | +| | | | ``Alice`` | +| | | | ``0`` | +| | | | ```` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | A list of checksum. | ``md5:04c36b75222cd9fd47f2607333029106`` | +| | An array of checksums. | ``md5:04c36b75222cd9fd47f2607333029106`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | Whether a preview of the file is available. | ``true`` or ``false`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ @@ -251,11 +255,11 @@ Supported properties | | | | ``-2`` Unknown free space. | | | | | ``-3`` Unlimited free space. | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The workspace file. | | +| | The id of the workspace file. | `3456` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | The content of the workspace file. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Date this file was uploaded. | | +| | Date this file was uploaded. | ``1675789581`` | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ | | Share note. | | +-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ From 140f3775dcdc77e84bd6bca5feba2788c05d1d2c Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Wed, 3 May 2023 16:13:29 +0200 Subject: [PATCH 13/20] Add groupfolders and files_lock properties Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 312 ++++++++++-------- 1 file changed, 173 insertions(+), 139 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 48bfd6ab0..540503191 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -134,145 +134,179 @@ And here is how it should look in your DAV request: Supported properties ^^^^^^^^^^^^^^^^^^^^ -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| Property | Description | Example | -+===============================+==================================================+==========================================================================+ -| | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The file's etag. | ``""6436d084d4805""`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The mime type of the file. | ``"image/jpeg"`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Specifies the nature of the resource. | ```` for a folder | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The size if it is a file. | ``3030237`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The language of the content. | ``en`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | A name suitable for presentation. | ``File name`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | Dummy endpoint for class 2 WebDAV support. | ```` | -| | | Should return the list of lock, but | | -| | | always return an empty response. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | Dummy endpoint for class 2 WebDAV support. | | ```` | -| | | Always provide the same lock capabilities. | | ```` | -| | | | | ```` | -| | | | | ```` | -| | | | | ```` | -| | | | | ```` | -| | | | | ```` | -| | | | | ```` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The fileid namespaced by the instance id. | | -| | | Globally unique. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The unique id for the file within the instance. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The URL to download the file. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The permissions that the user has over the | | ``S``: Shared | -| | | file. The value is a string containing letters | | ``R``: Shareable | -| | | for all available permissions. | | ``M``: Mounted | -| | | | ``G``: Readable | -| | | | ``D``: Deletable | -| | | | ``NV``: Updateable, Renameable, Moveable | -| | | | ``W``: Updateable (file) | -| | | | ``CK``: Creatable | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Same as ``creationdate``, but as a timestamp. | ``0`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The type of mount. | | ``''`` = local | -| | | | ``'shared'`` = received share | -| | | | ``'group'`` = group folder | -| | | | ``'external'`` = external storage | -| | | | ``'external-session'`` = external storage | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | -| | | | ``1`` for ``true`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | List of user specified tags. | ``test`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The favorite state. | | ``0`` for not favourited | -| | | | ``1`` for favourited | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The DAV endpoint to fetch the comments. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The number of comments. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The number of unread comments. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The user id of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The display name of the owner of a shared file. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | XML array of share types. | | ``{shareTypeId}`` | -| | | | ``0`` = User | -| | | | ``1`` = Group | -| | | | ``3`` = Public link | -| | | | ``4`` = Email | -| | | | ``6`` = Federated cloud share | -| | | | ``7`` = Circle | -| | | | ``8`` = Guest | -| | | | ``9`` = Remote group | -| | | | ``10`` = Talk conversation | -| | | | ``12`` = Deck | -| | | | ``15`` = Science mesh | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The permissions that the | | ``1`` = Read | -| | | user has over the share. | | ``2`` = Update | -| | | | ``4`` = Create | -| | | | ``8`` = Delete | -| | | | ``16`` = Share | -| | | | ``31`` = All | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The permissions that the user has | ``['share', 'read', 'write']`` | -| | | over the share as a JSON array. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | User set attributes as a JSON array. | ``[{ "scope" => , "key" => , "enabled" => }]`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The list of share recipient. | | ```` | -| | | | ``alice`` | -| | | | ``Alice`` | -| | | | ``0`` | -| | | | ```` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | An array of checksums. | ``md5:04c36b75222cd9fd47f2607333029106`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Whether a preview of the file is available. | ``true`` or ``false`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | Unlike ``getcontentlength``, | | -| | | this property also works | | -| | | for folders, reporting the size | | -| | | of everything in the folder. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Amount of bytes used in the folder. | ``3950773`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Amount of available bytes in the folder. | | ``3950773`` | -| | | | ``-1`` Uncomputed free space. | -| | | | ``-2`` Unknown free space. | -| | | | ``-3`` Unlimited free space. | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The id of the workspace file. | `3456` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | The content of the workspace file. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Date this file was uploaded. | ``1675789581`` | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | Share note. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The number of folders directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | The number of files directly contained | | -| | | in the folder (not recursively). | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ -| | | Used by the clients to find out | | -| | | if a backup has been restored. | | -+-------------------------------+--------------------------------------------------+--------------------------------------------------------------------------+ - ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| Property | Description | Example | ++===============================+=================================================+==========================================================================+ +| | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The language of the content. | ``en`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | A name suitable for presentation. | ``File name`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | Dummy endpoint for class 2 WebDAV support. | ```` | +| | | Should return the list of lock, but | | +| | | always return an empty response. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | Dummy endpoint for class 2 WebDAV support. | | ```` | +| | | Always provide the same lock capabilities. | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | +| | | | | ```` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The URL to download the file. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The permissions that the user has over the | | ``S``: Shared | +| | | file. The value is a string containing | | ``R``: Shareable | +| | | letters for all available permissions. | | ``M``: Mounted | +| | | | ``G``: Readable | +| | | | ``D``: Deletable | +| | | | ``NV``: Updateable, Renameable, Moveable | +| | | | ``W``: Updateable (file) | +| | | | ``CK``: Creatable | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Same as ``creationdate``, but as a timestamp. | ``0`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'group'`` = group folder | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | List of user specified tags. | ``test`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The number of comments. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | XML array of share types. | | ``{shareTypeId}`` | +| | | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``8`` = Guest | +| | | | ``9`` = Remote group | +| | | | ``10`` = Talk conversation | +| | | | ``12`` = Deck | +| | | | ``15`` = Science mesh | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The permissions that the | | ``1`` = Read | +| | | user has over the share. | | ``2`` = Update | +| | | | ``4`` = Create | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The permissions that the user has | ``['share', 'read', 'write']`` | +| | | over the share as a JSON array. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | User set attributes as a JSON array. | ``[{ "scope" => , "key" => , "enabled" => }]`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The list of share recipient. | | ```` | +| | | | ``alice`` | +| | | | ``Alice`` | +| | | | ``0`` | +| | | | ```` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | An array of checksums. | ``md5:04c36b75222cd9fd47f2607333029106`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Whether a preview of the file is available. | ``true`` or ``false`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | Unlike ``getcontentlength``, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Amount of bytes used in the folder. | ``3950773`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Amount of available bytes in the folder. | | ``3950773`` | +| | | | ``-1`` Uncomputed free space. | +| | | | ``-2`` Unknown free space. | +| | | | ``-3`` Unlimited free space. | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The id of the workspace file. | `3456` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The content of the workspace file. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Date this file was uploaded. | ``1675789581`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Share note. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | The number of files directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | | Used by the clients to find out | | +| | | if a backup has been restored. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Whether ACL is enabled for this group folder. | ``1`` or ``0`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Wether the current user can manager ACL. | ``1`` or ``0`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Array of ACL rules. | | ```` | +| | | | ``group`` | +| | | | ``admin`` | +| | | | ``admin`` | +| | | | ``20`` | +| | | | ``15`` | +| | | | ```` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Array of ACL rules from the parents folders | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Numerical id of that group folder. | ``1`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Wether the file is locked. | ``1`` or ``0`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Type of the owner of the lock. | ``0`` = User | +| | | ``1`` = Office or Text | +| | | ``2`` = WebDAV | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | User id of the owner of the lock. | ``alice`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Display name of the owner of the lock. | ``Alice`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | App id of an app owned lock. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | Date when the lock was created as a timestamp. | ``1675789581`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | TTL of the lock in seconds staring from the | ``0`` = No timeout | +| | creation time. | | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ +| | The token of the lock. | ``files_lock/0e53dfb6-61b4-46f0-b38e-d9a428292998`` | ++-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ Listing folders (rfc4918_) -------------------------- From 7bc8b31e418e366701e0094130e70ffd04e6cc37 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Wed, 3 May 2023 16:22:58 +0200 Subject: [PATCH 14/20] Improve creation_time example Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 540503191..61fb58892 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -182,7 +182,7 @@ Supported properties | | | | ``W``: Updateable (file) | | | | | ``CK``: Creatable | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | Same as ``creationdate``, but as a timestamp. | ``0`` | +| | Same as ``creationdate``, but as a timestamp. | ``1675789581`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | The type of mount. | | ``''`` = local | | | | | ``'shared'`` = received share | From 778d780471cf751cb7d75a957a6a8ca8a7437eab Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Wed, 3 May 2023 18:10:29 +0200 Subject: [PATCH 15/20] Add more examples Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 61fb58892..795e50d55 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -147,7 +147,7 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Specifies the nature of the resource. | ```` for a folder | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The size if it is a file. | ``3030237`` | +| | The size if it is a file in octets. | ``3030237`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | The language of the content. | ``en`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ @@ -166,12 +166,13 @@ Supported properties | | | | | ```` | | | | | | ```` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | | The fileid namespaced by the instance id. | | +| | | The fileid namespaced by the instance id. | ``00000007oc9l3j5ur4db`` | | | | Globally unique. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The unique id for the file within the instance. | | +| | The unique id for the file within the instance. | ``7`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The URL to download the file. | | +| | | A URL to directly download the file from a | | +| | | storage. No storeage implements that yet. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | | The permissions that the user has over the | | ``S``: Shared | | | | file. The value is a string containing | | ``R``: Shareable | @@ -182,7 +183,7 @@ Supported properties | | | | ``W``: Updateable (file) | | | | | ``CK``: Creatable | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | Same as ``creationdate``, but as a timestamp. | ``1675789581`` | +| | Same as ``creationdate``, but as a timestamp. | ``1675789581`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | The type of mount. | | ``''`` = local | | | | | ``'shared'`` = received share | @@ -198,15 +199,15 @@ Supported properties | | The favorite state. | | ``0`` for not favourited | | | | | ``1`` for favourited | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The DAV endpoint to fetch the comments. | | +| | The DAV endpoint to fetch the comments. | ``/remote.php/dav/comments/files/{fileId}`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The number of comments. | | +| | The number of comments. | ``2`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The number of unread comments. | | +| | The number of unread comments. | ``0`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The user id of the owner of a shared file. | | +| | The user id of the owner of a shared file. | ``alice`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The display name of the owner of a shared file. | | +| | The display name of the owner of a shared file. | ``Alice`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | XML array of share types. | | ``{shareTypeId}`` | | | | | ``0`` = User | @@ -243,10 +244,9 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Whether a preview of the file is available. | ``true`` or ``false`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | | Unlike ``getcontentlength``, | | -| | | this property also works | | -| | | for folders, reporting the size | | -| | | of everything in the folder. | | +| | | Unlike ``getcontentlength``, this property | ``127815235`` | +| | | also works for folders, reporting the size of | | +| | | everything in the folder. Size is in octets. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Amount of bytes used in the folder. | ``3950773`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ @@ -284,7 +284,7 @@ Supported properties | | | | ``15`` | | | | | ```` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | Array of ACL rules from the parents folders | | +| | Array of ACL rules from the parents folders | See | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Numerical id of that group folder. | ``1`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ From 6ed4ef8a4a4c0944402423ebd0b4131db1b6cc27 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Wed, 3 May 2023 18:14:08 +0200 Subject: [PATCH 16/20] Fix typo Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 795e50d55..555f8bb14 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -172,7 +172,7 @@ Supported properties | | The unique id for the file within the instance. | ``7`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | | A URL to directly download the file from a | | -| | | storage. No storeage implements that yet. | | +| | | storage. No storage implements that yet. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | | The permissions that the user has over the | | ``S``: Shared | | | | file. The value is a string containing | | ``R``: Shareable | From 7c5931d787cd1c1c7876bd45469f0072ad4a306d Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 4 May 2023 10:45:28 +0200 Subject: [PATCH 17/20] Use bytes over octets Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 555f8bb14..203138fb5 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -147,7 +147,7 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Specifies the nature of the resource. | ```` for a folder | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The size if it is a file in octets. | ``3030237`` | +| | The size if it is a file in bytes. | ``3030237`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | The language of the content. | ``en`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ @@ -246,7 +246,7 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | | Unlike ``getcontentlength``, this property | ``127815235`` | | | | also works for folders, reporting the size of | | -| | | everything in the folder. Size is in octets. | | +| | | everything in the folder. Size is in bytes. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Amount of bytes used in the folder. | ``3950773`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ From 77cbe46b74296f9141c5c2edd115c19cdfa42dbf Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 4 May 2023 15:03:32 +0200 Subject: [PATCH 18/20] Fix JSON syntax in example Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 203138fb5..8add5709a 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -32,7 +32,7 @@ For example: you can perform a :code:`PROPFIND` request to find files in a folde --user username:password \ --request PROPFIND \ --data ' - + @@ -229,7 +229,7 @@ Supported properties | | | | ``16`` = Share | | | | | ``31`` = All | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | | The permissions that the user has | ``['share', 'read', 'write']`` | +| | | The permissions that the user has | ``["share", "read", "write"]`` | | | | over the share as a JSON array. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | User set attributes as a JSON array. | ``[{ "scope" => , "key" => , "enabled" => }]`` | From ae60e1c5539fa9d456266f548f13ab582e8e9030 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 4 May 2023 16:03:26 +0200 Subject: [PATCH 19/20] Harmonize usage of " Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 8add5709a..ecafbc429 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -137,13 +137,13 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | Property | Description | Example | +===============================+=================================================+==========================================================================+ -| | The creation date of the node. | ``"1970-01-01T00:00:00+00:00"`` | +| | The creation date of the node. | ``1970-01-01T00:00:00+00:00`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | +| | The latest modification time. | ``Wed, 20 Jul 2022 05:12:23 GMT`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The file's etag. | ``""6436d084d4805""`` | +| | The file's etag. | ``"6436d084d4805"`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The mime type of the file. | ``"image/jpeg"`` | +| | The mime type of the file. | ``image/jpeg`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Specifies the nature of the resource. | ```` for a folder | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ From 46f1c9a83ca04dc94f492167bc2243d6438e8792 Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 4 May 2023 16:04:33 +0200 Subject: [PATCH 20/20] Fix table format Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index ecafbc429..f13d88eb4 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -137,17 +137,17 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | Property | Description | Example | +===============================+=================================================+==========================================================================+ -| | The creation date of the node. | ``1970-01-01T00:00:00+00:00`` | +| | The creation date of the node. | ``1970-01-01T00:00:00+00:00`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The latest modification time. | ``Wed, 20 Jul 2022 05:12:23 GMT`` | +| | The latest modification time. | ``Wed, 20 Jul 2022 05:12:23 GMT`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The file's etag. | ``"6436d084d4805"`` | +| | The file's etag. | ``"6436d084d4805"`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The mime type of the file. | ``image/jpeg`` | +| | The mime type of the file. | ``image/jpeg`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Specifies the nature of the resource. | ```` for a folder | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ -| | The size if it is a file in bytes. | ``3030237`` | +| | The size if it is a file in bytes. | ``3030237`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | The language of the content. | ``en`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ @@ -246,7 +246,7 @@ Supported properties +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | | Unlike ``getcontentlength``, this property | ``127815235`` | | | | also works for folders, reporting the size of | | -| | | everything in the folder. Size is in bytes. | | +| | | everything in the folder. Size is in bytes. | | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+ | | Amount of bytes used in the folder. | ``3950773`` | +-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------+