## ECalBackend

ECalBackend — Base class for calendar/tasks backend implementations.

## Synopsis

                        ECalBackend;
    ESource *           e_cal_backend_get_source            (ECalBackend *backend);
    const gchar *       e_cal_backend_get_uri               (ECalBackend *backend);
    icalcomponent_kind  e_cal_backend_get_kind              (ECalBackend *backend);
    const gchar *       e_cal_backend_get_cache_dir         (ECalBackend *backend);
    void                e_cal_backend_set_cache_dir         (ECalBackend *backend,
                                                             const gchar *cache_dir);
    void                e_cal_backend_add_client            (ECalBackend *backend,
                                                             EDataCal *cal);
    void                e_cal_backend_remove_client         (ECalBackend *backend,
                                                             EDataCal *cal);
    void                e_cal_backend_open                  (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             gboolean only_if_exists);
    void                e_cal_backend_refresh               (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable);
    void                e_cal_backend_remove                (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable);
    void                e_cal_backend_create_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);
    void                e_cal_backend_modify_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj,
                                                             CalObjModType mod);
    void                e_cal_backend_remove_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid,
                                                             CalObjModType mod);
    void                e_cal_backend_discard_alarm         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid,
                                                             const gchar *auid);
    void                e_cal_backend_receive_objects       (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);
    void                e_cal_backend_send_objects          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);
    void                e_cal_backend_get_object            (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid);
    void                e_cal_backend_get_object_list       (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *sexp);
    void                e_cal_backend_get_timezone          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *tzid);
    void                e_cal_backend_add_timezone          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *tzobject);
    void                e_cal_backend_get_free_busy         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *users,
                                                             time_t start,
                                                             time_t end);
    icaltimezone *      e_cal_backend_internal_get_timezone (ECalBackend *backend,
                                                             const gchar *tzid);
    void                e_cal_backend_set_notification_proxy
                                                            (ECalBackend *backend,
                                                             ECalBackend *proxy);
    void                e_cal_backend_notify_object_created (ECalBackend *backend,
                                                             const gchar *calobj);
    void                e_cal_backend_notify_object_modified
                                                            (ECalBackend *backend,
                                                             const gchar *old_object,
                                                             const gchar *object);
    void                e_cal_backend_notify_object_removed (ECalBackend *backend,
                                                             const ECalComponentId *id,
                                                             const gchar *old_object,
                                                             const gchar *object);
    void                e_cal_backend_notify_auth_required  (ECalBackend *backend,
                                                             gboolean is_self,
                                                             const ECredentials *credentials);
    void                e_cal_backend_notify_error          (ECalBackend *backend,
                                                             const gchar *message);
    void                e_cal_backend_notify_readonly       (ECalBackend *backend,
                                                             gboolean is_readonly);
    void                e_cal_backend_notify_objects_added  (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *objects);
    void                e_cal_backend_notify_objects_removed
                                                            (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *ids);
    void                e_cal_backend_notify_objects_modified
                                                            (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *objects);
    void                e_cal_backend_empty_cache           (ECalBackend *backend,
                                                             struct _ECalBackendCache *cache);

## Object Hierarchy

      GObject
       +----ECalBackend
             +----ECalBackendSync

## Properties

      "cache-dir"                gchar*                : Read / Write
      "kind"                     gulong                : Read / Write / Construct Only
      "source"                   ESource*              : Read / Write / Construct Only
      "uri"                      gchar*                : Read / Write / Construct Only

## Signals

      "last-client-gone"                               : Run First

## Description

## Details

### ECalBackend

    typedef struct _ECalBackend ECalBackend;

### e_cal_backend_get_source ()

    ESource *           e_cal_backend_get_source            (ECalBackend *backend);

Gets the ESource associated with the given backend.

`backend` : | an ECalBackend
Returns : | The ESource for the backend.

### e_cal_backend_get_uri ()

    const gchar *       e_cal_backend_get_uri               (ECalBackend *backend);

Queries the URI of a calendar backend, which must already have an open calendar.

`backend` : | an ECalBackend
Returns : | The URI where the calendar is stored.

### e_cal_backend_get_kind ()

    icalcomponent_kind  e_cal_backend_get_kind              (ECalBackend *backend);

Gets the kind of components the given backend stores.

`backend` : | an ECalBackend
Returns : | The kind of components for this backend.

