## EDataCal EDataCal — Server side D-Bus layer to communicate with calendars |

## Synopsis

    #include <libedata-cal/libedata-cal.h>

    #define             E_DATA_CAL_ERROR
    struct              EDataCal;
    struct              EDataCalClass;
    enum                EDataCalCallStatus;
    GQuark              e_data_cal_error_quark              (void);
    GError *            e_data_cal_create_error             (EDataCalCallStatus status,
                                                             const gchar *custom_msg);
    GError *            e_data_cal_create_error_fmt         (EDataCalCallStatus status,
                                                             const gchar *custom_msg_fmt,
                                                             ...);
    const gchar *       e_data_cal_status_to_string         (EDataCalCallStatus status);
    EDataCal *          e_data_cal_new                      (struct _ECalBackend *backend,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);
    struct _ECalBackend * e_data_cal_ref_backend            (EDataCal *cal);
    GDBusConnection *   e_data_cal_get_connection           (EDataCal *cal);
    const gchar *       e_data_cal_get_object_path          (EDataCal *cal);
    void                e_data_cal_respond_open             (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_respond_refresh          (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_respond_get_object       (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *object);
    void                e_data_cal_respond_get_object_list  (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *objects);
    void                e_data_cal_respond_get_free_busy    (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_respond_create_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *uids,
                                                             GSList *new_components);
    void                e_data_cal_respond_modify_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             GSList *old_components,
                                                             GSList *new_components);
    void                e_data_cal_respond_remove_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *ids,
                                                             GSList *old_components,
                                                             GSList *new_components);
    void                e_data_cal_respond_receive_objects  (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_respond_send_objects     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *users,
                                                             const gchar *calobj);
    void                e_data_cal_respond_get_attachment_uris
                                                            (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *attachment_uris);
    void                e_data_cal_respond_discard_alarm    (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_respond_get_timezone     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *tzobject);
    void                e_data_cal_respond_add_timezone     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_cal_report_error             (EDataCal *cal,
                                                             const gchar *message);
    void                e_data_cal_report_free_busy_data    (EDataCal *cal,
                                                             const GSList *freebusy);
    void                e_data_cal_report_backend_property_changed
                                                            (EDataCal *cal,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);

## Description

This class communicates with ECalClients over the bus and accesses an ECalBackend to satisfy client requests.

## Details

### E_DATA_CAL_ERROR

    #define E_DATA_CAL_ERROR e_data_cal_error_quark ()

Since 2.30

### struct EDataCal

    struct EDataCal {
    	GObject parent;
    	EDataCalPrivate *priv;
    };

### struct EDataCalClass

    struct EDataCalClass {
    	GObjectClass parent_class;
    };

### enum EDataCalCallStatus

    typedef enum {
    	Success,
    	Busy,
    	RepositoryOffline,
    	PermissionDenied,
    	InvalidRange,
    	ObjectNotFound,
    	InvalidObject,
    	ObjectIdAlreadyExists,
    	AuthenticationFailed,
    	AuthenticationRequired,
    	UnsupportedField,
    	UnsupportedMethod,
    	UnsupportedAuthenticationMethod,
    	TLSNotAvailable,
    	NoSuchCal,
    	UnknownUser,
    	OfflineUnavailable,

    	/* These can be returned for successful searches, but
    		indicate the result set was truncated */
    	SearchSizeLimitExceeded,
    	SearchTimeLimitExceeded,

    	InvalidQuery,
    	QueryRefused,

    	CouldNotCancel,

    	OtherError,
    	InvalidServerVersion,
    	InvalidArg,
    	NotSupported,
    	NotOpened
    } EDataCalCallStatus;

FIXME Document me!

`Success` |
`Busy` |
`RepositoryOffline` |
`PermissionDenied` |
`InvalidRange` |
`ObjectNotFound` |
`InvalidObject` |
`ObjectIdAlreadyExists` |
`AuthenticationFailed` |
`AuthenticationRequired` |
`UnsupportedField` |
`UnsupportedMethod` |
`UnsupportedAuthenticationMethod` |
`TLSNotAvailable` |
`NoSuchCal` |
`UnknownUser` |
`OfflineUnavailable` |
`SearchSizeLimitExceeded` |
`SearchTimeLimitExceeded` |
`InvalidQuery` |
`QueryRefused` |
`CouldNotCancel` |
`OtherError` |
`InvalidServerVersion` |
`InvalidArg` |
`NotSupported` |
`NotOpened` |

Since 3.6

### e_data_cal_error_quark ()

    GQuark              e_data_cal_error_quark              (void);

### e_data_cal_create_error ()

    GError *            e_data_cal_create_error             (EDataCalCallStatus status,
                                                             const gchar *custom_msg);

`status` : | EDataCalStatus code
`custom_msg` : | Custom message to use for the error. When NULL, then uses a default message based on the `status` code.
Returns : | NULL, when the `status` is Success, or a newly allocated GError, which should be freed with `g_error_free()` call.

Since 2.32

### e_data_cal_create_error_fmt ()

    GError *            e_data_cal_create_error_fmt         (EDataCalCallStatus status,
                                                             const gchar *custom_msg_fmt,
                                                             ...);

Similar as `e_data_cal_create_error()`, only here, instead of custom_msg, is used a `printf()` format to create a custom_msg for the error.

