## ECal

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

## Synopsis

    struct      ECal;
    #define     E_CAL_SET_MODE_STATUS_ENUM_TYPE
    #define     CAL_MODE_ENUM_TYPE
    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_set_mode_status_enum_get_type
                                                (void);
    GType       cal_mode_enum_get_type          (void);
    ECal*       e_cal_new                       (ESource *source,
                                                 ECalSourceType type);
    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);
    GList*      e_cal_uri_list                  (ECal *ecal,
                                                 CalMode mode);
    ECalLoadState e_cal_get_load_state          (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_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_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);
    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 char *uid,
                                                 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);

## Object Hierarchy

      GObject
       +----ECal

## Signal Prototypes

    "backend-died"
                void        user_function      (ECal *ecal,
                                                gpointer user_data);
    "backend-error"
                void        user_function      (ECal *ecal,
                                                gchar *arg1,
                                                gpointer user_data);
    "cal-opened"
                void        user_function      (ECal *ecal,
                                                gint arg1,
                                                gpointer user_data);
    "cal-set-mode"
                void        user_function      (ECal *ecal,
                                                ECalSetModeStatusEnum arg1,
                                                CalModeEnum arg2,
                                                gpointer user_data);
    "categories-changed"
                void        user_function      (ECal *ecal,
                                                gpointer arg1,
                                                gpointer user_data);

## Description

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

## Details

### struct ECal

    struct 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 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_set_mode_status_enum_get_type ()

    GType       e_cal_set_mode_status_enum_get_type
                                                (void);

Returns : |

### cal_mode_enum_get_type ()

    GType       cal_mode_enum_get_type          (void);

Returns : |

### e_cal_new ()

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

Creates a new calendar ecal. It should be initialized by calling `e_cal_open()`.

`source` : |
`type` : |
Returns : | A newly-created calendar ecal, or NULL if the ecal could not be constructed because it could not contact the calendar server.

### e_cal_set_auth_func ()

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

Associates the given authentication function with a calendar ecal. This function will be called any time the calendar server needs a password from the ecal. So, calendar ecals should provide such authentication function, which, when called, should act accordingly (by showing a dialog box, for example, to ask the user for the password).

The authentication function must have the following form: char * auth_func (ECal *ecal, const gchar *prompt, const gchar *key, gpointer user_data)

`ecal` : | A calendar ecal.
`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 ecal initiate a request to open a calendar. The calendar ecal will emit the "cal_opened" signal when the response from the server is received.

`ecal` : | A calendar ecal.
`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` : |
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);

`ecal` : |
`only_if_exists` : |

### e_cal_uri_list ()

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

`ecal` : |
`mode` : |
Returns : |

### e_cal_get_load_state ()

    ECalLoadState e_cal_get_load_state          (ECal *ecal);

Queries the state of loading of a calendar ecal.

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

### e_cal_get_uri ()

    const char* e_cal_get_uri                   (ECal *ecal);

Queries the URI that is open in a calendar ecal.

`ecal` : | A calendar ecal.
Returns : | The URI 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_is_read_only ()

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

Queries whether the calendar ecal 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 ecal.
`read_only` : |
`error` : |
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 ecal.

`ecal` : | A calendar ecal.
`cal_address` : |
`error` : |
Returns : | The calendar address associated with the calendar that is loaded or being loaded, or `NULL` if the ecal has not started a load request yet or the calendar has no associated email address.

### e_cal_get_alarm_email_address ()

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

`ecal` : |
`alarm_address` : |
`error` : |
Returns : |

### e_cal_get_ldap_attribute ()

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

`ecal` : |
`ldap_attribute` : |
`error` : |
Returns : |

### e_cal_get_one_alarm_only ()

    gboolean    e_cal_get_one_alarm_only        (ECal *ecal);

`ecal` : |
Returns : |

### e_cal_get_organizer_must_attend ()

    gboolean    e_cal_get_organizer_must_attend (ECal *ecal);

`ecal` : |
Returns : |

### e_cal_get_save_schedules ()

    gboolean    e_cal_get_save_schedules        (ECal *ecal);

`ecal` : |
Returns : |

### e_cal_get_static_capability ()

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

`ecal` : |
`cap` : |
Returns : |

### e_cal_set_mode ()

    gboolean    e_cal_set_mode                  (ECal *ecal,
                                                 CalMode mode);

`ecal` : |
`mode` : |
Returns : |

### e_cal_get_default_object ()

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

`ecal` : |
`icalcomp` : |
`error` : |
Returns : |

### 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 ecal.
`uid` : | Unique identifier for a calendar component.
`rid` : |
`icalcomp` : | Return value for the calendar component object.
`error` : |
Returns : | Result code based on the status of the operation.

### e_cal_get_changes ()

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

`ecal` : |
`change_id` : |
`changes` : |
`error` : |
Returns : |

### e_cal_free_change_list ()

    void        e_cal_free_change_list          (GList *list);

`list` : |

### e_cal_get_object_list ()

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

`ecal` : |
`query` : |
`objects` : |
`error` : |
Returns : |

### e_cal_get_object_list_as_comp ()

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

`ecal` : |
`query` : |
`objects` : |
`error` : |
Returns : |

### e_cal_free_object_list ()

    void        e_cal_free_object_list          (GList *objects);

`objects` : |

### 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 ecal.
`users` : | List of users to retrieve free/busy information for.
`start` : | Start time for query.
`end` : | End time for query.
`freebusy` : |
`error` : |
Returns : | a GList of VFREEBUSY ECalComponents

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

`ecal` : | A calendar ecal.
`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 ecal.
`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 char *uid,
                                                 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 ecal.
`uid` : | 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);

`ecal` : |
`icalcomp` : |
`uid` : |
`error` : |
Returns : |

### e_cal_modify_object ()

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

`ecal` : |
`icalcomp` : |
`mod` : |
`error` : |
Returns : |

### 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 ecals will be notified and they will emit the "obj_removed" signal.

`ecal` : | A calendar ecal.
`uid` : | Unique identifier of the calendar component to remove.
`error` : |
Returns : | an ECalResult value indicating the result of the operation.

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

`ecal` : |
`uid` : |
`rid` : |
`mod` : |
`error` : |
Returns : |

### 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` : |
Returns : | a ECalResult value indicating the result of the operation.

### e_cal_receive_objects ()

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

`ecal` : |
`icalcomp` : |
`error` : |
Returns : |

### e_cal_send_objects ()

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

`ecal` : |
`icalcomp` : |
`users` : |
`modified_icalcomp` : |
`error` : |
Returns : |

### e_cal_get_timezone ()

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

`ecal` : |
`tzid` : |
`zone` : |
`error` : |
Returns : |

### 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 ecal.
`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);

`ecal` : |
`zone` : |
`error` : |
Returns : |

### 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 ecal.
`sexp` : | S-expression representing the query.
`query` : |
`error` : |
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);

`tzid` : |
`data` : |
Returns : |

### 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 ecal.
`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);

Get an error message for the given status code.

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

## Signals

### The "backend-died" signal

    void        user_function                  (ECal *ecal,
                                                gpointer user_data);

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

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

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

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

### The "categories-changed" signal

    void        user_function                  (ECal *ecal,
                                                gpointer arg1,
                                                gpointer user_data);

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

## See Also

e-cal-listener, e-cal-view