ECalBackend

typedef struct {
	GObject object;

	ECalBackendPrivate *priv;
} ECalBackend;

CLIENT_BACKEND_PROPERTY_OPENED

#define CLIENT_BACKEND_PROPERTY_OPENED			"opened"

FIXME: Document me.

Since 3.2

CLIENT_BACKEND_PROPERTY_OPENING

#define CLIENT_BACKEND_PROPERTY_OPENING			"opening"

FIXME: Document me.

Since 3.2

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

e_cal_backend_get_source ()

ESource *           e_cal_backend_get_source            (ECalBackend *backend);

Gets the ESource associated with the given 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.

e_cal_backend_get_kind ()

icalcomponent_kind  e_cal_backend_get_kind              (ECalBackend *backend);

Gets the kind of components the given backend stores.

e_cal_backend_is_online ()

gboolean            e_cal_backend_is_online             (ECalBackend *backend);

Since 3.2

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

Since 3.2

e_cal_backend_is_opening ()

gboolean            e_cal_backend_is_opening            (ECalBackend *backend);

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.

Since 3.2

e_cal_backend_is_readonly ()

gboolean            e_cal_backend_is_readonly           (ECalBackend *backend);

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.

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.

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.

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.

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.

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.

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.

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);

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

Since 3.2

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.

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.

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);

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.

Since 3.2

e_cal_backend_set_online ()

void                e_cal_backend_set_online            (ECalBackend *backend,
                                                         gboolean is_online);

Sets the online mode of the calendar

Since 3.2

e_cal_backend_authenticate_user ()

void                e_cal_backend_authenticate_user     (ECalBackend *backend,
                                                         GCancellable *cancellable,
                                                         ECredentials *credentials);

Notifies backend about credentials provided by user to use for authentication. This notification is usually called during opening phase as a response to e_cal_backend_notify_auth_required() on the client side and it results in setting property 'opening' to TRUE unless the backend is already opened. This function finishes opening phase, thus it should be finished with e_cal_backend_notify_opened().

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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.

e_cal_backend_get_timezone ()

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

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

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.

e_cal_backend_start_view ()

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

Starts a new live view on the given backend.

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.

Since 3.2

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.

e_cal_backend_notify_objects_added ()

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

Since 2.24

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.

e_cal_backend_notify_objects_modified ()

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

Since 2.24

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.

e_cal_backend_notify_objects_removed ()

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

Since 2.24

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

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.

e_cal_backend_notify_online ()

void                e_cal_backend_notify_online         (ECalBackend *backend,
                                                         gboolean is_online);

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

Since 3.2

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.

e_cal_backend_notify_opened ()

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

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.

Since 3.2

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.

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.

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.

Since 3.2

e_cal_backend_respond_opened ()

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

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.

Since 3.2