## ECal

ECal — Permits access to a calendar or list of tasks.

## Synopsis

                        ECal;
    #define             E_CAL_SET_MODE_STATUS_ENUM_TYPE
    #define             CAL_MODE_ENUM_TYPE
    enum                ECalSourceType;
    enum                ECalSetModeStatus;
    enum                ECalLoadState;
    char *              (*ECalAuthFunc)                     (ECal *ecal,
                                                             const char *prompt,
                                                             const char *key,
                                                             gpointer user_data);
    GType               e_cal_open_status_enum_get_type     (void);
    GType               e_cal_source_type_enum_get_type     (void);
    GType               e_cal_set_mode_status_enum_get_type (void);
    GType               cal_mode_enum_get_type              (void);
    ECal *              e_cal_new                           (ESource *source,
                                                             ECalSourceType type);
    ECal *              e_cal_new_from_uri                  (const gchar *uri,
                                                             ECalSourceType type);
    ECal *              e_cal_new_system_calendar           (void);
    ECal *              e_cal_new_system_tasks              (void);
    ECal *              e_cal_new_system_memos              (void);
    void                e_cal_set_auth_func                 (ECal *ecal,
                                                             ECalAuthFunc func,
                                                             gpointer data);
    gboolean            e_cal_open                          (ECal *ecal,
                                                             gboolean only_if_exists,
                                                             GError **error);
    void                e_cal_open_async                    (ECal *ecal,
                                                             gboolean only_if_exists);
    gboolean            e_cal_remove                        (ECal *ecal,
                                                             GError **error);
    GList *             e_cal_uri_list                      (ECal *ecal,
                                                             CalMode mode);
    ECalSourceType      e_cal_get_source_type               (ECal *ecal);
    ECalLoadState       e_cal_get_load_state                (ECal *ecal);
    ESource *           e_cal_get_source                    (ECal *ecal);
    const char *        e_cal_get_uri                       (ECal *ecal);
    gboolean            e_cal_is_read_only                  (ECal *ecal,
                                                             gboolean *read_only,
                                                             GError **error);
    gboolean            e_cal_get_cal_address               (ECal *ecal,
                                                             char **cal_address,
                                                             GError **error);
    gboolean            e_cal_get_alarm_email_address       (ECal *ecal,
                                                             char **alarm_address,
                                                             GError **error);
    gboolean            e_cal_get_ldap_attribute            (ECal *ecal,
                                                             char **ldap_attribute,
                                                             GError **error);
    gboolean            e_cal_get_one_alarm_only            (ECal *ecal);
    gboolean            e_cal_get_organizer_must_attend     (ECal *ecal);
    gboolean            e_cal_get_save_schedules            (ECal *ecal);
    gboolean            e_cal_get_static_capability         (ECal *ecal,
                                                             const char *cap);
    gboolean            e_cal_get_organizer_must_accept     (ECal *ecal);
    gboolean            e_cal_set_mode                      (ECal *ecal,
                                                             CalMode mode);
    gboolean            e_cal_get_default_object            (ECal *ecal,
                                                             icalcomponent **icalcomp,
                                                             GError **error);
    gboolean            e_cal_get_object                    (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             icalcomponent **icalcomp,
                                                             GError **error);
    gboolean            e_cal_get_objects_for_uid           (ECal *ecal,
                                                             const char *uid,
                                                             GList **objects,
                                                             GError **error);
    gboolean            e_cal_get_changes                   (ECal *ecal,
                                                             const char *change_id,
                                                             GList **changes,
                                                             GError **error);
    void                e_cal_free_change_list              (GList *list);
    gboolean            e_cal_get_object_list               (ECal *ecal,
                                                             const char *query,
                                                             GList **objects,
                                                             GError **error);
    gboolean            e_cal_get_object_list_as_comp       (ECal *ecal,
                                                             const char *query,
                                                             GList **objects,
                                                             GError **error);
    void                e_cal_free_object_list              (GList *objects);
    gboolean            e_cal_get_free_busy                 (ECal *ecal,
                                                             GList *users,
                                                             time_t start,
                                                             time_t end,
                                                             GList **freebusy,
                                                             GError **error);
    void                e_cal_generate_instances            (ECal *ecal,
                                                             time_t start,
                                                             time_t end,
                                                             ECalRecurInstanceFn cb,
                                                             gpointer cb_data);
    void                e_cal_generate_instances_for_object (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             time_t start,
                                                             time_t end,
                                                             ECalRecurInstanceFn cb,
                                                             gpointer cb_data);
    GSList *            e_cal_get_alarms_in_range           (ECal *ecal,
                                                             time_t start,
                                                             time_t end);
    void                e_cal_free_alarms                   (GSList *comp_alarms);
    gboolean            e_cal_get_alarms_for_object         (ECal *ecal,
                                                             const ECalComponentId *id,
                                                             time_t start,
                                                             time_t end,
                                                             ECalComponentAlarms **alarms);
    gboolean            e_cal_create_object                 (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             char **uid,
                                                             GError **error);
    gboolean            e_cal_modify_object                 (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             CalObjModType mod,
                                                             GError **error);
    gboolean            e_cal_remove_object                 (ECal *ecal,
                                                             const char *uid,
                                                             GError **error);
    gboolean            e_cal_remove_object_with_mod        (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             CalObjModType mod,
                                                             GError **error);
    gboolean            e_cal_discard_alarm                 (ECal *ecal,
                                                             ECalComponent *comp,
                                                             const char *auid,
                                                             GError **error);
    gboolean            e_cal_receive_objects               (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             GError **error);
    gboolean            e_cal_send_objects                  (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             GList **users,
                                                             icalcomponent **modified_icalcomp,
                                                             GError **error);
    gboolean            e_cal_get_timezone                  (ECal *ecal,
                                                             const char *tzid,
                                                             icaltimezone **zone,
                                                             GError **error);
    gboolean            e_cal_add_timezone                  (ECal *ecal,
                                                             icaltimezone *izone,
                                                             GError **error);
    gboolean            e_cal_set_default_timezone          (ECal *ecal,
                                                             icaltimezone *zone,
                                                             GError **error);
    gboolean            e_cal_get_query                     (ECal *ecal,
                                                             const char *sexp,
                                                             ECalView **query,
                                                             GError **error);
    icaltimezone *      e_cal_resolve_tzid_cb               (const char *tzid,
                                                             gpointer data);
    char*               e_cal_get_component_as_string       (ECal *ecal,
                                                             icalcomponent *icalcomp);
    const char *        e_cal_get_error_message             (ECalendarStatus status);
    gboolean            e_cal_open_default                  (ECal **ecal,
                                                             ECalSourceType type,
                                                             ECalAuthFunc func,
                                                             gpointer data,
                                                             GError **error);
    gboolean            e_cal_set_default                   (ECal *ecal,
                                                             GError **error);
    gboolean            e_cal_set_default_source            (ESource *source,
                                                             ECalSourceType type,
                                                             GError **error);
    gboolean            e_cal_get_sources                   (ESourceList **sources,
                                                             ECalSourceType type,
                                                             GError **error);
    const char *        e_cal_get_local_attachment_store    (ECal *ecal);
    gboolean            e_cal_get_recurrences_no_master     (ECal *ecal);
    gboolean            e_cal_get_attachments_for_comp      (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             GSList **list,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----ECal

## Signals

      "backend-died"                                   : Run First
      "backend-error"                                  : Run First
      "cal-opened"                                     : Run First
      "cal-set-mode"                                   : Run First

## Description

Represents an entire calendar or task list, not individual items within them.2

## Details

### ECal

    typedef struct _ECal ECal;

### E_CAL_SET_MODE_STATUS_ENUM_TYPE

    #define E_CAL_SET_MODE_STATUS_ENUM_TYPE (e_cal_set_mode_status_enum_get_type ())

### CAL_MODE_ENUM_TYPE

    #define CAL_MODE_ENUM_TYPE                   (cal_mode_enum_get_type ())

### enum ECalSourceType

    typedef enum {
    	E_CAL_SOURCE_TYPE_EVENT,
    	E_CAL_SOURCE_TYPE_TODO,
    	E_CAL_SOURCE_TYPE_JOURNAL,
    	E_CAL_SOURCE_TYPE_LAST
    } ECalSourceType;

### enum ECalSetModeStatus

    typedef enum {
    	E_CAL_SET_MODE_SUCCESS,
    	E_CAL_SET_MODE_ERROR,
    	E_CAL_SET_MODE_NOT_SUPPORTED
    } ECalSetModeStatus;

### enum ECalLoadState

    typedef enum {
    	E_CAL_LOAD_NOT_LOADED,
    	E_CAL_LOAD_AUTHENTICATING,
    	E_CAL_LOAD_LOADING,
    	E_CAL_LOAD_LOADED
    } ECalLoadState;

### ECalAuthFunc ()

    char *              (*ECalAuthFunc)                     (ECal *ecal,
                                                             const char *prompt,
                                                             const char *key,
                                                             gpointer user_data);

`ecal` : |
`prompt` : |
`key` : |
`user_data` : |
Returns : |

### e_cal_open_status_enum_get_type ()

    GType               e_cal_open_status_enum_get_type     (void);

Returns : |

### e_cal_source_type_enum_get_type ()

    GType               e_cal_source_type_enum_get_type     (void);

Registers the ECalSourceTypeEnum type with glib.

Returns : | the ID of the ECalSourceTypeEnum type.

### e_cal_set_mode_status_enum_get_type ()

    GType               e_cal_set_mode_status_enum_get_type (void);

Registers the ECalSetModeStatusEnum type with glib.

Returns : | the ID of the ECalSetModeStatusEnum type.

### cal_mode_enum_get_type ()

    GType               cal_mode_enum_get_type              (void);

Registers the CalModeEnum type with glib.

Returns : | the ID of the CalModeEnum type.

### e_cal_new ()

    ECal *              e_cal_new                           (ESource *source,
                                                             ECalSourceType type);

Creates a new calendar client. This does not open the calendar itself, for that, e_cal_open or e_cal_open_async needs to be called.

`source` : | An ESource to be used for the client.
`type` : | Type of the client.
Returns : | A newly-created calendar client, or NULL if the client could not be constructed because it could not contact the calendar server.

### e_cal_new_from_uri ()

    ECal *              e_cal_new_from_uri                  (const gchar *uri,
                                                             ECalSourceType type);

Creates a new calendar client. This does not open the calendar itself, for that, e_cal_open or e_cal_open_async needs to be called.

`uri` : | The URI pointing to the calendar to open.
`type` : | Type of the client.
Returns : | A newly-created calendar client, or NULL if the client could not be constructed because it could not contact the calendar server.

### e_cal_new_system_calendar ()

    ECal *              e_cal_new_system_calendar           (void);

Create a calendar client for the system calendar, which should always be present in all Evolution installations. This does not open the calendar itself, for that, e_cal_open or e_cal_open_async needs to be called.

Returns : | A newly-created calendar client, or NULL if the client could not be constructed.

### e_cal_new_system_tasks ()

    ECal *              e_cal_new_system_tasks              (void);

Create a calendar client for the system task list, which should always be present in all Evolution installations. This does not open the tasks list itself, for that, e_cal_open or e_cal_open_async needs to be called.

Returns : | A newly-created calendar client, or NULL if the client could not be constructed.

### e_cal_new_system_memos ()

    ECal *              e_cal_new_system_memos              (void);

Create a calendar client for the system memos, which should always be present in all Evolution installations. This does not open the memos itself, for that, e_cal_open or e_cal_open_async needs to be called.

Returns : | A newly-created calendar client, or NULL if the client could not be constructed.

### e_cal_set_auth_func ()

    void                e_cal_set_auth_func                 (ECal *ecal,
                                                             ECalAuthFunc func,
                                                             gpointer data);

Sets the given authentication function on the calendar client. This function will be called any time the calendar server needs a password for an operation associated with the calendar and should be supplied before any calendar is opened.

When a calendar is opened asynchronously, the open function is processed in a concurrent thread. This means that the authentication function will also be called from this thread. As such, the authentication callback cannot directly call any functions that must be called from the main thread. For example any Gtk+ related functions, which must be proxied synchronously to the main thread by the callback.

The authentication function has the following signature (ECalAuthFunc): char * auth_func (ECal *ecal, const gchar *prompt, const gchar *key, gpointer user_data)

`ecal` : | A calendar client.
`func` : | The authentication function
`data` : | User data to be used when calling the authentication function

### e_cal_open ()

    gboolean            e_cal_open                          (ECal *ecal,
                                                             gboolean only_if_exists,
                                                             GError **error);

Makes a calendar client initiate a request to open a calendar. The calendar client will emit the "cal_opened" signal when the response from the server is received.

`ecal` : | A calendar client.
`only_if_exists` : | FALSE if the calendar should be opened even if there was no storage for it, i.e. to create a new calendar or load an existing one if it already exists. TRUE if it should only try to load calendars that already exist.
`error` : | Placeholder for error information.
Returns : | TRUE on success, FALSE on failure to issue the open request.

### e_cal_open_async ()

    void                e_cal_open_async                    (ECal *ecal,
                                                             gboolean only_if_exists);

Open the calendar asynchronously. The calendar will emit the "cal_opened" signal when the operation has completed.

Because this operation runs in another thread, any authentication callback set on the calendar will be called from this other thread. See #`e_cal_set_auth_func()` for details.

`ecal` : | A calendar client.
`only_if_exists` : | If TRUE, then only open the calendar if it already exists. If FALSE, then create a new calendar if it doesn't already exist.

### e_cal_remove ()

    gboolean            e_cal_remove                        (ECal *ecal,
                                                             GError **error);

Removes a calendar.

`ecal` : | A calendar client.
`error` : | Placeholder for error information.
Returns : | TRUE if the calendar was removed, FALSE if there was an error.

### e_cal_uri_list ()

    GList *             e_cal_uri_list                      (ECal *ecal,
                                                             CalMode mode);

Retrieves a list of all calendar clients for the given mode.

`ecal` : | A calendar client.
`mode` : | Mode of the URIs to get.
Returns : | list of uris.

### e_cal_get_source_type ()

    ECalSourceType      e_cal_get_source_type               (ECal *ecal);

Gets the type of the calendar client.

`ecal` : | A calendar client.
Returns : | an ECalSourceType value corresponding to the type of the calendar client.

### e_cal_get_load_state ()

    ECalLoadState       e_cal_get_load_state                (ECal *ecal);

Queries the state of loading of a calendar client.

`ecal` : | A calendar client.
Returns : | A ECalLoadState value indicating whether the client has not been loaded with e_cal_open yet, whether it is being loaded, or whether it is already loaded.

### e_cal_get_source ()

    ESource *           e_cal_get_source                    (ECal *ecal);

Queries the source that is open in a calendar client.

`ecal` : | A calendar client.
Returns : | The source of the calendar that is already loaded or is being loaded, or NULL if the ecal has not started a load request yet.

### e_cal_get_uri ()

    const char *        e_cal_get_uri                       (ECal *ecal);

Queries the URI that is open in a calendar client.

`ecal` : | A calendar client.
Returns : | The URI of the calendar that is already loaded or is being loaded, or NULL if the client has not started a load request yet.

### e_cal_is_read_only ()

    gboolean            e_cal_is_read_only                  (ECal *ecal,
                                                             gboolean *read_only,
                                                             GError **error);

Queries whether the calendar client can perform modifications on the calendar or not. Whether the backend is read only or not is specified, on exit, in the `read_only` argument.

`ecal` : | A calendar client.
`read_only` : | Return value for read only status.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE if there was an error.

### e_cal_get_cal_address ()

    gboolean            e_cal_get_cal_address               (ECal *ecal,
                                                             char **cal_address,
                                                             GError **error);

Queries the calendar address associated with a calendar client.

`ecal` : | A calendar client.
`cal_address` : | Return value for address information.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE if there was an error.

### e_cal_get_alarm_email_address ()

    gboolean            e_cal_get_alarm_email_address       (ECal *ecal,
                                                             char **alarm_address,
                                                             GError **error);

Queries the address to be used for alarms in a calendar client.

`ecal` : | A calendar client.
`alarm_address` : | Return value for alarm address.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE if there was an error while contacting the backend.

### e_cal_get_ldap_attribute ()

    gboolean            e_cal_get_ldap_attribute            (ECal *ecal,
                                                             char **ldap_attribute,
                                                             GError **error);

Queries the LDAP attribute for a calendar client.

`ecal` : | A calendar client.
`ldap_attribute` : | Return value for the LDAP attribute.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE if there was an error contacting the backend.

### e_cal_get_one_alarm_only ()

    gboolean            e_cal_get_one_alarm_only            (ECal *ecal);

Checks if a calendar supports only one alarm per component.

`ecal` : | A calendar client.
Returns : | TRUE if the calendar allows only one alarm, FALSE otherwise.

### e_cal_get_organizer_must_attend ()

    gboolean            e_cal_get_organizer_must_attend     (ECal *ecal);

Checks if a calendar forces organizers of meetings to be also attendees.

`ecal` : | A calendar client.
Returns : | TRUE if the calendar forces organizers to attend meetings, FALSE otherwise.

### e_cal_get_save_schedules ()

    gboolean            e_cal_get_save_schedules            (ECal *ecal);

Checks whether the calendar saves schedules.

`ecal` : | A calendar client.
Returns : | TRUE if it saves schedules, FALSE otherwise.

### e_cal_get_static_capability ()

    gboolean            e_cal_get_static_capability         (ECal *ecal,
                                                             const char *cap);

Queries the calendar for static capabilities.

`ecal` : | A calendar client.
`cap` : | Name of the static capability to check.
Returns : | TRUE if the capability is supported, FALSE otherwise.

### e_cal_get_organizer_must_accept ()

    gboolean            e_cal_get_organizer_must_accept     (ECal *ecal);

Checks whether a calendar requires organizer to accept their attendance to meetings.

`ecal` : | A calendar client.
Returns : | TRUE if the calendar requires organizers to accept, FALSE otherwise.

### e_cal_set_mode ()

    gboolean            e_cal_set_mode                      (ECal *ecal,
                                                             CalMode mode);

Switches online/offline mode on the calendar.

`ecal` : | A calendar client.
`mode` : | Mode to switch to.
Returns : | TRUE if the switch was successful, FALSE if there was an error.

### e_cal_get_default_object ()

    gboolean            e_cal_get_default_object            (ECal *ecal,
                                                             icalcomponent **icalcomp,
                                                             GError **error);

Retrives an icalcomponent from the backend that contains the default values for properties needed.

`ecal` : | A calendar client.
`icalcomp` : | Return value for the default object.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE otherwise.

### e_cal_get_object ()

    gboolean            e_cal_get_object                    (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             icalcomponent **icalcomp,
                                                             GError **error);

Queries a calendar for a calendar component object based on its unique identifier.

`ecal` : | A calendar client.
`uid` : | Unique identifier for a calendar component.
`rid` : | Recurrence identifier.
`icalcomp` : | Return value for the calendar component object.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE otherwise.

### e_cal_get_objects_for_uid ()

    gboolean            e_cal_get_objects_for_uid           (ECal *ecal,
                                                             const char *uid,
                                                             GList **objects,
                                                             GError **error);

Queries a calendar for all calendar components with the given unique ID. This will return any recurring event and all its detached recurrences. For non-recurring events, it will just return the object with that ID.

`ecal` : | A calendar client.
`uid` : | Unique identifier for a calendar component.
`objects` : | Return value for the list of objects obtained from the backend.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE otherwise.

### e_cal_get_changes ()

    gboolean            e_cal_get_changes                   (ECal *ecal,
                                                             const char *change_id,
                                                             GList **changes,
                                                             GError **error);

Returns a list of changes made to the calendar since a specific time. That time is identified by the `change_id` argument, which is used by the backend to compute the changes done.

`ecal` : | A calendar client.
`change_id` : | ID to use for comparing changes.
`changes` : | Return value for the list of changes.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE otherwise.

### e_cal_free_change_list ()

    void                e_cal_free_change_list              (GList *list);

Free a list of changes as returned by e_cal_get_changes.

`list` : | List of changes to be freed.

### e_cal_get_object_list ()

    gboolean            e_cal_get_object_list               (ECal *ecal,
                                                             const char *query,
                                                             GList **objects,
                                                             GError **error);

Gets a list of objects from the calendar that match the query specified by the `query` argument. The objects will be returned in the `objects` argument, which is a list of icalcomponent. When done, this list should be freed by using the e_cal_free_object_list function.

`ecal` : | A calendar client.
`query` : | Query string.
`objects` : | Return value for list of objects.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_get_object_list_as_comp ()

    gboolean            e_cal_get_object_list_as_comp       (ECal *ecal,
                                                             const char *query,
                                                             GList **objects,
                                                             GError **error);

Gets a list of objects from the calendar that match the query specified by the `query` argument. The objects will be returned in the `objects` argument, which is a list of ECalComponent.

`ecal` : | A calendar client.
`query` : | Query string.
`objects` : | Return value for list of objects.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_free_object_list ()

    void                e_cal_free_object_list              (GList *objects);

Frees a list of objects as returned by e_cal_get_object_list.

`objects` : | List of objects to be freed.

### e_cal_get_free_busy ()

    gboolean            e_cal_get_free_busy                 (ECal *ecal,
                                                             GList *users,
                                                             time_t start,
                                                             time_t end,
                                                             GList **freebusy,
                                                             GError **error);

Gets free/busy information from the calendar server.

`ecal` : | A calendar client.
`users` : | List of users to retrieve free/busy information for.
`start` : | Start time for query.
`end` : | End time for query.
`freebusy` : | Return value for VFREEBUSY objects.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_generate_instances ()

    void                e_cal_generate_instances            (ECal *ecal,
                                                             time_t start,
                                                             time_t end,
                                                             ECalRecurInstanceFn cb,
                                                             gpointer cb_data);

Does a combination of #`e_cal_get_object_list()` and #`e_cal_recur_generate_instances()`.

The callback function should do a `g_object_ref()` of the calendar component it gets passed if it intends to keep it around, since it will be unref'ed as soon as the callback returns.

`ecal` : | A calendar client.
`start` : | Start time for query.
`end` : | End time for query.
`cb` : | Callback for each generated instance.
`cb_data` : | Closure data for the callback.

### e_cal_generate_instances_for_object ()

    void                e_cal_generate_instances_for_object (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             time_t start,
                                                             time_t end,
                                                             ECalRecurInstanceFn cb,
                                                             gpointer cb_data);

Does a combination of #`e_cal_get_object_list()` and #`e_cal_recur_generate_instances()`, like #`e_cal_generate_instances()`, but for a single object.

The callback function should do a `g_object_ref()` of the calendar component it gets passed if it intends to keep it around, since it will be unref'ed as soon as the callback returns.

`ecal` : | A calendar client.
`icalcomp` : | Object to generate instances from.
`start` : | Start time for query.
`end` : | End time for query.
`cb` : | Callback for each generated instance.
`cb_data` : | Closure data for the callback.

### e_cal_get_alarms_in_range ()

    GSList *            e_cal_get_alarms_in_range           (ECal *ecal,
                                                             time_t start,
                                                             time_t end);

Queries a calendar for the alarms that trigger in the specified range of time.

`ecal` : | A calendar client.
`start` : | Start time for query.
`end` : | End time for query.
Returns : | A list of ECalComponentAlarms structures. This should be freed using the #`e_cal_free_alarms()` function, or by freeing each element separately with #`e_cal_component_alarms_free()` and then freeing the list with #`g_slist_free()`.

### e_cal_free_alarms ()

    void                e_cal_free_alarms                   (GSList *comp_alarms);

Frees a list of ECalComponentAlarms structures as returned by `e_cal_get_alarms_in_range()`.

`comp_alarms` : | A list of ECalComponentAlarms structures.

### e_cal_get_alarms_for_object ()

    gboolean            e_cal_get_alarms_for_object         (ECal *ecal,
                                                             const ECalComponentId *id,
                                                             time_t start,
                                                             time_t end,
                                                             ECalComponentAlarms **alarms);

Queries a calendar for the alarms of a particular object that trigger in the specified range of time.

`ecal` : | A calendar client.
`id` : | Unique identifier for a calendar component.
`start` : | Start time for query.
`end` : | End time for query.
`alarms` : | Return value for the component's alarm instances. Will return NULL if no instances occur within the specified time range. This should be freed using the `e_cal_component_alarms_free()` function.
Returns : | TRUE on success, FALSE if the object was not found.

### e_cal_create_object ()

    gboolean            e_cal_create_object                 (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             char **uid,
                                                             GError **error);

Requests the calendar backend to create the object specified by the `icalcomp` argument. Some backends would assign a specific UID to the newly created object, in those cases that UID would be returned in the `uid` argument.

`ecal` : | A calendar client.
`icalcomp` : | The component to create.
`uid` : | Return value for the UID assigned to the new component by the calendar backend.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_modify_object ()

    gboolean            e_cal_modify_object                 (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             CalObjModType mod,
                                                             GError **error);

Requests the calendar backend to modify an existing object. If the object does not exist on the calendar, an error will be returned.

For recurrent appointments, the `mod` argument specifies what to modify, if all instances (CALOBJ_MOD_ALL), a single instance (CALOBJ_MOD_THIS), or a specific set of instances (CALOBJ_MOD_THISNADPRIOR and CALOBJ_MOD_THISANDFUTURE).

`ecal` : | A calendar client.
`icalcomp` : | Component to modify.
`mod` : | Type of modification.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_remove_object ()

    gboolean            e_cal_remove_object                 (ECal *ecal,
                                                             const char *uid,
                                                             GError **error);

Asks a calendar to remove a component. If the server is able to remove the component, all clients will be notified and they will emit the "obj_removed" signal.

`ecal` : | A calendar client.
`uid` : | Unique identifier of the calendar component to remove.
`error` : | Placeholder for error information.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_cal_remove_object_with_mod ()

    gboolean            e_cal_remove_object_with_mod        (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             CalObjModType mod,
                                                             GError **error);

This function allows the removal of instances of a recurrent appointment. By using a combination of the `uid`, `rid` and `mod` arguments, you can remove specific instances. If what you want is to remove all instances, use e_cal_remove_object instead.

If not all instances are removed, the client will get a "obj_modified" signal, while it will get a "obj_removed" signal when all instances are removed.

`ecal` : | A calendar client.
`uid` : | UID og the object to remove.
`rid` : | Recurrence ID of the specific recurrence to remove.
`mod` : | Type of removal.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_discard_alarm ()

    gboolean            e_cal_discard_alarm                 (ECal *ecal,
                                                             ECalComponent *comp,
                                                             const char *auid,
                                                             GError **error);

Tells the calendar backend to get rid of the alarm identified by the `auid` argument in `comp`. Some backends might remove the alarm or update internal information about the alarm be discarded, or, like the file backend does, ignore the operation.

`ecal` : | A calendar ecal.
`comp` : | The component to discard the alarm from.
`auid` : | Unique identifier of the alarm to be discarded.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_receive_objects ()

    gboolean            e_cal_receive_objects               (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             GError **error);

Makes the backend receive the set of iCalendar objects specified in the `icalcomp` argument. This is used for iTIP confirmation/cancellation messages for scheduled meetings.

`ecal` : | A calendar client.
`icalcomp` : | An icalcomponent.
`error` : | Placeholder for error information.
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_cal_send_objects ()

    gboolean            e_cal_send_objects                  (ECal *ecal,
                                                             icalcomponent *icalcomp,
                                                             GList **users,
                                                             icalcomponent **modified_icalcomp,
                                                             GError **error);

Requests a calendar backend to send meeting information to the specified list of users.

`ecal` : | A calendar client.
`icalcomp` : | An icalcomponent.
`users` : | List of users to send the objects to.
`modified_icalcomp` : | Return value for the icalcomponent after all the operations performed.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_get_timezone ()

    gboolean            e_cal_get_timezone                  (ECal *ecal,
                                                             const char *tzid,
                                                             icaltimezone **zone,
                                                             GError **error);

Retrieves a timezone object from the calendar backend.

`ecal` : | A calendar client.
`tzid` : | ID of the timezone to retrieve.
`zone` : | Return value for the timezone.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_add_timezone ()

    gboolean            e_cal_add_timezone                  (ECal *ecal,
                                                             icaltimezone *izone,
                                                             GError **error);

Add a VTIMEZONE object to the given calendar.

`ecal` : | A calendar client.
`izone` : | The timezone to add.
`error` : | Placeholder for error information.
Returns : | TRUE if successful, FALSE otherwise.

### e_cal_set_default_timezone ()

    gboolean            e_cal_set_default_timezone          (ECal *ecal,
                                                             icaltimezone *zone,
                                                             GError **error);

Sets the default timezone on the calendar. This should be called before opening the calendar.

`ecal` : | A calendar client.
`zone` : | A timezone object.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_get_query ()

    gboolean            e_cal_get_query                     (ECal *ecal,
                                                             const char *sexp,
                                                             ECalView **query,
                                                             GError **error);

Creates a live query object from a loaded calendar.

`ecal` : | A calendar client.
`sexp` : | S-expression representing the query.
`query` : | Return value for the new query.
`error` : | Placeholder for error information.
Returns : | A query object that will emit notification signals as calendar components are added and removed from the query in the server.

### e_cal_resolve_tzid_cb ()

    icaltimezone *      e_cal_resolve_tzid_cb               (const char *tzid,
                                                             gpointer data);

Resolves TZIDs for the recurrence generator.

`tzid` : | ID of the timezone to resolve.
`data` : | Closure data for the callback.
Returns : | The timezone identified by the `tzid` argument, or `NULL` if it could not be found.

### e_cal_get_component_as_string ()

    char*               e_cal_get_component_as_string       (ECal *ecal,
                                                             icalcomponent *icalcomp);

Gets a calendar component as an iCalendar string, with a toplevel VCALENDAR component and all VTIMEZONEs needed for the component.

`ecal` : | A calendar client.
`icalcomp` : | A calendar component object.
Returns : | the component as a complete iCalendar string, or NULL on failure. The string should be freed after use.

### e_cal_get_error_message ()

    const char *        e_cal_get_error_message             (ECalendarStatus status);

Gets an error message for the given status code.

`status` : | A status code.
Returns : | the error message.

### e_cal_open_default ()

    gboolean            e_cal_open_default                  (ECal **ecal,
                                                             ECalSourceType type,
                                                             ECalAuthFunc func,
                                                             gpointer data,
                                                             GError **error);

Opens the default calendar.

`ecal` : | A calendar client.
`type` : | Type of the calendar.
`func` : | Authentication function.
`data` : | Closure data for the authentication function.
`error` : | Placeholder for error information.
Returns : | TRUE if it opened correctly, FALSE otherwise.

### e_cal_set_default ()

    gboolean            e_cal_set_default                   (ECal *ecal,
                                                             GError **error);

Sets a calendar as the default one.

`ecal` : | A calendar client.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_set_default_source ()

    gboolean            e_cal_set_default_source            (ESource *source,
                                                             ECalSourceType type,
                                                             GError **error);

Sets the default source for the specified `type`.

`source` : | An ESource.
`type` : | Type of the source.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_get_sources ()

    gboolean            e_cal_get_sources                   (ESourceList **sources,
                                                             ECalSourceType type,
                                                             GError **error);

Gets the list of sources defined in the configuration for the given `type`.

`sources` : | Return value for list of sources.
`type` : | Type of the sources to get.
`error` : | Placeholder for error information.
Returns : | TRUE if the operation was successful, FALSE otherwise.

### e_cal_get_local_attachment_store ()

    const char *        e_cal_get_local_attachment_store    (ECal *ecal);

Queries the URL where the calendar attachments are serialized in the local filesystem. This enable clients to operate with the reference to attachments rather than the data itself unless it specifically uses the attachments for open/sending operations.

`ecal` : | A calendar client.
Returns : | The URL where the attachments are serialized in the local filesystem.

### e_cal_get_recurrences_no_master ()

    gboolean            e_cal_get_recurrences_no_master     (ECal *ecal);

Checks if the calendar has a master object for recurrences.

`ecal` : | A calendar client.
Returns : | TRUE if the calendar has a master object for recurrences, FALSE otherwise.

### e_cal_get_attachments_for_comp ()

    gboolean            e_cal_get_attachments_for_comp      (ECal *ecal,
                                                             const char *uid,
                                                             const char *rid,
                                                             GSList **list,
                                                             GError **error);

Queries a calendar for a calendar component object based on its unique identifier and gets the attachments for the component.

`ecal` : | A calendar client.
`uid` : | Unique identifier for a calendar component.
`rid` : | Recurrence identifier.
`list` : | Return the list of attachment uris.
`error` : | Placeholder for error information.
Returns : | TRUE if the call was successful, FALSE otherwise.

## Signal Details

### The `"backend-died"` signal

    void                user_function                      (ECal    *ecal,
                                                            gpointer user_data)      : Run First

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

### The `"backend-error"` signal

    void                user_function                      (ECal    *ecal,
                                                            gchar   *arg1,
                                                            gpointer user_data)      : Run First

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

### The `"cal-opened"` signal

    void                user_function                      (ECal    *ecal,
                                                            gint     arg1,
                                                            gpointer user_data)      : Run First

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

### The `"cal-set-mode"` signal

    void                user_function                      (ECal                 *ecal,
                                                            ECalSetModeStatusEnum arg1,
                                                            CalModeEnum           arg2,
                                                            gpointer              user_data)      : Run First

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

## See Also

e-cal-listener, e-cal-view