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

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

Sets the given authentication function on the calendar ecal. 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 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);

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.
`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_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` : | Recurrence identifier.
`icalcomp` : | Return value for the calendar component object.
`error` : | Placeholder for error information.
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` : | Error placeholder.
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);

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

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 ecal.
`icalcomp` : | An icalcomponent.
`error` : | Error placeholder.
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);

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

## See Also

e-cal-listener, e-cal-view