Struct Provider 

pub struct Provider<L, T, R, U>
where
    L: CalDavSource<T>,
    T: CompleteCalendar + Sync + Send,
    R: CalDavSource<U>,
    U: DavCalendar + Sync + Send,
{ /* private fields */ }

A data source that combines two CalDavSources, which is able to sync both sources.

Usually, you will only need to use a provider between a server and a local cache, that is to say a CalDavProvider, i.e. a Provider<Cache, CachedCalendar, Client, RemoteCalendar>.
However, providers can be used for integration tests, where the remote source is mocked by a Cache.

Implementations

impl<L, T, R, U> Provider<L, T, R, U>

where L: CalDavSource<T>, T: CompleteCalendar + Sync + Send, R: CalDavSource<U>, U: DavCalendar + Sync + Send,

pub fn new(remote: R, local: L) -> Self

Create a provider.

remote is usually a Client, local is usually a Cache. However, both can be interchangeable. The only difference is that remote always wins in case of a sync conflict

Examples found in repository

examples/shared.rs (line 34)

pub async fn initial_sync(cache_folder: &str) -> CalDavProvider {
    let cache_path = Path::new(cache_folder);

    let client = Client::new(URL, USERNAME, PASSWORD).unwrap();
    let cache = match Cache::from_folder(&cache_path) {
        Ok(cache) => cache,
        Err(err) => {
            log::warn!("Invalid cache file: {}. Using a default cache", err);
            Cache::new(&cache_path)
        }
    };
    let mut provider = CalDavProvider::new(client, cache);


    let cals = provider.local().get_calendars().await.unwrap();
    println!("---- Local items, before sync -----");
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    println!("Starting a sync...");
    println!("Depending on your RUST_LOG value, you may see more or less details about the progress.");
    // Note that we could use sync_with_feedback() to have better and formatted feedback
    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync.");
    }
    provider.local().save_to_folder().unwrap();

    println!("---- Local items, after sync -----");
    let cals = provider.local().get_calendars().await.unwrap();
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    provider
}

pub fn local(&self) -> &L

Returns the data source described as local

Examples found in repository

examples/toggle-completions.rs (line 40)

async fn toggle_all_tasks_and_sync_again(provider: &mut CalDavProvider) -> Result<(), Box<dyn Error>> {
    let mut n_toggled = 0;

    for (_url, cal) in provider.local().get_calendars_sync()?.iter() {
        for (_url, item) in cal.lock().unwrap().get_items_mut_sync()?.iter_mut() {
            match item {
                Item::Task(task) => {
                    match task.completed() {
                        false => task.set_completion_status(CompletionStatus::Completed(Some(Utc::now()))),
                        true => task.set_completion_status(CompletionStatus::Uncompleted),
                    };
                    n_toggled += 1;
                }
                Item::Event(_) => {
                    // Not doing anything with calendar events
                },
            }
        }
    }

    println!("{} items toggled.", n_toggled);
    println!("Syncing...");

    provider.sync().await;

    println!("Syncing complete.");

    Ok(())
}

examples/shared.rs (line 37)

pub async fn initial_sync(cache_folder: &str) -> CalDavProvider {
    let cache_path = Path::new(cache_folder);

    let client = Client::new(URL, USERNAME, PASSWORD).unwrap();
    let cache = match Cache::from_folder(&cache_path) {
        Ok(cache) => cache,
        Err(err) => {
            log::warn!("Invalid cache file: {}. Using a default cache", err);
            Cache::new(&cache_path)
        }
    };
    let mut provider = CalDavProvider::new(client, cache);


    let cals = provider.local().get_calendars().await.unwrap();
    println!("---- Local items, before sync -----");
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    println!("Starting a sync...");
    println!("Depending on your RUST_LOG value, you may see more or less details about the progress.");
    // Note that we could use sync_with_feedback() to have better and formatted feedback
    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync.");
    }
    provider.local().save_to_folder().unwrap();

    println!("---- Local items, after sync -----");
    let cals = provider.local().get_calendars().await.unwrap();
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    provider
}

examples/provider-sync.rs (line 59)

