Evolution Developer's Guide
<<< Previous Page | Home | Up | Next Page >>>

# CalComponent

## Name

CalComponent -- RFC 2445 iCalendar component object.

## Synopsis

    #define     CAL_COMPONENT                   (obj)
    enum        CalComponentVType;
    enum        CalComponentField;
    enum        CalComponentClassification;
    typedef     CalComponentDateTime;
    enum        CalComponentPeriodType;
    typedef     CalComponentPeriod;
    typedef     CalComponentText;
    enum        CalComponentTransparency;
    char*       cal_component_gen_uid           (void);
    CalComponent* cal_component_new             (void);
    CalComponent* cal_component_clone           (CalComponent *comp);
    void        cal_component_set_new_vtype     (CalComponent *comp,
                                                 CalComponentVType type);
    gboolean    cal_component_set_icalcomponent (CalComponent *comp,
                                                 icalcomponent *icalcomp);
    icalcomponent* cal_component_get_icalcomponent
                                                (CalComponent *comp);
    CalComponentVType cal_component_get_vtype   (CalComponent *comp);
    char*       cal_component_get_as_string     (CalComponent *comp);
    void        cal_component_commit_sequence   (CalComponent *comp);
    void        cal_component_get_uid           (CalComponent *comp,
                                                 const char **uid);
    void        cal_component_set_uid           (CalComponent *comp,
                                                 const char *uid);
    void        cal_component_get_categories    (CalComponent *comp,
                                                 const char **categories);
    void        cal_component_set_categories    (CalComponent *comp,
                                                 const char *categories);
    void        cal_component_get_categories_list
                                                (CalComponent *comp,
                                                 GSList **categ_list);
    void        cal_component_set_categories_list
                                                (CalComponent *comp,
                                                 GSList *categ_list);
    void        cal_component_get_classification
                                                (CalComponent *comp,
                                                 CalComponentClassification *classif);
    void        cal_component_set_classification
                                                (CalComponent *comp,
                                                 CalComponentClassification classif);
    void        cal_component_get_comment_list  (CalComponent *comp,
                                                 GSList **text_list);
    void        cal_component_set_comment_list  (CalComponent *comp,
                                                 GSList *text_list);
    void        cal_component_get_completed     (CalComponent *comp,
                                                 struct icaltimetype **t);
    void        cal_component_set_completed     (CalComponent *comp,
                                                 struct icaltimetype *t);
    void        cal_component_get_created       (CalComponent *comp,
                                                 struct icaltimetype **t);
    void        cal_component_set_created       (CalComponent *comp,
                                                 struct icaltimetype *t);
    void        cal_component_get_description_list
                                                (CalComponent *comp,
                                                 GSList **text_list);
    void        cal_component_set_description_list
                                                (CalComponent *comp,
                                                 GSList *text_list);
    void        cal_component_get_dtend         (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_set_dtend         (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_get_dtstamp       (CalComponent *comp,
                                                 struct icaltimetype *t);
    void        cal_component_set_dtstamp       (CalComponent *comp,
                                                 struct icaltimetype *t);
    void        cal_component_get_dtstart       (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_set_dtstart       (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_get_due           (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_set_due           (CalComponent *comp,
                                                 CalComponentDateTime *dt);
    void        cal_component_get_exdate_list   (CalComponent *comp,
                                                 GSList **exdate_list);
    void        cal_component_set_exdate_list   (CalComponent *comp,
                                                 GSList *exdate_list);
    gboolean    cal_component_has_exdates       (CalComponent *comp);
    void        cal_component_get_exrule_list   (CalComponent *comp,
                                                 GSList **recur_list);
    void        cal_component_get_exrule_property_list
                                                (CalComponent *comp,
                                                 GSList **recur_list);
    void        cal_component_set_exrule_list   (CalComponent *comp,
                                                 GSList *recur_list);
    gboolean    cal_component_has_exrules       (CalComponent *comp);
    gboolean    cal_component_has_exceptions    (CalComponent *comp);
    void        cal_component_get_geo           (CalComponent *comp,
                                                 struct icalgeotype **geo);
    void        cal_component_set_geo           (CalComponent *comp,
                                                 struct icalgeotype *geo);
    void        cal_component_get_last_modified (CalComponent *comp,
                                                 struct icaltimetype **t);
    void        cal_component_set_last_modified (CalComponent *comp,
                                                 struct icaltimetype *t);
    void        cal_component_get_percent       (CalComponent *comp,
                                                 int **percent);
    void        cal_component_set_percent       (CalComponent *comp,
                                                 int *percent);
    void        cal_component_get_priority      (CalComponent *comp,
                                                 int **priority);
    void        cal_component_set_priority      (CalComponent *comp,
                                                 int *priority);
    void        cal_component_get_rdate_list    (CalComponent *comp,
                                                 GSList **period_list);
    void        cal_component_set_rdate_list    (CalComponent *comp,
                                                 GSList *period_list);
    gboolean    cal_component_has_rdates        (CalComponent *comp);
    void        cal_component_get_rrule_list    (CalComponent *comp,
                                                 GSList **recur_list);
    void        cal_component_get_rrule_property_list
                                                (CalComponent *comp,
                                                 GSList **recur_list);
    void        cal_component_set_rrule_list    (CalComponent *comp,
                                                 GSList *recur_list);
    gboolean    cal_component_has_rrules        (CalComponent *comp);
    gboolean    cal_component_has_recurrences   (CalComponent *comp);
    void        cal_component_get_sequence      (CalComponent *comp,
                                                 int **sequence);
    void        cal_component_set_sequence      (CalComponent *comp,
                                                 int *sequence);
    void        cal_component_get_status        (CalComponent *comp,
                                                 icalproperty_status *status);
    void        cal_component_set_status        (CalComponent *comp,
                                                 icalproperty_status status);
    void        cal_component_get_summary       (CalComponent *comp,
                                                 CalComponentText *summary);
    void        cal_component_set_summary       (CalComponent *comp,
                                                 CalComponentText *summary);
    void        cal_component_get_transparency  (CalComponent *comp,
                                                 CalComponentTransparency *transp);
    void        cal_component_set_transparency  (CalComponent *comp,
                                                 CalComponentTransparency transp);
    void        cal_component_get_url           (CalComponent *comp,
                                                 const char **url);
    void        cal_component_set_url           (CalComponent *comp,
                                                 const char *url);

    void        cal_component_free_categories_list
                                                (GSList *categ_list);
    void        cal_component_free_datetime     (CalComponentDateTime *dt);
    void        cal_component_free_exdate_list  (GSList *exdate_list);
    void        cal_component_free_geo          (struct icalgeotype *geo);
    void        cal_component_free_icaltimetype (struct icaltimetype *t);
    void        cal_component_free_percent      (int *percent);
    void        cal_component_free_priority     (int *priority);
    void        cal_component_free_period_list  (GSList *period_list);
    void        cal_component_free_recur_list   (GSList *recur_list);
    void        cal_component_free_sequence     (int *sequence);
    void        cal_component_free_text_list    (GSList *text_list);

    struct      CalComponentAlarm;
    typedef     CalAlarmInstance;
    typedef     CalComponentAlarms;
    enum        CalAlarmAction;
    enum        CalAlarmTriggerType;
    typedef     CalAlarmTrigger;
    gboolean    cal_component_has_alarms        (CalComponent *comp);
    GList*      cal_component_get_alarm_uids    (CalComponent *comp);
    CalComponentAlarm* cal_component_get_alarm  (CalComponent *comp,
                                                 const char *auid);
    void        cal_component_alarm_free        (CalComponentAlarm *alarm);
    void        cal_component_alarms_free       (CalComponentAlarms *alarms);
    const char* cal_component_alarm_get_uid     (CalComponentAlarm *alarm);
    void        cal_component_alarm_get_action  (CalComponentAlarm *alarm,
                                                 CalAlarmAction *action);
    void        cal_component_alarm_set_action  (CalComponentAlarm *alarm,
                                                 CalAlarmAction action);
    void        cal_component_alarm_get_trigger (CalComponentAlarm *alarm,
                                                 CalAlarmTrigger *trigger);
    void        cal_component_alarm_set_trigger (CalComponentAlarm *alarm,
                                                 CalAlarmTrigger trigger);

## Object Hierarchy

      GtkObject
       +----CalComponent

## Description

The CalComponent object provides a wrapper over the libical functions for manipulating calendar components. CalComponent presents a GTK+-like interface to calendar components according to RFC 2445.

While libical supports almost all of the features of the iCalendar RFCs, applications are normally not interested in all the mindless gunk that is there. Still, applications should do their best not to drop extension fields from calendar components or any other extra information they do not support (including standard fields they are not interested in). The CalComponent object provides a wrapper over icalcomponent structures from libical so that no information in them will be lost even if the application is not designed to handle it. Also, CalComponent provides a higher-level API to many of the libical operations so as to make it less painful to deal with iCalendar components.

A CalComponent object starts out empty. It must be initialized from an existing icalcomponent structure by using the cal_component_set_icalcomponent() function, or from a completely new data by specifying the desired component type to the cal_component_set_new_vtype() function.

CalComponent will create an internal map of the properties in the icalcomponent structure and then allow random access to them via the CalComponent API functions; normally the libical API would have to be used by creating many iterators and other unpleasant constructs. CalComponent keeps handles to the properties it scanned from the icalcomponent and will let the parent application modify them at any time without having to do any iteration.

Eventually a CalComponent may be turned into the RFC 2445 string representation of an iCalendar component by using the cal_component_get_as_string() function. Applications can then transfer this interoperable [1] string to other programs that deal with iCalendar.

## Details

### CAL_COMPONENT()

    #define CAL_COMPONENT(obj)            (GTK_CHECK_CAST ((obj), CAL_COMPONENT_TYPE, CalComponent))

Casts a GtkObject to a CalComponent.

`obj` : | A GTK+ object.

### enum CalComponentVType

    typedef enum {
    	CAL_COMPONENT_NO_TYPE,
    	CAL_COMPONENT_EVENT,
    	CAL_COMPONENT_TODO,
    	CAL_COMPONENT_JOURNAL,
    	CAL_COMPONENT_FREEBUSY,
    	CAL_COMPONENT_TIMEZONE
    } CalComponentVType;

Calendar component types as defined by RFC 2445. These values can be used to create a new calendar component by passing them to the cal_component_set_new_vtype() function. They are also the return value of the cal_component_get_vtype() function. The only time the `CAL_COMPONENT_NO_TYPE` value is used is when querying the vtype of an uninitialized CalComponent.

### enum CalComponentField

    typedef enum {
    	CAL_COMPONENT_FIELD_CATEGORIES,		/* concatenation of the categories list */
    	CAL_COMPONENT_FIELD_CLASSIFICATION,
    	CAL_COMPONENT_FIELD_COMPLETED,
    	CAL_COMPONENT_FIELD_DTEND,
    	CAL_COMPONENT_FIELD_DTSTART,
    	CAL_COMPONENT_FIELD_DUE,
    	CAL_COMPONENT_FIELD_GEO,
    	CAL_COMPONENT_FIELD_PERCENT,
    	CAL_COMPONENT_FIELD_PRIORITY,
    	CAL_COMPONENT_FIELD_SUMMARY,
    	CAL_COMPONENT_FIELD_TRANSPARENCY,
    	CAL_COMPONENT_FIELD_URL,
    	CAL_COMPONENT_FIELD_HAS_ALARMS,		/* not a real field */
    	CAL_COMPONENT_FIELD_ICON,		/* not a real field */
    	CAL_COMPONENT_FIELD_COMPLETE,		/* not a real field */
    	CAL_COMPONENT_FIELD_RECURRING,		/* not a real field */
    	CAL_COMPONENT_FIELD_OVERDUE,		/* not a real field */
    	CAL_COMPONENT_FIELD_COLOR,		/* not a real field */
    	CAL_COMPONENT_FIELD_STATUS,
    	CAL_COMPONENT_FIELD_COMPONENT,		/* not a real field */
    #if 0
    	CAL_COMPONENT_FIELD_LOCATION,
    #endif
    	CAL_COMPONENT_FIELD_NUM_FIELDS
    } CalComponentField;

These values are used as identifiers for ETable columns. These are used by the calendar GUI code in Evolution.

### enum CalComponentClassification

    typedef enum {
    	CAL_COMPONENT_CLASS_NONE,
    	CAL_COMPONENT_CLASS_PUBLIC,
    	CAL_COMPONENT_CLASS_PRIVATE,
    	CAL_COMPONENT_CLASS_CONFIDENTIAL,
    	CAL_COMPONENT_CLASS_UNKNOWN
    } CalComponentClassification;

Values for the access classification property of a calendar component.

### CalComponentDateTime

    typedef struct {
    	/* Actual date/time value */
    	struct icaltimetype *value;

    	/* Timezone ID */
    	const char *tzid;
    } CalComponentDateTime;

This structure defines a date and time value.

### enum CalComponentPeriodType

    typedef enum {
    	CAL_COMPONENT_PERIOD_DATETIME,
    	CAL_COMPONENT_PERIOD_DURATION
    } CalComponentPeriodType;

Defines how a period of time is specified.

### CalComponentPeriod

    typedef struct {
    	CalComponentPeriodType type;

    	struct icaltimetype start;

    	union {
    		struct icaltimetype end;
    		struct icaldurationtype duration;
    	} u;
    } CalComponentPeriod;

This structure defines a period of time.

### CalComponentText

    typedef struct {
    	/* Description string */
    	const char *value;

    	/* Alternate representation URI */
    	const char *altrep;
    } CalComponentText;

This structure defines the value of a text property that may have an alternate representation parameter.

### enum CalComponentTransparency

    typedef enum {
    	CAL_COMPONENT_TRANSP_NONE,
    	CAL_COMPONENT_TRANSP_TRANSPARENT,
    	CAL_COMPONENT_TRANSP_OPAQUE,
    	CAL_COMPONENT_TRANSP_UNKNOWN
    } CalComponentTransparency;

### cal_component_gen_uid ()

    char*       cal_component_gen_uid           (void);

Generates a unique identifier suitable for calendar components.

Returns : | A unique identifier string. Every time this function is called a different string is returned.

### cal_component_new ()

    CalComponent* cal_component_new             (void);

Creates a new empty calendar component object. You should set it from an icalcomponent structure by using cal_component_set_icalcomponent() or with a new empty component type by using cal_component_set_new_vtype().

Returns : | A newly-created calendar component object.

### cal_component_clone ()

    CalComponent* cal_component_clone           (CalComponent *comp);

Creates a new calendar component object by copying the information from another one.

`comp` : | A calendar component object.
Returns : | A newly-created calendar component with the same values as the original one.

### cal_component_set_new_vtype ()

    void        cal_component_set_new_vtype     (CalComponent *comp,
                                                 CalComponentVType type);

Clears any existing component data from a calendar component object and creates a new icalcomponent of the specified type for it. The only property that will be set in the new component will be its unique identifier.

`comp` : | A calendar component object.
`type` : | Type of calendar component to create.

### cal_component_set_icalcomponent ()

    gboolean    cal_component_set_icalcomponent (CalComponent *comp,
                                                 icalcomponent *icalcomp);

Sets the contents of a calendar component object from an icalcomponent structure. If the `comp` already had an icalcomponent set into it, it will will be freed automatically if the icalcomponent does not have a parent component itself.

Supported component types are VEVENT, VTODO, VJOURNAL, VFREEBUSY, and VTIMEZONE.

`comp` : | A calendar component object.
`icalcomp` : | An icalcomponent.
Returns : | TRUE on success, FALSE if `icalcomp` is an unsupported component type.

### cal_component_get_icalcomponent ()

    icalcomponent* cal_component_get_icalcomponent
                                                (CalComponent *comp);

Queries the icalcomponent structure that a calendar component object is wrapping.

`comp` : | A calendar component object.
Returns : | An icalcomponent structure, or NULL if the `comp` has no icalcomponent set to it.

### cal_component_get_vtype ()

    CalComponentVType cal_component_get_vtype   (CalComponent *comp);

Queries the type of a calendar component object.

`comp` : | A calendar component object.
Returns : | The type of the component, as defined by RFC 2445.

### cal_component_get_as_string ()

    char*       cal_component_get_as_string     (CalComponent *comp);

Gets the iCalendar string representation of a calendar component. You should call cal_component_commit_sequence() before this function to ensure that the component's sequence number is consistent with the state of the object.

`comp` : | A calendar component.
Returns : | String representation of the calendar component according to RFC 2445.

### cal_component_commit_sequence ()

    void        cal_component_commit_sequence   (CalComponent *comp);

Increments the sequence number property in a calendar component object if it needs it. This needs to be done when any of a number of properties listed in RFC 2445 change values, such as the start and end dates of a component.

This function must be called before calling cal_component_get_as_string() to ensure that the component is fully consistent.

`comp` : |

### cal_component_get_uid ()

    void        cal_component_get_uid           (CalComponent *comp,
                                                 const char **uid);

Queries the unique identifier of a calendar component object.

`comp` : | A calendar component object.
`uid` : | Return value for the UID string.

### cal_component_set_uid ()

    void        cal_component_set_uid           (CalComponent *comp,
                                                 const char *uid);

Sets the unique identifier string of a calendar component object.

`comp` : | A calendar component object.
`uid` : | Unique identifier.

### cal_component_get_categories ()

    void        cal_component_get_categories    (CalComponent *comp,
                                                 const char **categories);

`comp` : | A calendar component object.
`categories` : |

### cal_component_set_categories ()

    void        cal_component_set_categories    (CalComponent *comp,
                                                 const char *categories);

`comp` : | A calendar component object.
`categories` : |

### cal_component_get_categories_list ()

    void        cal_component_get_categories_list
                                                (CalComponent *comp,
                                                 GSList **categ_list);

Queries the list of categories of a calendar component object. Each element in the returned categ_list is a string with the corresponding category.

`comp` : | A calendar component object.
`categ_list` : | Return value for the list of strings, where each string is a category. This should be freed using cal_component_free_categories_list().

### cal_component_set_categories_list ()

    void        cal_component_set_categories_list
                                                (CalComponent *comp,
                                                 GSList *categ_list);

Sets the list of categories of a calendar component object.

`comp` : | A calendar component object.
`categ_list` : | List of strings, one for each category.

### cal_component_get_classification ()

    void        cal_component_get_classification
                                                (CalComponent *comp,
                                                 CalComponentClassification *classif);

Queries the classification of a calendar component object. If the classification property is not set on this component, this function returns CAL_COMPONENT_CLASS_NONE.

`comp` : | A calendar component object.
`classif` : | Return value for the classification.

### cal_component_set_classification ()

    void        cal_component_set_classification
                                                (CalComponent *comp,
                                                 CalComponentClassification classif);

Sets the classification property of a calendar component object. To unset the property, specify CAL_COMPONENT_CLASS_NONE for `classif`.

`comp` : | A calendar component object.
`classif` : | Classification to use.

### cal_component_get_comment_list ()

    void        cal_component_get_comment_list  (CalComponent *comp,
                                                 GSList **text_list);

Queries the comment of a calendar component object. The comment property can appear several times inside a calendar component, and so a list of CalComponentText is returned.

`comp` : | A calendar component object.
`text_list` : | Return value for the comment properties and their parameters, as a list of CalComponentText structures. This should be freed using the cal_component_free_text_list() function.

### cal_component_set_comment_list ()

    void        cal_component_set_comment_list  (CalComponent *comp,
                                                 GSList *text_list);

Sets the comment of a calendar component object. The comment property can appear several times inside a calendar component, and so a list of CalComponentText structures is used.

`comp` : | A calendar component object.
`text_list` : | List of CalComponentText structures.

### cal_component_get_completed ()

    void        cal_component_get_completed     (CalComponent *comp,
                                                 struct icaltimetype **t);

Queries the date at which a calendar compoment object was completed.

`comp` : | A calendar component object.
`t` : | Return value for the completion date. This should be freed using the cal_component_free_icaltimetype() function.

### cal_component_set_completed ()

    void        cal_component_set_completed     (CalComponent *comp,
                                                 struct icaltimetype *t);

Sets the date at which a calendar component object was completed.

`comp` : | A calendar component object.
`t` : | Value for the completion date.

### cal_component_get_created ()

    void        cal_component_get_created       (CalComponent *comp,
                                                 struct icaltimetype **t);

Queries the date in which a calendar component object was created in the calendar store.

`comp` : | A calendar component object.
`t` : | Return value for the creation date. This should be freed using the cal_component_free_icaltimetype() function.

### cal_component_set_created ()

    void        cal_component_set_created       (CalComponent *comp,
                                                 struct icaltimetype *t);

Sets the date in which a calendar component object is created in the calendar store. This should only be used inside a calendar store application, i.e. not by calendar user agents.

`comp` : | A calendar component object.
`t` : | Value for the creation date.

### cal_component_get_description_list ()

    void        cal_component_get_description_list
                                                (CalComponent *comp,
                                                 GSList **text_list);

Queries the description of a calendar component object. Journal components may have more than one description, and as such this function returns a list of CalComponentText structures. All other types of components can have at most one description.

`comp` : | A calendar component object.
`text_list` : | Return value for the description properties and their parameters, as a list of CalComponentText structures. This should be freed using the cal_component_free_text_list() function.

### cal_component_set_description_list ()

    void        cal_component_set_description_list
                                                (CalComponent *comp,
                                                 GSList *text_list);

Sets the description of a calendar component object. Journal components may have more than one description, and as such this function takes in a list of CalComponentDescription structures. All other types of components can have at most one description.

`comp` : | A calendar component object.
`text_list` : | List of CalComponentSummary structures.

### cal_component_get_dtend ()

    void        cal_component_get_dtend         (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Queries the date/time end of a calendar component object.

`comp` : | A calendar component object.
`dt` : | Return value for the date/time end. This should be freed with the cal_component_free_datetime() function.

### cal_component_set_dtend ()

    void        cal_component_set_dtend         (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Sets the date/time end property of a calendar component object.

`comp` : | A calendar component object.
`dt` : | End date/time.

### cal_component_get_dtstamp ()

    void        cal_component_get_dtstamp       (CalComponent *comp,
                                                 struct icaltimetype *t);

Queries the date/timestamp property of a calendar component object, which is the last time at which the object was modified by a calendar user agent.

`comp` : | A calendar component object.
`t` : | A value for the date/timestamp.

### cal_component_set_dtstamp ()

    void        cal_component_set_dtstamp       (CalComponent *comp,
                                                 struct icaltimetype *t);

Sets the date/timestamp of a calendar component object. This should be called whenever a calendar user agent makes a change to a component's properties.

`comp` : | A calendar component object.
`t` : | Date/timestamp value.

### cal_component_get_dtstart ()

    void        cal_component_get_dtstart       (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Queries the date/time start of a calendar component object.

`comp` : | A calendar component object.
`dt` : | Return value for the date/time start. This should be freed with the cal_component_free_datetime() function.

### cal_component_set_dtstart ()

    void        cal_component_set_dtstart       (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Sets the date/time start property of a calendar component object.

`comp` : | A calendar component object.
`dt` : | Start date/time.

### cal_component_get_due ()

    void        cal_component_get_due           (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Queries the due date/time of a calendar component object.

`comp` : | A calendar component object.
`dt` : | Return value for the due date/time. This should be freed with the cal_component_free_datetime() function.

### cal_component_set_due ()

    void        cal_component_set_due           (CalComponent *comp,
                                                 CalComponentDateTime *dt);

Sets the due date/time property of a calendar component object.

`comp` : | A calendar component object.
`dt` : | End date/time.

### cal_component_get_exdate_list ()

    void        cal_component_get_exdate_list   (CalComponent *comp,
                                                 GSList **exdate_list);

Queries the list of exception date properties in a calendar component object.

`comp` : | A calendar component object.
`exdate_list` : | Return value for the list of exception dates, as a list of CalComponentDateTime structures. This should be freed using the cal_component_free_exdate_list() function.

### cal_component_set_exdate_list ()

    void        cal_component_set_exdate_list   (CalComponent *comp,
                                                 GSList *exdate_list);

Sets the list of exception dates in a calendar component object.

`comp` : | A calendar component object.
`exdate_list` : | List of CalComponentDateTime structures.

### cal_component_has_exdates ()

    gboolean    cal_component_has_exdates       (CalComponent *comp);

Queries whether a calendar component object has any exception dates defined for it.

`comp` : | A calendar component object.
Returns : | TRUE if the component has exception dates, FALSE otherwise.

### cal_component_get_exrule_list ()

    void        cal_component_get_exrule_list   (CalComponent *comp,
                                                 GSList **recur_list);

Queries the list of exception rule properties of a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | List of exception rules as struct icalrecurrencetype structures. This should be freed using the cal_component_free_recur_list() function.

### cal_component_get_exrule_property_list ()

    void        cal_component_get_exrule_property_list
                                                (CalComponent *comp,
                                                 GSList **recur_list);

Queries the list of exception rule properties of a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | Returns a list of exception rule properties.

### cal_component_set_exrule_list ()

    void        cal_component_set_exrule_list   (CalComponent *comp,
                                                 GSList *recur_list);

Sets the list of exception rules in a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | List of struct icalrecurrencetype structures.

### cal_component_has_exrules ()

    gboolean    cal_component_has_exrules       (CalComponent *comp);

Queries whether a calendar component object has any exception rules defined for it.

`comp` : | A calendar component object.
Returns : | TRUE if the component has exception rules, FALSE otherwise.

### cal_component_has_exceptions ()

    gboolean    cal_component_has_exceptions    (CalComponent *comp);

Queries whether a calendar component object has any exception dates or exception rules.

`comp` : | A calendar component object
Returns : | TRUE if the component has exceptions, FALSE otherwise.

### cal_component_get_geo ()

    void        cal_component_get_geo           (CalComponent *comp,
                                                 struct icalgeotype **geo);

Sets the geographic position property of a calendar component object.

`comp` : | A calendar component object.
`geo` : | Return value for the geographic position property. This should be freed using the cal_component_free_geo() function.

### cal_component_set_geo ()

    void        cal_component_set_geo           (CalComponent *comp,
                                                 struct icalgeotype *geo);

Sets the geographic position property on a calendar component object.

`comp` : | A calendar component object.
`geo` : | Value for the geographic position property.

### cal_component_get_last_modified ()

    void        cal_component_get_last_modified (CalComponent *comp,
                                                 struct icaltimetype **t);

Queries the time at which a calendar component object was last modified in the calendar store.

`comp` : | A calendar component object.
`t` : | Return value for the last modified time value.

### cal_component_set_last_modified ()

    void        cal_component_set_last_modified (CalComponent *comp,
                                                 struct icaltimetype *t);

Sets the time at which a calendar component object was last stored in the calendar store. This should not be called by plain calendar user agents.

`comp` : | A calendar component object.
`t` : | Value for the last time modified.

### cal_component_get_percent ()

    void        cal_component_get_percent       (CalComponent *comp,
                                                 int **percent);

Queries the percent-complete property of a calendar component object.

`comp` : | A calendar component object.
`percent` : | Return value for the percent-complete property. This should be freed using the cal_component_free_percent() function.

### cal_component_set_percent ()

    void        cal_component_set_percent       (CalComponent *comp,
                                                 int *percent);

Sets the percent-complete property of a calendar component object.

`comp` : | A calendar component object.
`percent` : | Value for the percent-complete property.

### cal_component_get_priority ()

    void        cal_component_get_priority      (CalComponent *comp,
                                                 int **priority);

Queries the priority property of a calendar component object.

`comp` : | A calendar component object.
`priority` : | Return value for the priority property. This should be freed using the cal_component_free_priority() function.

### cal_component_set_priority ()

    void        cal_component_set_priority      (CalComponent *comp,
                                                 int *priority);

Sets the priority property of a calendar component object.

`comp` : | A calendar component object.
`priority` : | Value for the priority property.

### cal_component_get_rdate_list ()

    void        cal_component_get_rdate_list    (CalComponent *comp,
                                                 GSList **period_list);

Queries the list of recurrence date properties in a calendar component object.

`comp` : | A calendar component object.
`period_list` : | Return value for the list of recurrence dates, as a list of CalComponentPeriod structures. This should be freed using the cal_component_free_period_list() function.

### cal_component_set_rdate_list ()

    void        cal_component_set_rdate_list    (CalComponent *comp,
                                                 GSList *period_list);

Sets the list of recurrence dates in a calendar component object.

`comp` : | A calendar component object.
`period_list` : | List of CalComponentPeriod structures.

### cal_component_has_rdates ()

    gboolean    cal_component_has_rdates        (CalComponent *comp);

Queries whether a calendar component object has any recurrence dates defined for it.

`comp` : | A calendar component object.
Returns : | TRUE if the component has recurrence dates, FALSE otherwise.

### cal_component_get_rrule_list ()

    void        cal_component_get_rrule_list    (CalComponent *comp,
                                                 GSList **recur_list);

Queries the list of recurrence rule properties of a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | List of recurrence rules as struct icalrecurrencetype structures. This should be freed using the cal_component_free_recur_list() function.

### cal_component_get_rrule_property_list ()

    void        cal_component_get_rrule_property_list
                                                (CalComponent *comp,
                                                 GSList **recur_list);

Queries a list of recurrence rule properties of a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | Returns a list of recurrence rule properties.

### cal_component_set_rrule_list ()

    void        cal_component_set_rrule_list    (CalComponent *comp,
                                                 GSList *recur_list);

Sets the list of recurrence rules in a calendar component object.

`comp` : | A calendar component object.
`recur_list` : | List of struct icalrecurrencetype structures.

### cal_component_has_rrules ()

    gboolean    cal_component_has_rrules        (CalComponent *comp);

Queries whether a calendar component object has any recurrence rules defined for it.

`comp` : | A calendar component object.
Returns : | TRUE if the component has recurrence rules, FALSE otherwise.

### cal_component_has_recurrences ()

    gboolean    cal_component_has_recurrences   (CalComponent *comp);

Queries whether a calendar component object has any recurrence dates or recurrence rules.

`comp` : | A calendar component object
Returns : | TRUE if the component has recurrences, FALSE otherwise.

### cal_component_get_sequence ()

    void        cal_component_get_sequence      (CalComponent *comp,
                                                 int **sequence);

Queries the sequence number of a calendar component object.

`comp` : | A calendar component object.
`sequence` : | Return value for the sequence number. This should be freed using cal_component_free_sequence().

### cal_component_set_sequence ()

    void        cal_component_set_sequence      (CalComponent *comp,
                                                 int *sequence);

Sets the sequence number of a calendar component object. Normally this function should not be called, since the sequence number is incremented automatically at the proper times.

`comp` : | A calendar component object.
`sequence` : | Sequence number value.

### cal_component_get_status ()

    void        cal_component_get_status        (CalComponent *comp,
                                                 icalproperty_status *status);

Queries the status property of a calendar component object.

`comp` : | A calendar component object.
`status` : | Return value for the status value. It is set to ICAL_STATUS_NONE if the component has no status property.

### cal_component_set_status ()

    void        cal_component_set_status        (CalComponent *comp,
                                                 icalproperty_status status);

Sets the status property of a calendar component object.

`comp` : | A calendar component object.
`status` : | Status value. You should use ICAL_STATUS_NONE if you want to unset this property.

### cal_component_get_summary ()

    void        cal_component_get_summary       (CalComponent *comp,
                                                 CalComponentText *summary);

Queries the summary of a calendar component object.

`comp` : | A calendar component object.
`summary` : | Return value for the summary property and its parameters.

### cal_component_set_summary ()

    void        cal_component_set_summary       (CalComponent *comp,
                                                 CalComponentText *summary);

Sets the summary of a calendar component object.

`comp` : | A calendar component object.
`summary` : | Summary property and its parameters.

### cal_component_get_transparency ()

    void        cal_component_get_transparency  (CalComponent *comp,
                                                 CalComponentTransparency *transp);

Queries the time transparency of a calendar component object.

`comp` : | A calendar component object.
`transp` : | Return value for the time transparency.

### cal_component_set_transparency ()

    void        cal_component_set_transparency  (CalComponent *comp,
                                                 CalComponentTransparency transp);

Sets the time transparency of a calendar component object.

`comp` : | A calendar component object.
`transp` : | Time transparency value.

### cal_component_get_url ()

    void        cal_component_get_url           (CalComponent *comp,
                                                 const char **url);

Queries the uniform resource locator property of a calendar component object.

`comp` : | A calendar component object.
`url` : | Return value for the URL.

### cal_component_set_url ()

    void        cal_component_set_url           (CalComponent *comp,
                                                 const char *url);

Sets the uniform resource locator property of a calendar component object.

`comp` : | A calendar component object.
`url` : | URL value.

### cal_component_free_categories_list ()

    void        cal_component_free_categories_list
                                                (GSList *categ_list);

Frees a list of category strings.

`categ_list` : | List of category strings.

### cal_component_free_datetime ()

    void        cal_component_free_datetime     (CalComponentDateTime *dt);

Frees a date/time structure.

`dt` : | A date/time structure.

### cal_component_free_exdate_list ()

    void        cal_component_free_exdate_list  (GSList *exdate_list);

Frees a list of CalComponentDateTime structures as returned by the cal_component_get_exdate_list() function.

`exdate_list` : | List of CalComponentDateTime structures.

### cal_component_free_geo ()

    void        cal_component_free_geo          (struct icalgeotype *geo);

Frees a struct icalgeotype structure as returned by the calendar component functions.

`geo` : | An icalgeotype structure.

### cal_component_free_icaltimetype ()

    void        cal_component_free_icaltimetype (struct icaltimetype *t);

Frees a struct icaltimetype value as returned by the calendar component functions.

`t` : | An icaltimetype structure.

### cal_component_free_percent ()

    void        cal_component_free_percent      (int *percent);

Frees a percent value as returned by the cal_component_get_percent() function.

`percent` : | Percent value.

### cal_component_free_priority ()

    void        cal_component_free_priority     (int *priority);

Frees a priority value as returned by the cal_component_get_priority() function.

`priority` : | Priority value.

### cal_component_free_period_list ()

    void        cal_component_free_period_list  (GSList *period_list);

Frees a list of CalComponentPeriod structures.

`period_list` : | List of CalComponentPeriod structures.

### cal_component_free_recur_list ()

    void        cal_component_free_recur_list   (GSList *recur_list);

Frees a list of struct icalrecurrencetype structures.

`recur_list` : | List of struct icalrecurrencetype structures.

### cal_component_free_sequence ()

    void        cal_component_free_sequence     (int *sequence);

Frees a sequence number value.

`sequence` : | Sequence number value.

### cal_component_free_text_list ()

    void        cal_component_free_text_list    (GSList *text_list);

Frees a list of CalComponentText structures. This function should only be used to free lists of text values as returned by the other getter functions of CalComponent.

`text_list` : | List of CalComponentText structures.

### struct CalComponentAlarm

    struct CalComponentAlarm;

### CalAlarmInstance

    typedef struct {
    	/* UID of the alarm that triggered */
    	const char *auid;

    	/* Trigger time, i.e. "5 minutes before the appointment" */
    	time_t trigger;

    	/* Actual event occurrence to which this trigger corresponds */
    	time_t occur_start;
    	time_t occur_end;
    } CalAlarmInstance;

### CalComponentAlarms

    typedef struct {
    	/* The actual component */
    	CalComponent *comp;

    	/* List of CalAlarmInstance structures */
    	GSList *alarms;
    } CalComponentAlarms;

### enum CalAlarmAction

    typedef enum {
    	CAL_ALARM_NONE,
    	CAL_ALARM_AUDIO,
    	CAL_ALARM_DISPLAY,
    	CAL_ALARM_EMAIL,
    	CAL_ALARM_PROCEDURE,
    	CAL_ALARM_UNKNOWN
    } CalAlarmAction;

### enum CalAlarmTriggerType

    typedef enum {
    	CAL_ALARM_TRIGGER_NONE,
    	CAL_ALARM_TRIGGER_RELATIVE_START,
    	CAL_ALARM_TRIGGER_RELATIVE_END,
    	CAL_ALARM_TRIGGER_ABSOLUTE
    } CalAlarmTriggerType;

### CalAlarmTrigger

    typedef struct {
    	CalAlarmTriggerType type;

    	union {
    		struct icaldurationtype rel_duration;
    		struct icaltimetype abs_time;
    	} u;
    } CalAlarmTrigger;

### cal_component_has_alarms ()

    gboolean    cal_component_has_alarms        (CalComponent *comp);

Checks whether the component has any alarms.

`comp` : | A calendar component object.
Returns : | TRUE if the component has any alarms.

### cal_component_get_alarm_uids ()

    GList*      cal_component_get_alarm_uids    (CalComponent *comp);

Builds a list of the unique identifiers of the alarm subcomponents inside a calendar component.

`comp` : | A calendar component.
Returns : | List of unique identifiers for alarms. This should be freed using cal_obj_uid_list_free().

### cal_component_get_alarm ()

    CalComponentAlarm* cal_component_get_alarm  (CalComponent *comp,
                                                 const char *auid);

Queries a particular alarm subcomponent of a calendar component.

`comp` : | A calendar component.
`auid` : | Unique identifier for the sought alarm subcomponent.
Returns : | The alarm subcomponent that corresponds to the specified `auid`, or NULL if no alarm exists with that UID. This should be freed using cal_component_alarm_free().

### cal_component_alarm_free ()

    void        cal_component_alarm_free        (CalComponentAlarm *alarm);

Frees an alarm structure.

`alarm` : | A calendar alarm.

### cal_component_alarms_free ()

    void        cal_component_alarms_free       (CalComponentAlarms *alarms);

Frees a CalComponentAlarms structure.

`alarms` : | Component alarms structure.

### cal_component_alarm_get_uid ()

    const char* cal_component_alarm_get_uid     (CalComponentAlarm *alarm);

Queries the unique identifier of an alarm subcomponent.

`alarm` : | An alarm subcomponent.
Returns : | UID of the alarm.

### cal_component_alarm_get_action ()

    void        cal_component_alarm_get_action  (CalComponentAlarm *alarm,
                                                 CalAlarmAction *action);

Queries the action type of an alarm.

`alarm` : | An alarm.
`action` : | Return value for the alarm's action type.

### cal_component_alarm_set_action ()

    void        cal_component_alarm_set_action  (CalComponentAlarm *alarm,
                                                 CalAlarmAction action);

Sets the action type for an alarm.

`alarm` : | An alarm.
`action` : | Action type.

### cal_component_alarm_get_trigger ()

    void        cal_component_alarm_get_trigger (CalComponentAlarm *alarm,
                                                 CalAlarmTrigger *trigger);

Queries the trigger time for an alarm.

`alarm` : | An alarm.
`trigger` : | Return value for the trigger time.

### cal_component_alarm_set_trigger ()

    void        cal_component_alarm_set_trigger (CalComponentAlarm *alarm,
                                                 CalAlarmTrigger trigger);

Sets the trigger time of an alarm.

`alarm` : | An alarm.
`trigger` : | Trigger time structure.

## Notes

[1] | “Interoperable.” Heavens, I love that word.

<<< Previous Page | Home | Up | Next Page >>>
CalClient | Miscellaneous utilities