ucb/README.md | 39 ++++++++++++++++++++++++++++++++-------
1 file changed, 32 insertions(+), 7 deletions(-)
New commits:
commit a3a6ef172927087d4d98f1e04f428de870db3c8c
Author: Michael Stahl <michael.st...@allotropia.de>
AuthorDate: Fri Jan 14 19:08:44 2022 +0100
Commit: Michael Stahl <michael.st...@allotropia.de>
CommitDate: Wed Jan 26 18:50:07 2022 +0100
ucb: add more webdav-curl doc to README
Change-Id: I50a56f9f5b0126c46133129d62464e0171dc40f8
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/128422
Tested-by: Michael Stahl <michael.st...@allotropia.de>
Reviewed-by: Michael Stahl <michael.st...@allotropia.de>
diff --git a/ucb/README.md b/ucb/README.md
index bd451b4c9e8c..4d31280779a1 100644
--- a/ucb/README.md
+++ b/ucb/README.md
@@ -7,7 +7,7 @@ various DMS and fileshare systems like WebDAV, CMIS, or GIO.
The UCPs implement the Universal Content Provider UNO interfaces in
C++, in particular the `com.sun.star.ucb.ContentProvider` service.
-## WebDAV ucp
+## WebDAV UCP
The WebDAV content provider is based on `libcurl` for much of the
network and protocol stuff, including authentication.
@@ -36,18 +36,43 @@ server idiosyncrasies:
* Nextcloud will reply to a PROPFIND request with "100 Continue" and
then after the data is uploaded it will send a "401 Unauthorized" if
the auth header is missing in the headers to which it replied with
- "100 Continue". So we reuse that.
-* Sharepoint 16 responds to PROPFIND with "Transfer-Encoding: chunked"
+ "100 Continue".
+* Sharepoint 16 responds to PROPFIND, PROPPATCH and LOCK with
+ "Transfer-Encoding: chunked"
with "HTTP/1.1 200 OK" and an actual error message in the response *body*.
* apparently setting Content-Length works better, so we use that
- * Sharepoint 16 has the same problem with PROPFIND.
- * and for when using chunked encoding for LOCK
* Sharepoint returns redirect urls that curl can't parse, so we encode
them (check `WebDAVResponseParser` for the code)
+* Sharepoint may reply to HEAD with 200 OK but then 404 NOT FOUND to PROPFIND
+* Sharepoint does not appear to support Dead Properties
* avoiding chunked encoding for PUT, since for Nextcloud:
* Transfer-Encoding: chunked creates a 0 byte file with response
"201 Created"
* see upstream bug: https://github.com/nextcloud/server/issues/7995
- * apparently this doesn't happen with header Content-Length: 8347,
- so we use that
+
+To a first approximation, there are 3 parts involved in the UCP:
+
+* The upper layer implements the UNO API which is called by LibreOffice, and
+ translates the calls from generic sequence-of-any stringly typed abstractness
+ into HTTP or WebDAV protocol calls, and does some high level protocol
+ handling to figure out what the server supports and so on. This is is
+ independent of the low-level library.
+* Then there is the lower layer of the UCP, which translates the generic HTTP
+ or WebDAV protocol calls to something that the particular third-party library
+ can understand, hook up its callbacks for data transfer and authentication,
+ and parse the reply XML documents.
+* At the bottom, there is the third-party library that implements the HTTP
+ protocol.
+
+The most important classes are:
+* ContentProvider: the UNO entry point/factory, creates Content instances
+* Content: the main UNO service, translates the UCP API to WebDAV methods,
+ one instance per URL
+* DAVResourceAccess: sits between Content and CurlSession
+* DAVSessionFactory: creates CurlSession for DAVResourceAccess
+* CurlSession: low-level interfacing with libcurl
+* SerfLockStore: singleton used by CurlSession to store DAV lock tokens, runs
+ a thread to refresh locks when they expire
+* WebDAVResponseParser: parse XML responses to LOCK, PROPFIND requests
+* DAVAuthListener_Impl: request credentials from UI via UNO