async fn add_items_and_sync_again(provider: &mut CalDavProvider) {
    println!("\nNow, we'll add a calendar and a few tasks and run the sync again.");
    pause();

    // Create a new calendar...
    let new_calendar_url: Url = EXAMPLE_CREATED_CALENDAR_URL.parse().unwrap();
    let new_calendar_name = "A brave new calendar".to_string();
    if let Err(_err) = provider.local_mut()
        .create_calendar(new_calendar_url.clone(), new_calendar_name.clone(), SupportedComponents::TODO, Some("#ff8000".parse().unwrap()))
        .await {
            println!("Unable to add calendar, maybe it exists already. We're not adding it after all.");
    }

    // ...and add a task in it
    let new_name = "This is a new task in a new calendar";
    let new_task = Task::new(String::from(new_name), true, &new_calendar_url);
    provider.local().get_calendar(&new_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    // Also create a task in a previously existing calendar
    let changed_calendar_url: Url = EXAMPLE_EXISTING_CALENDAR_URL.parse().unwrap();
    let new_task_name = "This is a new task we're adding as an example, with ÜTF-8 characters";
    let new_task = Task::new(String::from(new_task_name), false, &changed_calendar_url);
    let new_url = new_task.url().clone();
    provider.local().get_calendar(&changed_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the new task '{}' and the new calendar '{}'", new_task_name, new_calendar_name);
    }
    provider.local().save_to_folder().unwrap();

    complete_item_and_sync_again(provider, &changed_calendar_url, &new_url).await;
}

async fn complete_item_and_sync_again(
    provider: &mut CalDavProvider,
    changed_calendar_url: &Url,
    url_to_complete: &Url)
{
    println!("\nNow, we'll mark this last task as completed, and run the sync again.");
    pause();

    let completion_status = CompletionStatus::Completed(Some(Utc::now()));
    provider.local().get_calendar(changed_calendar_url).await.unwrap()
        .lock().unwrap().get_item_by_url_mut(url_to_complete).await.unwrap()
        .unwrap_task_mut()
        .set_completion_status(completion_status);

    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the completed task");
    }
    provider.local().save_to_folder().unwrap();

    remove_items_and_sync_again(provider, changed_calendar_url, url_to_complete).await;
}

async fn remove_items_and_sync_again(
    provider: &mut CalDavProvider,
    changed_calendar_url: &Url,
    id_to_remove: &Url)
{
    println!("\nNow, we'll delete this last task, and run the sync again.");
    pause();

    // Remove the task we had created
    provider.local().get_calendar(changed_calendar_url).await.unwrap()
        .lock().unwrap()
        .mark_for_deletion(id_to_remove).await.unwrap();

    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the deleted task");
    }
    provider.local().save_to_folder().unwrap();

    println!("Done. You can start this example again to see the cache being restored from its current saved state")
}

pub fn local_mut(&mut self) -> &mut L

Returns the data source described as local

Examples found in repository

examples/provider-sync.rs (line 50)

async fn add_items_and_sync_again(provider: &mut CalDavProvider) {
    println!("\nNow, we'll add a calendar and a few tasks and run the sync again.");
    pause();

    // Create a new calendar...
    let new_calendar_url: Url = EXAMPLE_CREATED_CALENDAR_URL.parse().unwrap();
    let new_calendar_name = "A brave new calendar".to_string();
    if let Err(_err) = provider.local_mut()
        .create_calendar(new_calendar_url.clone(), new_calendar_name.clone(), SupportedComponents::TODO, Some("#ff8000".parse().unwrap()))
        .await {
            println!("Unable to add calendar, maybe it exists already. We're not adding it after all.");
    }

    // ...and add a task in it
    let new_name = "This is a new task in a new calendar";
    let new_task = Task::new(String::from(new_name), true, &new_calendar_url);
    provider.local().get_calendar(&new_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    // Also create a task in a previously existing calendar
    let changed_calendar_url: Url = EXAMPLE_EXISTING_CALENDAR_URL.parse().unwrap();
    let new_task_name = "This is a new task we're adding as an example, with ÜTF-8 characters";
    let new_task = Task::new(String::from(new_task_name), false, &changed_calendar_url);
    let new_url = new_task.url().clone();
    provider.local().get_calendar(&changed_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the new task '{}' and the new calendar '{}'", new_task_name, new_calendar_name);
    }
    provider.local().save_to_folder().unwrap();

    complete_item_and_sync_again(provider, &changed_calendar_url, &new_url).await;
}

pub fn remote(&self) -> &R

Returns the data source described as remote.

Apart from tests, there are very few (if any) reasons to access remote directly. Usually, you should rather use the local source, which (usually) is a much faster local cache. To be sure local accurately mirrors the remote source, you can run Provider::sync

pub async fn sync_with_feedback( &mut self, feedback_sender: FeedbackSender, ) -> bool

Performs a synchronisation between local and remote, and provide feeedback to the user about the progress.

This bidirectional sync applies additions/deletions made on a source to the other source. In case of conflicts (the same item has been modified on both ends since the last sync, remote always wins).

It returns whether the sync was totally successful (details about errors are logged using the log::* macros). In case errors happened, the sync might have been partially executed but your data will never be correupted (either locally nor in the server). Simply run this function again, it will re-start a sync, picking up where it failed.

pub async fn sync(&mut self) -> bool

Performs a synchronisation between local and remote, without giving any feedback.

See Self::sync_with_feedback

Examples found in repository

examples/toggle-completions.rs (line 60)

async fn toggle_all_tasks_and_sync_again(provider: &mut CalDavProvider) -> Result<(), Box<dyn Error>> {
    let mut n_toggled = 0;

    for (_url, cal) in provider.local().get_calendars_sync()?.iter() {
        for (_url, item) in cal.lock().unwrap().get_items_mut_sync()?.iter_mut() {
            match item {
                Item::Task(task) => {
                    match task.completed() {
                        false => task.set_completion_status(CompletionStatus::Completed(Some(Utc::now()))),
                        true => task.set_completion_status(CompletionStatus::Uncompleted),
                    };
                    n_toggled += 1;
                }
                Item::Event(_) => {
                    // Not doing anything with calendar events
                },
            }
        }
    }

    println!("{} items toggled.", n_toggled);
    println!("Syncing...");

    provider.sync().await;

    println!("Syncing complete.");

    Ok(())
}

examples/shared.rs (line 44)

pub async fn initial_sync(cache_folder: &str) -> CalDavProvider {
    let cache_path = Path::new(cache_folder);

    let client = Client::new(URL, USERNAME, PASSWORD).unwrap();
    let cache = match Cache::from_folder(&cache_path) {
        Ok(cache) => cache,
        Err(err) => {
            log::warn!("Invalid cache file: {}. Using a default cache", err);
            Cache::new(&cache_path)
        }
    };
    let mut provider = CalDavProvider::new(client, cache);


    let cals = provider.local().get_calendars().await.unwrap();
    println!("---- Local items, before sync -----");
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    println!("Starting a sync...");
    println!("Depending on your RUST_LOG value, you may see more or less details about the progress.");
    // Note that we could use sync_with_feedback() to have better and formatted feedback
    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync.");
    }
    provider.local().save_to_folder().unwrap();

    println!("---- Local items, after sync -----");
    let cals = provider.local().get_calendars().await.unwrap();
    kitchen_fridge::utils::print_calendar_list(&cals).await;

    provider
}