### e_cal_backend_get_cache_dir ()

    const gchar *       e_cal_backend_get_cache_dir         (ECalBackend *backend);

Returns the cache directory for the given backend.

`backend` : | an ECalBackend
Returns : | the cache directory for the backend

Since 2.32

### e_cal_backend_set_cache_dir ()

    void                e_cal_backend_set_cache_dir         (ECalBackend *backend,
                                                             const gchar *cache_dir);

Sets the cache directory for the given backend.

Note that ECalBackend is initialized with a usable default based on "source" and "kind" properties. Backends should not override the default without good reason.

`backend` : | an ECalBackend
`cache_dir` : | a local cache directory

Since 2.32

### e_cal_backend_add_client ()

    void                e_cal_backend_add_client            (ECalBackend *backend,
                                                             EDataCal *cal);

Adds a new client to the given backend. For any event, the backend will notify all clients added via this function.

`backend` : | an ECalBackend
`cal` : | an EDataCal

### e_cal_backend_remove_client ()

    void                e_cal_backend_remove_client         (ECalBackend *backend,
                                                             EDataCal *cal);

Removes a client from the list of connected clients to the given backend.

`backend` : | an ECalBackend
`cal` : | an EDataCal

### e_cal_backend_open ()

    void                e_cal_backend_open                  (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             gboolean only_if_exists);

Opens a calendar backend with data from a calendar stored at the specified URI. This might be finished with `e_data_cal_respond_open()` or `e_cal_backend_respond_opened()`, though the overall opening phase finishes only after call of `e_cal_backend_notify_opened()` after which call the backend is either fully opened (including authentication against (remote) server/storage) or an error was encountered during this opening phase. 'opened' and 'opening' properties are updated automatically. The backend refuses all other operations until the opening phase is finished.

The `e_cal_backend_notify_opened()` is called either from this function or from `e_cal_backend_authenticate_user()`, or after necessary steps initiated by these two functions.

The opening phase usually works like this: 1) client requests open for the backend 2) server receives this request and calls `e_cal_backend_open()` - the opening phase begun 3) either the backend is opened during this call, and notifies client with `e_cal_backend_notify_opened()` about that. This is usually for local backends; their opening phase is finished 4) or the backend requires authentication, thus it notifies client about that with `e_cal_backend_notify_auth_required()` and is waiting for credentials, which will be received from client by `e_cal_backend_authenticate_user()` call. Backend's opening phase is still running in this case, thus it doesn't call `e_cal_backend_notify_opened()` within `e_cal_backend_open()` call. 5) when backend receives credentials in `e_cal_backend_authenticate_user()` then it tries to authenticate against a server/storage with them and only after it knows result of the authentication, whether user was or wasn't authenticated, it notifies client with the result by `e_cal_backend_notify_opened()` and it's opening phase is finished now. If there was no error returned then the backend is considered opened, otherwise it's considered closed. Use AuthenticationFailed error when the given credentials were rejected by the server/store, which will result in a re-prompt on the client side, otherwise use AuthenticationRequired if there was anything wrong with the given credentials. Set error's message to a reason for a re-prompt, it'll be shown to a user. 6) client checks error returned from `e_cal_backend_notify_opened()` and reprompts for a password if it was AuthenticationFailed. Otherwise considers backend opened based on the error presence (no error means success).

In any case, the call of `e_cal_backend_open()` should be always finished with `e_data_cal_respond_open()`, which has no influence on the opening phase, or alternatively with `e_cal_backend_respond_opened()`. Never use authentication errors in `e_data_cal_respond_open()` to notify the client the authentication is required, there is `e_cal_backend_notify_auth_required()` for this.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`only_if_exists` : | Whether the calendar should be opened only if it already exists. If FALSE, a new calendar will be created when the specified `uri` does not exist.

### e_cal_backend_refresh ()

    void                e_cal_backend_refresh               (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable);

Refreshes the calendar being accessed by the given backend. This might be finished with `e_data_cal_respond_refresh()`, and it might be called as soon as possible; it doesn't mean that the refreshing is done after calling that, the backend is only notifying client whether it started the refresh process or not.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation

Since 2.30

### e_cal_backend_remove ()

    void                e_cal_backend_remove                (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable);

Removes the calendar being accessed by the given backend. This might be finished with `e_data_cal_respond_remove()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation

### e_cal_backend_create_object ()

    void                e_cal_backend_create_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);

Calls the create_object method on the given backend. This might be finished with `e_data_cal_respond_create_object()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobj` : | The object to create.

### e_cal_backend_modify_object ()

    void                e_cal_backend_modify_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj,
                                                             CalObjModType mod);

Calls the modify_object method on the given backend. This might be finished with `e_data_cal_respond_modify_object()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobj` : | Object to be modified.
`mod` : | Type of modification.

### e_cal_backend_remove_object ()

    void                e_cal_backend_remove_object         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid,
                                                             CalObjModType mod);

Removes an object in a calendar backend. The backend will notify all of its clients about the change. This might be finished with `e_data_cal_respond_remove_object()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`uid` : | Unique identifier of the object to remove.
`rid` : | A recurrence ID.
`mod` : | Type of removal.

### e_cal_backend_discard_alarm ()

    void                e_cal_backend_discard_alarm         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid,
                                                             const gchar *auid);

Discards alarm `auid` from the object identified by `uid` and `rid`. This might be finished with `e_data_cal_respond_discard_alarm()`. Default implementation of this method returns Not Supported error.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`uid` : | Unique identifier for a calendar object.
`rid` : | ID for the object's recurrence to discard alarm in.
`auid` : | Unique identifier of the alarm itself.

### e_cal_backend_receive_objects ()

    void                e_cal_backend_receive_objects       (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);

Calls the receive_objects method on the given backend. This might be finished with `e_data_cal_respond_receive_objects()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobj` : | iCalendar object.

### e_cal_backend_send_objects ()

    void                e_cal_backend_send_objects          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *calobj);

Calls the send_objects method on the given backend. This might be finished with `e_data_cal_respond_send_objects()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobj` : | iCalendar object to be sent.

### e_cal_backend_get_object ()

    void                e_cal_backend_get_object            (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid);

Queries a calendar backend for a calendar object based on its unique identifier and its recurrence ID (if a recurrent appointment). This might be finished with `e_data_cal_respond_get_object()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`uid` : | Unique identifier for a calendar object.
`rid` : | ID for the object's recurrence to get.

### e_cal_backend_get_object_list ()

    void                e_cal_backend_get_object_list       (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *sexp);

Calls the get_object_list method on the given backend. This might be finished with `e_data_cal_respond_get_object_list()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`sexp` : | Expression to search for.

### e_cal_backend_get_timezone ()

    void                e_cal_backend_get_timezone          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *tzid);

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`tzid` : | Unique identifier of a VTIMEZONE object. Note that this must not be NULL.

### e_cal_backend_add_timezone ()

    void                e_cal_backend_add_timezone          (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *tzobject);

Add a timezone object to the given backend. This might be finished with `e_data_cal_respond_add_timezone()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`tzobject` : |

### e_cal_backend_get_free_busy ()

    void                e_cal_backend_get_free_busy         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *users,
                                                             time_t start,
                                                             time_t end);

Gets a free/busy object for the given time interval. Client side is notified about free/busy objects throug `e_data_cal_report_free_busy_data()`. This might be finished with `e_data_cal_respond_get_free_busy()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`users` : | List of users to get free/busy information for.
`start` : | Start time for query.
`end` : | End time for query.

### e_cal_backend_internal_get_timezone ()

    icaltimezone *      e_cal_backend_internal_get_timezone (ECalBackend *backend,
                                                             const gchar *tzid);

Calls the internal_get_timezone method on the given backend.

`backend` : | an ECalBackend
`tzid` : | ID of the timezone to get.
Returns : |

### e_cal_backend_set_notification_proxy ()

    void                e_cal_backend_set_notification_proxy
                                                            (ECalBackend *backend,
                                                             ECalBackend *proxy);

Sets the backend that will act as notification proxy for the given backend.

`backend` : | an ECalBackend
`proxy` : | The calendar backend to act as notification proxy.

### e_cal_backend_notify_object_created ()

    void                e_cal_backend_notify_object_created (ECalBackend *backend,
                                                             const gchar *calobj);

Notifies each of the backend's listeners about a new object.

#`e_data_cal_notify_object_created()` calls this for you. You only need to call `e_cal_backend_notify_object_created()` yourself to report objects created by non-EDS clients.

`backend` : | an ECalBackend
`calobj` : | iCalendar representation of new object

### e_cal_backend_notify_object_modified ()

    void                e_cal_backend_notify_object_modified
                                                            (ECalBackend *backend,
                                                             const gchar *old_object,
                                                             const gchar *object);

Notifies each of the backend's listeners about a modified object.

#`e_data_cal_notify_object_modified()` calls this for you. You only need to call `e_cal_backend_notify_object_modified()` yourself to report objects modified by non-EDS clients.

`backend` : | an ECalBackend
`old_object` : | iCalendar representation of the original form of the object
`object` : | iCalendar representation of the new form of the object

### e_cal_backend_notify_object_removed ()

    void                e_cal_backend_notify_object_removed (ECalBackend *backend,
                                                             const ECalComponentId *id,
                                                             const gchar *old_object,
                                                             const gchar *object);

Notifies each of the backend's listeners about a removed object.

`e_data_cal_notify_object_removed()` calls this for you. You only need to call `e_cal_backend_notify_object_removed()` yourself to report objects removed by non-EDS clients.

`backend` : | an ECalBackend
`id` : | the Id of the removed object
`old_object` : | iCalendar representation of the removed object
`object` : |

### e_cal_backend_notify_auth_required ()

    void                e_cal_backend_notify_auth_required  (ECalBackend *backend,
                                                             gboolean is_self,
                                                             const ECredentials *credentials);

Notifies clients that `backend` requires authentication in order to connect. This function call does not influence 'opening', but influences 'opened' property, which is set to `FALSE` when `is_self` is `TRUE` or `credentials` is `NULL`. Opening phase is finished by `e_cal_backend_notify_opened()` if this is requested for `backend`.

See `e_cal_backend_open()` for a description how the whole opening phase works.

Meant to be used by backend implementations.

`backend` : | an ECalBackend
`is_self` : | Use `TRUE` to indicate the authentication is required for the `backend`, otheriwse the authentication is for any other source. Having `credentials` `NULL` means `is_self` automatically.
`credentials` : | an ECredentials that contains extra information for a source for which authentication is requested. This parameter can be NULL to indicate "for this calendar".

### e_cal_backend_notify_error ()

    void                e_cal_backend_notify_error          (ECalBackend *backend,
                                                             const gchar *message);

Notifies each of the backend's listeners about an error

`backend` : | an ECalBackend
`message` : | Error message

### e_cal_backend_notify_readonly ()

    void                e_cal_backend_notify_readonly       (ECalBackend *backend,
                                                             gboolean is_readonly);

Notifies all backend's clients about the current readonly state. Meant to be used by backend implementations.

`backend` : | an ECalBackend
`is_readonly` : | flag indicating readonly status

### e_cal_backend_notify_objects_added ()

    void                e_cal_backend_notify_objects_added  (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *objects);

`backend` : |
`view` : |
`objects` : |

Since 2.24

### e_cal_backend_notify_objects_removed ()

    void                e_cal_backend_notify_objects_removed
                                                            (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *ids);

`backend` : |
`view` : |
`ids` : |

Since 2.24

### e_cal_backend_notify_objects_modified ()

    void                e_cal_backend_notify_objects_modified
                                                            (ECalBackend *backend,
                                                             EDataCalView *view,
                                                             const GSList *objects);

`backend` : |
`view` : |
`objects` : |

Since 2.24

### e_cal_backend_empty_cache ()

    void                e_cal_backend_empty_cache           (ECalBackend *backend,
                                                             struct _ECalBackendCache *cache);

Empties backend's cache with all notifications and so on, thus all listening will know there is nothing in this backend.

`backend` : | an ECalBackend
`cache` : | Backend's cache to empty.

Since 2.28

## Property Details

### The `"cache-dir"` property

      "cache-dir"                gchar*                : Read / Write

Default value: NULL

### The `"kind"` property

      "kind"                     gulong                : Read / Write / Construct Only

Allowed values: <= 25

### The `"source"` property

      "source"                   ESource*              : Read / Write / Construct Only

### The `"uri"` property

      "uri"                      gchar*                : Read / Write / Construct Only

Default value: ""

## Signal Details

### The `"last-client-gone"` signal

    void                user_function                      (ECalBackend *ecalbackend,
                                                            gpointer     user_data)        : Run First

`ecalbackend` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.