Struct libdav::CardDavClient
source · pub struct CardDavClient<C>{ /* private fields */ }Expand description
Client to communicate with a carddav server.
Instances are usually created via a ClientBuilder, which can also automatically bootstrap
the exact host and context path.
use http::Uri;
use libdav::auth::{Auth, Password};
use hyper_rustls::HttpsConnectorBuilder;
let uri = Uri::try_from("https://example.com").unwrap();
let auth = Auth::Basic {
username: String::from("user"),
password: Some(Password::from("secret")),
};
let https = HttpsConnectorBuilder::new()
.with_native_roots()
.unwrap()
.https_or_http()
.enable_http1()
.build();
let client = CardDavClient::builder()
.with_uri(uri)
.with_auth(auth)
.bootstrap(https)
.await
.unwrap()
.build();Implementations§
source§impl<C> CardDavClient<C>
impl<C> CardDavClient<C>
sourcepub fn builder() -> ClientBuilder<Self, NeedsUri>
pub fn builder() -> ClientBuilder<Self, NeedsUri>
Creates a new builder. See CardDavClient and ClientBuilder for details.
sourcepub fn addressbook_home_set(&self) -> Option<&Uri>
pub fn addressbook_home_set(&self) -> Option<&Uri>
The home set found during discovery (if any) or explicitly provided during client creation.
This function does not perform any network operations; it merely returns the already-known URL.
sourcepub async fn find_addressbooks(
&self,
url: Option<&Uri>
) -> Result<Vec<FoundCollection>, DavError>
pub async fn find_addressbooks( &self, url: Option<&Uri> ) -> Result<Vec<FoundCollection>, DavError>
Find address book collections under the given url.
If url is not specified, this client’s address book home set is used instead. If no
address book home set has been found, then the server’s context path will be used. When
using a client bootstrapped via automatic discovery, passing None will usually yield the
expected results.
Errors
If the HTTP call fails or parsing the XML response fails.
sourcepub async fn get_address_book_resources(
&self,
addressbook_href: impl AsRef<str>,
hrefs: impl IntoIterator<Item = impl AsRef<str>>
) -> Result<Vec<FetchedResource>, DavError>
pub async fn get_address_book_resources( &self, addressbook_href: impl AsRef<str>, hrefs: impl IntoIterator<Item = impl AsRef<str>> ) -> Result<Vec<FetchedResource>, DavError>
Fetches existing vcard resources.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn check_support(&self, url: &Uri) -> Result<(), CheckSupportError>
pub async fn check_support(&self, url: &Uri) -> Result<(), CheckSupportError>
Checks that the given URI advertises carddav support.
See: https://www.rfc-editor.org/rfc/rfc6352#section-6.1
Errors
If there are any network issues or if the server does not explicitly advertise carddav support.
Methods from Deref<Target = WebDavClient<C>>§
sourcepub fn relative_uri(&self, path: impl AsRef<str>) -> Result<Uri, Error>
pub fn relative_uri(&self, path: impl AsRef<str>) -> Result<Uri, Error>
Returns a new URI relative to the server’s root.
Errors
If this client’s base_url is invalid or the provided path is not an acceptable path.
sourcepub async fn find_current_user_principal(
&self
) -> Result<Option<Uri>, FindCurrentUserPrincipalError>
pub async fn find_current_user_principal( &self ) -> Result<Option<Uri>, FindCurrentUserPrincipalError>
Resolves the current user’s principal resource.
Returns None if the response’s status code is 404 or if no principal was found.
Errors
- If the underlying HTTP request fails.
- If the response status code is neither success nor 404.
- If parsing the XML response fails.
- If the
hrefcannot be parsed into a validUri
See also
sourcepub async fn propfind(
&self,
url: &Uri,
properties: &[&Property<'_, '_>],
depth: u8
) -> Result<(Parts, Bytes), DavError>
pub async fn propfind( &self, url: &Uri, properties: &[&Property<'_, '_>], depth: u8 ) -> Result<(Parts, Bytes), DavError>
Sends a PROPFIND request.
This is a shortcut for simple PROPFIND requests.
Errors
If there are any network errors.
sourcepub async fn request(
&self,
request: Request<Body>
) -> Result<(Parts, Bytes), RequestError>
pub async fn request( &self, request: Request<Body> ) -> Result<(Parts, Bytes), RequestError>
Send a request to the server.
Sends a request, applying any necessary authentication and logging the response.
Errors
Returns an error if the underlying http request fails or if streaming the response fails.
sourcepub async fn get_collection_displayname(
&self,
href: &str
) -> Result<Option<String>, DavError>
pub async fn get_collection_displayname( &self, href: &str ) -> Result<Option<String>, DavError>
Returns the displayname for the collection at path href.
From rfc3744#section-4:
A principal MUST have a non-empty DAV:displayname property
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn propupdate(
&self,
url: &Uri,
property: &Property<'_, '_>,
value: Option<&str>
) -> Result<(), DavError>
pub async fn propupdate( &self, url: &Uri, property: &Property<'_, '_>, value: Option<&str> ) -> Result<(), DavError>
Sends a PROPUPDATE query to the server.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn set_collection_displayname(
&self,
href: &str,
displayname: Option<&str>
) -> Result<(), DavError>
pub async fn set_collection_displayname( &self, href: &str, displayname: Option<&str> ) -> Result<(), DavError>
Sets the displayname for a collection
The displayname string is expected not to be escaped.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn find_context_path(
&self,
service: DiscoverableService,
host: &str,
port: u16
) -> Result<Option<Uri>, ResolveContextPathError>
pub async fn find_context_path( &self, service: DiscoverableService, host: &str, port: u16 ) -> Result<Option<Uri>, ResolveContextPathError>
Resolve the default context path using a well-known path.
This only applies for servers supporting webdav extensions like caldav or carddav.
Errors
- If the provided scheme, host and port cannot be used to construct a valid URL.
- If there are any network errors.
- If the response is not an HTTP redirection.
- If the
Locationheader in the response is missing or invalid.
See also
sourcepub async fn list_resources(
&self,
collection_href: &str
) -> Result<Vec<ListedResource>, DavError>
pub async fn list_resources( &self, collection_href: &str ) -> Result<Vec<ListedResource>, DavError>
Enumerates resources in a collection
Returns an array of results.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn create_resource(
&self,
href: impl AsRef<str>,
data: Vec<u8>,
mime_type: impl AsRef<[u8]>
) -> Result<Option<String>, DavError>
pub async fn create_resource( &self, href: impl AsRef<str>, data: Vec<u8>, mime_type: impl AsRef<[u8]> ) -> Result<Option<String>, DavError>
Creates a new resource
Returns an Etag if present in the server’s response.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn update_resource(
&self,
href: impl AsRef<str>,
data: Vec<u8>,
etag: impl AsRef<str>,
mime_type: impl AsRef<[u8]>
) -> Result<Option<String>, DavError>
pub async fn update_resource( &self, href: impl AsRef<str>, data: Vec<u8>, etag: impl AsRef<str>, mime_type: impl AsRef<[u8]> ) -> Result<Option<String>, DavError>
Updates an existing resource
Returns an Etag if present in the server’s response.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn create_collection(
&self,
href: impl AsRef<str>,
resourcetypes: &[&Property<'_, '_>]
) -> Result<(), DavError>
pub async fn create_collection( &self, href: impl AsRef<str>, resourcetypes: &[&Property<'_, '_>] ) -> Result<(), DavError>
Creates a collection under path href.
This function executes an Extended MKCOL.
Additional resource types may be specified via the resourcetypes argument. The
DAV:collection resource type is implied and MUST NOT be specified.
Caveats
Because servers commonly don’t return an Etag for this operation, it needs to be fetched in a separate operation.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn delete(
&self,
href: impl AsRef<str>,
etag: impl AsRef<str>
) -> Result<(), DavError>
pub async fn delete( &self, href: impl AsRef<str>, etag: impl AsRef<str> ) -> Result<(), DavError>
Deletes the resource at href.
The resource MAY be a collection. Because the implementation for deleting resources and collections is identical, this same function is used for both cases.
If the Etag does not match (i.e.: if the resource has been altered), the operation will fail and return an Error.
Errors
If there are any network errors or the response could not be parsed.
sourcepub async fn force_delete(&self, href: impl AsRef<str>) -> Result<(), DavError>
pub async fn force_delete(&self, href: impl AsRef<str>) -> Result<(), DavError>
Force deletion of the resource at href.
This function does not guarantee that a resource or collection has not been modified since it was last read. Use this function with great care.
The resource MAY be a collection. Because the implementation for deleting resources and collections is identical, this same method covers both cases.
Errors
If there are any network errors or the response could not be parsed.