struct ECal

struct ECal;

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;

enum EDataCalMode

typedef enum {
	Local = 1 << 0,
	Remote = 1 << 1,
	AnyMode = 0x07
} EDataCalMode;

FIXME: Document me.

Since 3.2

ECalAuthFunc ()

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

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.

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.

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 use e_cal_open() or e_cal_open_async().

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 task list itself -- for that use e_cal_open() or e_cal_open_async().

e_cal_new_system_memos ()

ECal *              e_cal_new_system_memos              (void);

Create a calendar client for the system memo list, which should always be present in all Evolution installations. This does not open the memo list itself -- for that use e_cal_open() or e_cal_open_async().

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): gchar * auth_func (ECal *ecal, const gchar *prompt, const gchar *key, gpointer user_data)

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. Since 3.0 is emitted also "cal_opened_ex" signal, which contains a GError pointer from the open operation (NULL when no error occurred). New signal deprecates the old "cal_opened" signal.

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. Since 3.0 is emitted also "cal_opened_ex" signal, which contains a GError pointer from the open operation (NULL when no error occurred). New signal deprecates the old "cal_opened" signal.

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.

e_cal_refresh ()

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

Invokes refresh on a calendar. See e_cal_get_refresh_supported.

Since 2.30

e_cal_remove ()

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

Removes a calendar.

e_cal_uri_list ()

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

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

e_cal_get_source_type ()

ECalSourceType      e_cal_get_source_type               (ECal *ecal);

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

e_cal_get_source ()

ESource *           e_cal_get_source                    (ECal *ecal);

Queries the source that is open in a calendar client.

e_cal_get_uri ()

const gchar *       e_cal_get_uri                       (ECal *ecal);

Queries the URI that is open in a calendar client.

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.

e_cal_get_cal_address ()

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

Queries the calendar address associated with a calendar client.

e_cal_get_alarm_email_address ()

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

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

e_cal_get_ldap_attribute ()

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

Queries the LDAP attribute for a calendar client.

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.

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.

e_cal_get_save_schedules ()

gboolean            e_cal_get_save_schedules            (ECal *ecal);

Checks whether the calendar saves schedules.

e_cal_get_static_capability ()

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

Queries the calendar for static capabilities.

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.

e_cal_get_refresh_supported ()

gboolean            e_cal_get_refresh_supported         (ECal *ecal);

Checks whether a calendar supports explicit refreshing (see e_cal_refresh).

Since 2.30

e_cal_set_mode ()

gboolean            e_cal_set_mode                      (ECal *ecal,
                                                         CalMode mode);

Switches online/offline mode on the calendar.

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.

e_cal_get_object ()

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

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

e_cal_get_objects_for_uid ()

gboolean            e_cal_get_objects_for_uid           (ECal *ecal,
                                                         const gchar *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.

e_cal_get_changes ()

gboolean            e_cal_get_changes                   (ECal *ecal,
                                                         const gchar *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.

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.

e_cal_get_object_list ()

gboolean            e_cal_get_object_list               (ECal *ecal,
                                                         const gchar *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.

e_cal_get_object_list_as_comp ()

gboolean            e_cal_get_object_list_as_comp       (ECal *ecal,
                                                         const gchar *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.

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.

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.

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.

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.

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.

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

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.

e_cal_create_object ()

gboolean            e_cal_create_object                 (ECal *ecal,
                                                         icalcomponent *icalcomp,
                                                         gchar **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.

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

e_cal_remove_object ()

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

Asks a calendar to remove all components with the given UID. If more control of the removal is desired, then use e_cal_remove_object_with_mod(). If the server is able to remove the component(s), all clients will be notified and they will emit the "obj_removed" signal.

e_cal_remove_object_with_mod ()

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

This function allows the removal of instances of a recurrent appointment. If what you want is to remove all instances, use e_cal_remove_object instead.

By using a combination of the uid, rid and mod arguments, you can remove specific instances. uid is mandatory. Empty or NULL rid selects the parent appointment (the one with the recurrence rule). A non-empty rid selects the recurrence at the time specified in rid, using the same time zone as the parent appointment's start time.

The exact semantic then depends on mod. CALOBJ_MOD_THIS, CALOBJ_MOD_THISANDPRIOR, CALOBJ_MOD_THISANDFUTURE and CALOBJ_MOD_ALL ensure that the event does not recur at the selected instance(s). This is done by removing any detached recurrence matching the selection criteria and modifying the parent appointment (adding EXDATE, adjusting recurrence rules, etc.). It is not an error if uid+rid do not match an existing instance.

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

CALOBJ_MOD_ONLY_THIS changes the semantic of CALOBJ_MOD_THIS: uid and rid must select an existing instance. That instance is removed without modifying the parent appointment. In other words, e_cal_remove_object_with_mod(CALOBJ_MOD_ONLY_THIS) is the inverse operation for adding a detached recurrence. The client is always sent an "obj_removed" signal.

Note that not all backends support CALOBJ_MOD_ONLY_THIS. Check for the CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS capability before using it. Previous releases did not check consistently for unknown mod values, using it with them may have had unexpected results.

e_cal_discard_alarm ()

gboolean            e_cal_discard_alarm                 (ECal *ecal,
                                                         ECalComponent *comp,
                                                         const gchar *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.

CALOBJ_MOD_ONLY_THIS is not supported in this call.

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.

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.

e_cal_get_timezone ()

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

Retrieves a timezone object from the calendar backend.

e_cal_add_timezone ()

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

Add a VTIMEZONE object to the given calendar.

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.

e_cal_get_query ()

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

Creates a live query object from a loaded calendar.

e_cal_resolve_tzid_cb ()

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

Resolves TZIDs for the recurrence generator.

e_cal_get_component_as_string ()

gchar *             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.

e_cal_get_error_message ()

const gchar *       e_cal_get_error_message             (ECalendarStatus status);

Gets an error message for the given status code.

e_cal_open_default ()

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

Opens the default calendar.

e_cal_set_default ()

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

Sets the ESource in ecal as default.

e_cal_set_default_source ()

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

Sets source as the default source for the specified type.

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.

e_cal_get_local_attachment_store ()

const gchar *       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.

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.

e_cal_get_attachments_for_comp ()

gboolean            e_cal_get_attachments_for_comp      (ECal *ecal,
                                                         const gchar *uid,
                                                         const gchar *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.

The "backend-died" signal

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

The "backend-error" signal

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

The "cal-opened" signal

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

The "cal-opened-ex" signal

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

The "cal-set-mode" signal

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