Since 2.32

### e_data_cal_status_to_string ()

    const gchar *       e_data_cal_status_to_string         (EDataCalCallStatus status);

Since 2.32

### e_data_cal_new ()

    EDataCal *          e_data_cal_new                      (struct _ECalBackend *backend,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);

Creates a new EDataCal and exports the Calendar D-Bus interface on `connection` at `object_path`. The EDataCal handles incoming remote method invocations and forwards them to the `backend`. If the Calendar interface fails to export, the function sets `error` and returns `NULL`.

`backend` : | an ECalBackend
`connection` : | a GDBusConnection
`object_path` : | object path for the D-Bus interface
`error` : | return location for a GError, or `NULL`
Returns : | an EDataCal, or `NULL` on error

### e_data_cal_ref_backend ()

    struct _ECalBackend * e_data_cal_ref_backend            (EDataCal *cal);

Returns the ECalBackend to which incoming remote method invocations are being forwarded.

The returned ECalBackend is referenced for thread-safety and should be unreferenced with `g_object_unref()` when finished with it.

`cal` : | an EDataCal
Returns : | an ECalBackend

Since 3.10

### e_data_cal_get_connection ()

    GDBusConnection *   e_data_cal_get_connection           (EDataCal *cal);

Returns the GDBusConnection on which the Calendar D-Bus interface is exported.

`cal` : | an EDataCal
Returns : | the GDBusConnection

Since 3.8

### e_data_cal_get_object_path ()

    const gchar *       e_data_cal_get_object_path          (EDataCal *cal);

Returns the object path at which the Calendar D-Bus interface is exported.

`cal` : | an EDataCal
Returns : | the object path

Since 3.8

### e_data_cal_respond_open ()

    void                e_data_cal_respond_open             (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the open method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_respond_refresh ()

    void                e_data_cal_respond_refresh          (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the refresh method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_respond_get_object ()

    void                e_data_cal_respond_get_object       (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *object);

Notifies listeners of the completion of the get_object method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`object` : | The object retrieved as an iCalendar string.

Since 3.2

### e_data_cal_respond_get_object_list ()

    void                e_data_cal_respond_get_object_list  (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *objects);

Notifies listeners of the completion of the get_object_list method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`objects` : | List of retrieved objects.

Since 3.2

### e_data_cal_respond_get_free_busy ()

    void                e_data_cal_respond_get_free_busy    (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the get_free_busy method call. To pass actual free/busy objects to the client use `e_data_cal_report_free_busy_data()`.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_respond_create_objects ()

    void                e_data_cal_respond_create_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *uids,
                                                             GSList *new_components);

Notifies listeners of the completion of the create_objects method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`uids` : | UIDs of the objects created.
`new_components` : | The newly created ECalComponent objects.

Since 3.6

### e_data_cal_respond_modify_objects ()

    void                e_data_cal_respond_modify_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             GSList *old_components,
                                                             GSList *new_components);

Notifies listeners of the completion of the modify_objects method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`old_components` : | The old ECalComponents.
`new_components` : | The new ECalComponents.

Since 3.6

### e_data_cal_respond_remove_objects ()

    void                e_data_cal_respond_remove_objects   (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *ids,
                                                             GSList *old_components,
                                                             GSList *new_components);

Notifies listeners of the completion of the remove_objects method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`ids` : | IDs of the removed objects.
`old_components` : | The old ECalComponents.
`new_components` : | The new ECalComponents. They will not be NULL only when removing instances of recurring appointments.

Since 3.6

### e_data_cal_respond_receive_objects ()

    void                e_data_cal_respond_receive_objects  (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the receive_objects method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_respond_send_objects ()

    void                e_data_cal_respond_send_objects     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *users,
                                                             const gchar *calobj);

Notifies listeners of the completion of the send_objects method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`users` : | List of users.
`calobj` : | An iCalendar string representing the object sent.

Since 3.2

### e_data_cal_respond_get_attachment_uris ()

    void                e_data_cal_respond_get_attachment_uris
                                                            (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *attachment_uris);

Notifies listeners of the completion of the get_attachment_uris method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`attachment_uris` : | List of retrieved attachment uri's.

Since 3.2

### e_data_cal_respond_discard_alarm ()

    void                e_data_cal_respond_discard_alarm    (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the discard_alarm method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_respond_get_timezone ()

    void                e_data_cal_respond_get_timezone     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *tzobject);

Notifies listeners of the completion of the get_timezone method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.
`tzobject` : | The requested timezone as an iCalendar string.

Since 3.2

### e_data_cal_respond_add_timezone ()

    void                e_data_cal_respond_add_timezone     (EDataCal *cal,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the add_timezone method call.

`cal` : | A calendar client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_cal_report_error ()

    void                e_data_cal_report_error             (EDataCal *cal,
                                                             const gchar *message);

FIXME: Document me.

Since 3.2

### e_data_cal_report_free_busy_data ()

    void                e_data_cal_report_free_busy_data    (EDataCal *cal,
                                                             const GSList *freebusy);

FIXME: Document me.

Since 3.2

### e_data_cal_report_backend_property_changed ()

    void                e_data_cal_report_backend_property_changed
                                                            (EDataCal *cal,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);

Notifies client about certain property value change

Since 3.2