Struct CalDavClient

pub struct CalDavClient<C>
where
    C: Service<Request<String>, Response = Response<Incoming>> + Sync + Send + 'static,
{
    pub webdav_client: WebDavClient<C>,
}

Client to communicate with a CalDAV server.

Instances are usually created via CalDavClient::new:

use http::Uri;
use hyper_rustls::HttpsConnectorBuilder;
use hyper_util::{client::legacy::Client, rt::TokioExecutor};
use tower_http::auth::AddAuthorization;

let uri = Uri::try_from("https://example.com").unwrap();

let https_connector = HttpsConnectorBuilder::new()
    .with_native_roots()
    .unwrap()
    .https_or_http()
    .enable_http1()
    .build();
let https_client = Client::builder(TokioExecutor::new()).build(https_connector);
let https_client = AddAuthorization::basic(https_client, "user", "secret");
let webdav = WebDavClient::new(uri, https_client);
let client = CalDavClient::new(webdav);

If the real CalDAV server needs to be resolved via automated service discovery, use CalDavClient::bootstrap_via_service_discovery.

For setting the Authorization header or applying other changes to outgoing requests, see the documentation on WebDavClient.

Fields

webdav_client: WebDavClient<C>

A WebDAV client used to send requests.

Implementations

impl<C> CalDavClient<C>

where C: Service<Request<String>, Response = Response<Incoming>> + Sync + Send, <C as Service<Request<String>>>::Error: Error + Send + Sync,

pub fn new(webdav_client: WebDavClient<C>) -> CalDavClient<C>

Create a new client instance.

See also

CalDavClient::bootstrap_via_service_discovery.

pub async fn bootstrap_via_service_discovery( webdav_client: WebDavClient<C>, ) -> Result<CalDavClient<C>, BootstrapError>

Automatically bootstrap a new client instance using service discovery.

Creates a new client, with its base_url set to the context path retrieved using service discovery via find_context_url.

Errors

• BootstrapError::ServiceForUrl if the webdav client uses a URL with an invalid schema.
• BootstrapError::ContextUrl if underlying call to find_context_url returns an error.

pub async fn find_calendar_home_set( &self, principal: &Uri, ) -> Result<Vec<Uri>, FindHomeSetError>

Queries the server for the calendar home set.

See: https://www.rfc-editor.org/rfc/rfc4791#section-6.2.1

Errors

If there are any network errors or the response could not be parsed.

pub async fn find_calendars( &self, calendar_home_set: &Uri, ) -> Result<Vec<FoundCollection>, WebDavError>

Find calendars collections under the given url.

If url is not specified, this client’s current base_url shall be used instead. 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.

pub async fn get_calendar_resources( &self, calendar_href: &str, hrefs: impl IntoIterator<Item = impl AsRef<str>>, ) -> Result<Vec<FetchedResource>, WebDavError>

Fetches existing icalendar resources.

If the getetag property is missing for an item, it will be reported as http::StatusCode::NOT_FOUND. This should not be an actual issue with in practice, since support for getetag is mandatory for CalDAV implementations.

Errors

If there are any network errors or the response could not be parsed.

pub async fn check_support(&self, url: &Uri) -> Result<(), CheckSupportError>

Checks that the given URI advertises caldav support.

See: https://www.rfc-editor.org/rfc/rfc4791#section-5.1

Known Issues

• Nextcloud’s implementation seems broken. Bug report.

Errors

If there are any network issues or if the server does not explicitly advertise caldav support.

pub async fn create_calendar(&self, href: &str) -> Result<(), WebDavError>

Create an calendar collection.

Errors

Returns an error in case of network errors or if the server returns a failure status code.

pub async fn get_user_address_set( &self, principal: &Uri, ) -> Result<Vec<String>, WebDavError>

Returns the addresses for a given principal.

This set typically includes at least email address in the format mailto:alice@example.com.

Errors

Returns an error in case of network errors or if the server returns a failure status code.

Methods from Deref<Target = WebDavClient<C>>

pub fn base_url(&self) -> &Uri

Returns a URL pointing to the server’s context path.

pub fn relative_uri(&self, path: &str) -> Result<Uri, Error>

Returns a new URI relative to the server’s root.

path MUST NOT be percent-encoded, except for any reserved characters.

Errors

If this client’s base_url is invalid or the provided path is not an acceptable path.

