Plasma GitLab Archive
Projects Blog Knowledge

Class type Webdav_client.webdav_client_t


class type webdav_client_t = object .. end
General remarks:

Paths. The paths passed to the access methods must be absolute (start with "/"), and must not include the http:// prefix. All unsafe characters in the paths (like ";" or "?") are automatically percent-encoded.

Synchronous operation. The access methods return an object that already includes the servers response. All TCP connections are already closed.

Depth. The depth says whether the operation is only applied to the passed object (`Zero), to the object and the direct children (`One), or to the whole subtree (`Infinity). The latter is the default if the depth is not specified.

Fixup. All methods have a fixup argument. The passed function is called back with the call object before the WebDAV request is submitted to the server. This can be used to set options in the call object.

Error checking. The returned call object has methods reporting the exact error condition. For most applications it is sufficient to only check whether fully_successful is true. A number of methods can return partial successes, though, e.g. a recursive operation could only be carried out for a number of files. If this needs to be analyzed by the caller, one should first check call_status and if `Multi_status is returned, the methods good_paths and bad_paths list for which paths the operation was successful or not successful, respectively.


method base_url : string
The base URL this client class prepends to all URLs. For example, if the base URL is "http://localhost/foo" and the operation propfind "/bar" is invoked, actually the target URL is set to the concatation of both, namely "http://localhost/foo/bar".

The base URL is encoded, if necessary (percent encoding).

method pipeline : Http_client.pipeline
The backing pipeline
method propfind : ?depth:Webdav_http.depth ->
?propfind_request:Webdav_client_methods.propfind_request ->
?fixup:(Http_client.http_call -> unit) ->
string -> Webdav_client_methods.propfind_call_t
propfind path: Submits a PROPFIND request to the server. The returned propfind_call_t object already includes the response.
method list : ?depth:Webdav_http.depth ->
?fixup:(Http_client.http_call -> unit) ->
Webdav_client_methods.list_request -> string -> Webdav_client_methods.list_t
list req path: Submits a special PROPFIND request for getting a file listing.

Example: Get file listing at /foo:

           let l = client # list `Existence "/foo" in
           if not l#fully_successful then failwith "Not successful";
           let paths = l#good_paths
        

method proppatch : ?fixup:(Http_client.http_call -> unit) ->
proppatch_request:Webdav_client_methods.proppatch_request ->
string -> Webdav_client_methods.proppatch_call_t
proppatch ~proppatch_request path: Submits a PROPPATCH request to change properties. The change is described in proppatch_request.

Example: Set the Content-Type

	  let proppatch_request =
	    [ `Set [ Webdav_xml.encode_getcontenttype ("text/plain",[]) ] ] in
	  client # proppatch ~proppatch_request "/file"

method mkcol : ?fixup:(Http_client.http_call -> unit) ->
string -> Webdav_client_methods.mkcol_call_t
mkcol path: Submits an MKCOL request (create a new collection/directory).
method delete : ?fixup:(Http_client.http_call -> unit) ->
string -> Webdav_client_methods.delete_call_t
delete path: Submits a DELETE request. Deletes are always recursive. Servers are allowed to delete as much as possible (instead of an "all or nothing" semantics), and to return partial success only.
method get : ?store:Http_client.response_body_storage ->
?fixup:(Http_client.http_call -> unit) ->
string -> Webdav_client_methods.get_call_t
get path: Submits a GET request (download a file). The downloaded body can be accessed with the response_body method of the returned object.

The store argument specifies where the body is stored.

Example download (in-memory):

           let g = client # get "/path"
           let s = g # response_body # value
        

Example download to file:

           let store = `File (fun () -> "/home/gerd/downloaded_file")
           let g = client # get ~store "/path"
           let ch = g # response_body # open_value_rd()
           ch # input_line()    (* get first line *)
        

method put : ?content_type:string ->
?content_length:int64 ->
?expect_handshake:bool ->
?fixup:(Http_client.http_call -> unit) ->
string -> Netmime.mime_body -> Webdav_client_methods.put_call_t
put path body: Submits a PUT request (upload a file). The body includes the data to upload.

  • content_type: The media type of the body. The server is free to ignore this.
  • content_length: The length of the body, if already known. There are servers that accept PUT only if the content length is set in the header. (See the function length_of_body below for getting the length.)
  • expect_handshake: Set this to true to enable a special handshake before the body is uploaded. This is reasonable when the PUT request may cause errors - the error can be received before the upload starts. There might be compatibility problems, though, as this feature was incorrectly specified in some versions of HTTP.
Note that some servers do not permit that existing files are replaced. The RFC says nothing about this case, though.

Example upload:

         let b = new Netmime.file_mime_body "/home/gerd/large.bin"
         let n = length_of_body b
         let p = client # put ~content_length:n ~expect_handshake:true
                               "/path" b
         if not p#fully_successful then
           failwith "Error"
      

method copy : ?depth:Webdav_http.depth ->
?overwrite:bool ->
?dest_base_url:string ->
?fixup:(Http_client.http_call -> unit) ->
string -> string -> Webdav_client_methods.copy_call_t
copy src_path dest_path: Submits a COPY request. By default, it is not possible to overwrite files during the copy. One has to set overwrite:true to allow this.

Note that dest_path is interpreted as "copy onto", not "copy into" if it is a directory, i.e. the src_path subtree will be available also as dest_path if the copy is successful. This is different from the semantics of the cp command.

In a recursive copy, servers are free to copy only as many of the files as possible, i.e. partial success is possible.

If dest_base_url is set, one can specify to copy to a different WebDAV server. This is rarely supported by servers, though.

method move : ?overwrite:bool ->
?dest_base_url:string ->
?fixup:(Http_client.http_call -> unit) ->
string -> string -> Webdav_client_methods.move_call_t
move src_path dest_path: Submits a MOVE request. By default, it is not possible to overwrite files during the move. One has to set overwrite:true to allow this.

The MOVE method is always recursive.

Note that dest_path is interpreted as "move onto", not "move into" if it is a directory, i.e. the src_path subtree will be available as dest_path if the move is successful. This is different from the semantics of the mv command.

Servers are free to move only as many of the files as possible, i.e. partial success is possible.

If dest_base_url is set, one can specify to move to a different WebDAV server. This is rarely supported by servers, though.

This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml