## ECalBackend ECalBackend |

## Synopsis

    struct              ECalBackend;
    #define             CLIENT_BACKEND_PROPERTY_ONLINE
    #define             CLIENT_BACKEND_PROPERTY_READONLY
    #define             CLIENT_BACKEND_PROPERTY_CACHE_DIR
    #define             CLIENT_BACKEND_PROPERTY_CAPABILITIES
    #define             CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS
    #define             CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS
    #define             CAL_BACKEND_PROPERTY_DEFAULT_OBJECT
    #define             CAL_BACKEND_PROPERTY_REVISION
    icalcomponent_kind  e_cal_backend_get_kind              (ECalBackend *backend);
    ESourceRegistry *   e_cal_backend_get_registry          (ECalBackend *backend);
    gboolean            e_cal_backend_get_writable          (ECalBackend *backend);
    void                e_cal_backend_set_writable          (ECalBackend *backend,
                                                             gboolean writable);
    gboolean            e_cal_backend_is_opened             (ECalBackend *backend);
    gboolean            e_cal_backend_is_readonly           (ECalBackend *backend);
    gboolean            e_cal_backend_is_removed            (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);
    gchar *             e_cal_backend_create_cache_filename (ECalBackend *backend,
                                                             const gchar *uid,
                                                             const gchar *filename,
                                                             gint fileindex);
    void                e_cal_backend_add_client            (ECalBackend *backend,
                                                             EDataCal *cal);
    void                e_cal_backend_remove_client         (ECalBackend *backend,
                                                             EDataCal *cal);
    void                e_cal_backend_add_view              (ECalBackend *backend,
                                                             EDataCalView *view);
    void                e_cal_backend_remove_view           (ECalBackend *backend,
                                                             EDataCalView *view);
    GList *             e_cal_backend_list_views            (ECalBackend *backend);
    void                e_cal_backend_set_notification_proxy
                                                            (ECalBackend *backend,
                                                             ECalBackend *proxy);
    void                e_cal_backend_get_backend_property  (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *prop_name);
    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_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_free_busy         (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *users,
                                                             time_t start,
                                                             time_t end);
    void                e_cal_backend_create_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *calobjs);
    void                e_cal_backend_modify_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *calobjs,
                                                             ECalObjModType mod);
    void                e_cal_backend_remove_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *ids,
                                                             ECalObjModType mod);
    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_attachment_uris   (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *uid,
                                                             const gchar *rid);
    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_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_start_view            (ECalBackend *backend,
                                                             EDataCalView *view);
    void                e_cal_backend_stop_view             (ECalBackend *backend,
                                                             EDataCalView *view);
    void                e_cal_backend_notify_component_created
                                                            (ECalBackend *backend,
                                                             ECalComponent *component);
    void                e_cal_backend_notify_component_modified
                                                            (ECalBackend *backend,
                                                             ECalComponent *old_component,
                                                             ECalComponent *new_component);
    void                e_cal_backend_notify_component_removed
                                                            (ECalBackend *backend,
                                                             const ECalComponentId *id,
                                                             ECalComponent *old_component,
                                                             ECalComponent *new_component);
    void                e_cal_backend_notify_error          (ECalBackend *backend,
                                                             const gchar *message);
    void                e_cal_backend_notify_property_changed
                                                            (ECalBackend *backend,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);
    void                e_cal_backend_empty_cache           (ECalBackend *backend,
                                                             struct _ECalBackendCache *cache);
    void                e_cal_backend_set_is_removed        (ECalBackend *backend,
                                                             gboolean is_removed);

    #define             CLIENT_BACKEND_PROPERTY_OPENED
    #define             CLIENT_BACKEND_PROPERTY_OPENING
    gboolean            e_cal_backend_is_opening            (ECalBackend *backend);
    void                e_cal_backend_set_backend_property  (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);
    void                e_cal_backend_foreach_view          (ECalBackend *backend,
                                                             gboolean (*callback) (EDataCalView *view, gpointer user_data),
                                                             gpointer user_data);
    void                e_cal_backend_notify_opened         (ECalBackend *backend,
                                                             GError *error);
    void                e_cal_backend_notify_readonly       (ECalBackend *backend,
                                                             gboolean is_readonly);
    void                e_cal_backend_notify_online         (ECalBackend *backend,
                                                             gboolean is_online);
    void                e_cal_backend_respond_opened        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

## Object Hierarchy

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

## Implemented Interfaces

ECalBackend implements ETimezoneCache.

## Properties

      "cache-dir"                gchar*                : Read / Write
      "kind"                     gulong                : Read / Write / Construct Only
      "registry"                 ESourceRegistry*      : Read / Write / Construct Only
      "writable"                 gboolean              : Read / Write

## Description

## Details

### struct ECalBackend

    struct ECalBackend;

### CLIENT_BACKEND_PROPERTY_ONLINE

    #define CLIENT_BACKEND_PROPERTY_ONLINE			"online"

FIXME: Document me.

Since 3.2

### CLIENT_BACKEND_PROPERTY_READONLY

    #define CLIENT_BACKEND_PROPERTY_READONLY		"readonly"

FIXME: Document me.

Since 3.2

### CLIENT_BACKEND_PROPERTY_CACHE_DIR

    #define CLIENT_BACKEND_PROPERTY_CACHE_DIR		"cache-dir"

FIXME: Document me.

Since 3.2

### CLIENT_BACKEND_PROPERTY_CAPABILITIES

    #define CLIENT_BACKEND_PROPERTY_CAPABILITIES		"capabilities"

FIXME: Document me.

Since 3.2

### CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS

    #define CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS		"cal-email-address"

FIXME: Document me.

Since 3.2

### CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS

    #define CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS "alarm-email-address"

FIXME: Document me.

Since 3.2

### CAL_BACKEND_PROPERTY_DEFAULT_OBJECT

    #define CAL_BACKEND_PROPERTY_DEFAULT_OBJECT		"default-object"

FIXME: Document me.

Since 3.2

### CAL_BACKEND_PROPERTY_REVISION

    #define CAL_BACKEND_PROPERTY_REVISION			"revision"

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the calendar revision was observed.

Since 3.4

### 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_registry ()

    ESourceRegistry *   e_cal_backend_get_registry          (ECalBackend *backend);

Returns the data source registry to which "source" belongs.

`backend` : | an ECalBackend
Returns : | an ESourceRegistry

Since 3.6

### e_cal_backend_get_writable ()

    gboolean            e_cal_backend_get_writable          (ECalBackend *backend);

Returns whether `backend` will accept changes to its data content.

`backend` : | an ECalBackend
Returns : | whether `backend` is writable

Since 3.8

### e_cal_backend_set_writable ()

    void                e_cal_backend_set_writable          (ECalBackend *backend,
                                                             gboolean writable);

Sets whether `backend` will accept changes to its data content.

`backend` : | an ECalBackend
`writable` : | whether `backend` is writable

Since 3.8

### e_cal_backend_is_opened ()

    gboolean            e_cal_backend_is_opened             (ECalBackend *backend);

Checks if `backend`'s storage has been opened (and authenticated, if necessary) and the backend itself is ready for accessing. This property is changed automatically within call of `e_cal_backend_notify_opened()`.

`backend` : | an ECalBackend
Returns : | `TRUE` if fully opened, `FALSE` otherwise.

Since 3.2

### e_cal_backend_is_readonly ()

    gboolean            e_cal_backend_is_readonly           (ECalBackend *backend);

`backend` : | an ECalBackend
Returns : | Whether is backend read-only. This value is the last used in a call of `e_cal_backend_notify_readonly()`.

Since 3.2

### e_cal_backend_is_removed ()

    gboolean            e_cal_backend_is_removed            (ECalBackend *backend);

Checks if `backend` has been removed from its physical storage.

`backend` : | an ECalBackend
Returns : | `TRUE` if `backend` has been removed, `FALSE` otherwise.

Since 3.2

### 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_create_cache_filename ()

    gchar *             e_cal_backend_create_cache_filename (ECalBackend *backend,
                                                             const gchar *uid,
                                                             const gchar *filename,
                                                             gint fileindex);

`backend` : | an ECalBackend
`uid` : | a component UID
`filename` : | a filename to use; can be NULL
`fileindex` : | index of a file; used only when `filename` is NULL
Returns : | a filename for an attachment in a local cache dir. Free returned pointer with a `g_free()`.

Since 3.4

### 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_add_view ()

    void                e_cal_backend_add_view              (ECalBackend *backend,
                                                             EDataCalView *view);

Adds a view to the list of live views being run by the given backend. Doing so means that any listener on the view will get notified of any change that affect the live view.

`backend` : | an ECalBackend
`view` : | An EDataCalView object.

Since 3.2

### e_cal_backend_remove_view ()

    void                e_cal_backend_remove_view           (ECalBackend *backend,
                                                             EDataCalView *view);

Removes view from the list of live views for the backend.

`backend` : | an ECalBackend
`view` : | An EDataCalView object, previously added with `ref` e_cal_backend_add_view.

Since 3.2

### e_cal_backend_list_views ()

    GList *             e_cal_backend_list_views            (ECalBackend *backend);

Returns a list of ECalBookView instances added with `e_cal_backend_add_view()`.

The views returned in the list are referenced for thread-safety. They must each be unreferenced with `g_object_unref()` when finished with them. Free the returned list itself with `g_list_free()`.

An easy way to free the list properly in one step is as follows:

    1
    g_list_free_full (list, g_object_unref);

`backend` : | an ECalBackend
Returns : | a list of cal views

Since 3.8

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

Since 3.2

### e_cal_backend_get_backend_property ()

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

Calls the get_backend_property method on the given backend. This might be finished with `e_data_cal_respond_get_backend_property()`. Default implementation takes care of common properties and returns an 'unsupported' error for any unknown properties. The subclass may always call this default implementation for properties which fetching it doesn't overwrite.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`prop_name` : | property name to get value of; cannot be NULL

Since 3.2

### 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_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_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_create_objects ()

    void                e_cal_backend_create_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *calobjs);

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

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobjs` : | The objects to create (list of gchar *).

Since 3.6

### e_cal_backend_modify_objects ()

    void                e_cal_backend_modify_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *calobjs,
                                                             ECalObjModType mod);

Calls the modify_objects method on the given backend. This might be finished with `e_data_cal_respond_modify_objects()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`calobjs` : | Objects to be modified (list of gchar *).
`mod` : | Type of modification.

Since 3.6

### e_cal_backend_remove_objects ()

    void                e_cal_backend_remove_objects        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *ids,
                                                             ECalObjModType mod);

Removes objects 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_objects()`.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`ids` : | List of ECalComponentId objects identifying the objects to remove
`mod` : | Type of removal.

Since 3.6

### 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_attachment_uris ()

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

Queries a calendar backend for attachments present in 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_attachment_uris()`.

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

Since 3.2

### 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_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.
Returns : | the icaltimezone* corresponding to the TZID, or NULL if the TZID can't be found. This might be finished with `e_data_cal_respond_get_timezone()`.

### 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` : | The timezone object, in a string.

### e_cal_backend_start_view ()

    void                e_cal_backend_start_view            (ECalBackend *backend,
                                                             EDataCalView *view);

Starts a new live view on the given backend.

`backend` : | an ECalBackend
`view` : | The view to be started.

Since 3.2

### e_cal_backend_stop_view ()

    void                e_cal_backend_stop_view             (ECalBackend *backend,
                                                             EDataCalView *view);

Stops a previously started live view on the given backend.

`backend` : | an ECalBackend
`view` : | The view to be stopped.

Since 3.2

### e_cal_backend_notify_component_created ()

    void                e_cal_backend_notify_component_created
                                                            (ECalBackend *backend,
                                                             ECalComponent *component);

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

Like `e_cal_backend_notify_object_created()` except takes an ECalComponent instead of an ical string representation and uses the EDataCalView's fields-of-interest to filter out unwanted information from ical strings sent over the bus.

`backend` : | an ECalBackend
`component` : | the newly created ECalComponent

Since 3.4

### e_cal_backend_notify_component_modified ()

    void                e_cal_backend_notify_component_modified
                                                            (ECalBackend *backend,
                                                             ECalComponent *old_component,
                                                             ECalComponent *new_component);

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

Like `e_cal_backend_notify_object_modified()` except takes an ECalComponent instead of an ical string representation and uses the EDataCalView's fields-of-interest to filter out unwanted information from ical strings sent over the bus.

`backend` : | an ECalBackend
`old_component` : | the ECalComponent before the modification
`new_component` : | the ECalComponent after the modification

Since 3.4

### e_cal_backend_notify_component_removed ()

    void                e_cal_backend_notify_component_removed
                                                            (ECalBackend *backend,
                                                             const ECalComponentId *id,
                                                             ECalComponent *old_component,
                                                             ECalComponent *new_component);

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

Like `e_cal_backend_notify_object_removed()` except takes an ECalComponent instead of an ical string representation and uses the EDataCalView's fields-of-interest to filter out unwanted information from ical strings sent over the bus.

`backend` : | an ECalBackend
`id` : | the Id of the removed object
`old_component` : | the removed component
`new_component` : | the component after the removal. This only applies to recurrent appointments that had an instance removed. In that case, this function notifies a modification instead of a removal.

Since 3.4

### 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_property_changed ()

    void                e_cal_backend_notify_property_changed
                                                            (ECalBackend *backend,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);

Notifies client about property value change.

`backend` : | an ECalBackend
`prop_name` : | property name, which changed
`prop_value` : | new property value

Since 3.2

### 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

### e_cal_backend_set_is_removed ()

    void                e_cal_backend_set_is_removed        (ECalBackend *backend,
                                                             gboolean is_removed);

Sets the flag indicating whether `backend` was removed to `is_removed`. Meant to be used by backend implementations.

`backend` : | an ECalBackend
`is_removed` : | A flag indicating whether the backend's storage was removed

Since 3.2

### CLIENT_BACKEND_PROPERTY_OPENED

    #define CLIENT_BACKEND_PROPERTY_OPENED			"opened"

### Warning

`CLIENT_BACKEND_PROPERTY_OPENED` has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened anymore. This property will always return `TRUE`.

FIXME: Document me.

Since 3.2

### CLIENT_BACKEND_PROPERTY_OPENING

    #define CLIENT_BACKEND_PROPERTY_OPENING			"opening"

### Warning

`CLIENT_BACKEND_PROPERTY_OPENING` has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened anymore. This property will always return `FALSE`.

FIXME: Document me.

Since 3.2

### e_cal_backend_is_opening ()

    gboolean            e_cal_backend_is_opening            (ECalBackend *backend);

### Warning

`e_cal_backend_is_opening` has been deprecated since version 3.8 and should not be used in newly-written code. This function is no longer relevant, and always returns `FALSE`.

Checks if `backend` is processing its opening phase, which includes everything since the `e_cal_backend_open()` call, through authentication, up to `e_cal_backend_notify_opened()`. This property is managed automatically and the backend deny every operation except of cancel and authenticate_user while it is being opening.

`backend` : | an ECalBackend
Returns : | `FALSE` always

Since 3.2

### e_cal_backend_set_backend_property ()

    void                e_cal_backend_set_backend_property  (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);

### Warning

`e_cal_backend_set_backend_property` has been deprecated since version 3.8 and should not be used in newly-written code. This function no longer does anything.

Calls the set_backend_property method on the given backend. This might be finished with `e_data_cal_respond_set_backend_property()`. Default implementation simply returns an 'unsupported' error. The subclass may always call this default implementation for properties which fetching it doesn't overwrite.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`prop_name` : | property name to change; cannot be NULL
`prop_value` : | value to set to `prop_name`; cannot be NULL

Since 3.2

### e_cal_backend_foreach_view ()

    void                e_cal_backend_foreach_view          (ECalBackend *backend,
                                                             gboolean (*callback) (EDataCalView *view, gpointer user_data),
                                                             gpointer user_data);

### Warning

`e_cal_backend_foreach_view` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_cal_backend_list_views()` instead.

Calls `callback` for each known calendar view of this `backend`. `callback` returns `FALSE` to stop further processing.

`backend` : | an ECalBackend
`callback` : | callback to call
`user_data` : | user_data passed into the `callback`

Since 3.2

### e_cal_backend_notify_opened ()

    void                e_cal_backend_notify_opened         (ECalBackend *backend,
                                                             GError *error);

### Warning

`e_cal_backend_notify_opened` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_data_cal_respond_open()` instead.

Notifies clients that `backend` finished its opening phase. See `e_cal_backend_open()` for more information how the opening phase works. Calling this function changes 'opening' property, same as 'opened'. 'opening' is set to `FALSE` and the backend is considered 'opened' only if the `error` is `NULL`.

See also: `e_cal_backend_respond_opened()`

Note: The `error` is freed automatically if not `NULL`.

Meant to be used by backend implementations.

`backend` : | an ECalBackend
`error` : | a GError corresponding to the error encountered during the opening phase. Use `NULL` for success. The `error` is freed automatically if not `NULL`.

Since 3.2

### e_cal_backend_notify_readonly ()

    void                e_cal_backend_notify_readonly       (ECalBackend *backend,
                                                             gboolean is_readonly);

### Warning

`e_cal_backend_notify_readonly` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_cal_backend_set_writable()` instead.

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_online ()

    void                e_cal_backend_notify_online         (ECalBackend *backend,
                                                             gboolean is_online);

### Warning

`e_cal_backend_notify_online` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_backend_set_online()` instead.

Notifies clients of `backend`'s connection status indicated by `is_online`. Meant to be used by backend implementations.

`backend` : | an ECalBackend
`is_online` : | flag indicating whether `backend` is connected and online

Since 3.2

### e_cal_backend_respond_opened ()

    void                e_cal_backend_respond_opened        (ECalBackend *backend,
                                                             EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

### Warning

`e_cal_backend_respond_opened` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_data_book_respond_open()` instead.

This is a replacement for `e_data_cal_respond_open()` for cases where the finish of 'open' method call also finishes backend opening phase. This function covers calling of both `e_cal_backend_notify_opened()` and `e_data_cal_respond_open()` with the same `error`.

See `e_cal_backend_open()` for more details how the opening phase works.

`backend` : | an ECalBackend
`cal` : | an EDataCal
`opid` : | an operation ID
`error` : | result error; can be `NULL`, if it isn't then it's automatically freed

Since 3.2

## Property Details

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

      "cache-dir"                gchar*                : Read / Write

The backend's cache directory.

Default value: NULL

### The `"kind"` property

      "kind"                     gulong                : Read / Write / Construct Only

The kind of iCalendar components this backend manages.

Allowed values: <= 25

### The `"registry"` property

      "registry"                 ESourceRegistry*      : Read / Write / Construct Only

Data source registry.

### The `"writable"` property

      "writable"                 gboolean              : Read / Write

Whether the backend will accept changes.

Default value: FALSE