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.stahl@allotropia.de>
Reviewed-by: Michael Stahl <michael.stahl@allotropia.de>

1 files changed, 32 insertions, 7 deletions

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