examples/provider-sync.rs (line 72)

async fn add_items_and_sync_again(provider: &mut CalDavProvider) {
    println!("\nNow, we'll add a calendar and a few tasks and run the sync again.");
    pause();

    // Create a new calendar...
    let new_calendar_url: Url = EXAMPLE_CREATED_CALENDAR_URL.parse().unwrap();
    let new_calendar_name = "A brave new calendar".to_string();
    if let Err(_err) = provider.local_mut()
        .create_calendar(new_calendar_url.clone(), new_calendar_name.clone(), SupportedComponents::TODO, Some("#ff8000".parse().unwrap()))
        .await {
            println!("Unable to add calendar, maybe it exists already. We're not adding it after all.");
    }

    // ...and add a task in it
    let new_name = "This is a new task in a new calendar";
    let new_task = Task::new(String::from(new_name), true, &new_calendar_url);
    provider.local().get_calendar(&new_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    // Also create a task in a previously existing calendar
    let changed_calendar_url: Url = EXAMPLE_EXISTING_CALENDAR_URL.parse().unwrap();
    let new_task_name = "This is a new task we're adding as an example, with ÜTF-8 characters";
    let new_task = Task::new(String::from(new_task_name), false, &changed_calendar_url);
    let new_url = new_task.url().clone();
    provider.local().get_calendar(&changed_calendar_url).await.unwrap()
        .lock().unwrap().add_item(Item::Task(new_task)).await.unwrap();


    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the new task '{}' and the new calendar '{}'", new_task_name, new_calendar_name);
    }
    provider.local().save_to_folder().unwrap();

    complete_item_and_sync_again(provider, &changed_calendar_url, &new_url).await;
}

async fn complete_item_and_sync_again(
    provider: &mut CalDavProvider,
    changed_calendar_url: &Url,
    url_to_complete: &Url)
{
    println!("\nNow, we'll mark this last task as completed, and run the sync again.");
    pause();

    let completion_status = CompletionStatus::Completed(Some(Utc::now()));
    provider.local().get_calendar(changed_calendar_url).await.unwrap()
        .lock().unwrap().get_item_by_url_mut(url_to_complete).await.unwrap()
        .unwrap_task_mut()
        .set_completion_status(completion_status);

    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the completed task");
    }
    provider.local().save_to_folder().unwrap();

    remove_items_and_sync_again(provider, changed_calendar_url, url_to_complete).await;
}

async fn remove_items_and_sync_again(
    provider: &mut CalDavProvider,
    changed_calendar_url: &Url,
    id_to_remove: &Url)
{
    println!("\nNow, we'll delete this last task, and run the sync again.");
    pause();

    // Remove the task we had created
    provider.local().get_calendar(changed_calendar_url).await.unwrap()
        .lock().unwrap()
        .mark_for_deletion(id_to_remove).await.unwrap();

    if provider.sync().await == false {
        log::warn!("Sync did not complete, see the previous log lines for more info. You can safely start a new sync. The new task may not have been synced.");
    } else {
        println!("Done syncing the deleted task");
    }
    provider.local().save_to_folder().unwrap();

    println!("Done. You can start this example again to see the cache being restored from its current saved state")
}

Trait Implementations

impl<L, T, R, U> Debug for Provider<L, T, R, U>

where L: CalDavSource<T> + Debug, T: CompleteCalendar + Sync + Send + Debug, R: CalDavSource<U> + Debug, U: DavCalendar + Sync + Send + Debug,

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

Formats the value using the given formatter.