pub async fn find_current_user_principal( &self, ) -> Result<Option<Uri>, FindCurrentUserPrincipalError>

Resolves the current user’s principal resource.

First queries the base_url, then the root path on the same host.

Returns None if the response’s status code is 404 or if no principal was found.

Errors

See FindCurrentUserPrincipalError

See also

The DAV:current-user-principal property is defined in https://www.rfc-editor.org/rfc/rfc5397#section-3

pub async fn propfind( &self, url: &Uri, properties: &[&PropertyName<'_, '_>], depth: Depth, ) -> Result<(Parts, Bytes), WebDavError>

Sends a PROPFIND request.

Returns the head and body of the response.

Errors

If there are any network errors or the provided url is invalid.

pub async fn request( &self, request: Request<String>, ) -> 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.

pub async fn get_property( &self, href: &str, property: &PropertyName<'_, '_>, ) -> Result<Option<String>, WebDavError>

Fetch a single property.

Common properties

• names::ADDRESSBOOK_DESCRIPTION
• names::CALENDAR_COLOUR
• names::CALENDAR_DESCRIPTION
• names::CALENDAR_ORDER
• names::DISPLAY_NAME

Quirks

The namespace of the value in the response from the server is ignored. This is a workaround for an issue in cyrus-imapd.

Errors

• If there are any network errors or the response could not be parsed.
• If the requested property is missing in the response.

See also

• WebDavClient::set_property

pub async fn get_properties<'ptr, 'p>( &self, href: &str, properties: &[&'ptr PropertyName<'p, 'p>], ) -> Result<Vec<(&'ptr PropertyName<'p, 'p>, Option<String>)>, WebDavError>

Fetch multiple properties for a single resource.

Values in the returned Vec are in the same order as the properties parameter.

Quirks

Same as WebDavClient::get_property.

Errors

• If there are any network errors or the response could not be parsed.
• If the requested property is missing in the response.

See also

• WebDavClient::get_property
• WebDavClient::set_property

pub async fn set_property( &self, href: &str, property: &PropertyName<'_, '_>, value: Option<&str>, ) -> Result<Option<String>, WebDavError>

Sends a PROPUPDATE query to the server.

Setting the value to None will remove the property. Returns the new value as returned by the server. The provided value does not need to be escaped.

Quirks

Same as WebDavClient::get_property.

Errors

If there are any network errors or the response could not be parsed.

See also

• WebDavClient::get_property (contains a list of some included well-known properties)

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. Returns Ok(None) if the well-known path does not redirect to another location.

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 Location header in the response is missing or invalid.

See also

• https://www.rfc-editor.org/rfc/rfc6764#section-5
• ResolveContextPathError

pub async fn list_resources( &self, collection_href: &str, ) -> Result<Vec<ListedResource>, WebDavError>

Enumerates resources in a collection

Errors

If there are any network errors or the response could not be parsed.

pub async fn create_resource( &self, href: &str, data: Vec<u8>, mime_type: &[u8], ) -> Result<Option<String>, WebDavError>

Creates a new resource

Returns an Etag if present in the response. If the Etag is not included, it must be requested in a follow-up request, and cannot be obtained race-free.

Errors

If there are any network errors or the response could not be parsed.

pub async fn update_resource( &self, href: &str, data: Vec<u8>, etag: &str, mime_type: &[u8], ) -> Result<Option<String>, WebDavError>

Updates an existing resource

Returns an Etag if present in the response. If the Etag is not included, it must be requested in a follow-up request, and cannot be obtained race-free.

Errors

If there are any network errors or the response could not be parsed.

pub async fn create_collection( &self, href: &str, resourcetypes: &[&PropertyName<'_, '_>], ) -> Result<(), WebDavError>

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.

Errors

If there are any network errors or the response could not be parsed.

pub async fn delete(&self, href: &str, etag: &str) -> Result<(), WebDavError>

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.

pub async fn force_delete(&self, href: &str) -> Result<(), WebDavError>

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 care.

The resource MAY be a collection. Because the implementation for deleting resources and collections is identical, this same function covers both cases.

Errors

If there are any network errors or the response could not be parsed.

Trait Implementations

impl<C> Debug for CalDavClient<C>

where C: Service<Request<String>, Response = Response<Incoming>> + Sync + Send + 'static + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C> Deref for CalDavClient<C>

where C: Service<Request<String>, Response = Response<Incoming>> + Sync + Send,

type Target = WebDavClient<C>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.