# MIMEDirVComponent

## Name

MIMEDirVComponent -- iCalendar base object

## Synopsis

    #include <mimedir/mimedir-vcomponent.h>

                        MIMEDirVComponent;

    enum                MIMEDirClassification;
    enum                MIMEDirStatus;
    #define             MIMEDIR_VCOMPONENT_PERCENT_NONE

    gboolean            mimedir_vcomponent_read_from_profile
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirProfile *profile,
                                                             GError **error);
    MIMEDirProfile*     mimedir_vcomponent_write_to_profile (MIMEDirVComponent *vcomponent,
                                                             const gchar *profile_name);
    gchar*              mimedir_vcomponent_get_categories_as_string
                                                            (MIMEDirVComponent *vcomponent);
    void                mimedir_vcomponent_set_alarm_list   (MIMEDirVComponent *vcomponent,
                                                             const GList *list);
    const GList*        mimedir_vcomponent_get_alarm_list   (MIMEDirVComponent *vcomponent);
    void                mimedir_vcomponent_set_attendee_list
                                                            (MIMEDirVComponent *vcomponent,
                                                             const GList *list);
    const GList*        mimedir_vcomponent_get_attendee_list
                                                            (MIMEDirVComponent *vcomponent);
    void                mimedir_vcomponent_set_opaque       (MIMEDirVComponent *vcomponent,
                                                             gboolean opaque);
    gboolean            mimedir_vcomponent_get_opaque       (MIMEDirVComponent *vcomponent);
    void                mimedir_vcomponent_set_classification
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirClassification classification,
                                                             const gchar *klass);
    MIMEDirClassification mimedir_vcomponent_get_classification
                                                            (MIMEDirVComponent *vcomponent,
                                                             const gchar **klass);
    void                mimedir_vcomponent_set_location     (MIMEDirVComponent *vcomponent,
                                                             const gchar *location,
                                                             const gchar *uri);
    const gchar*        mimedir_vcomponent_get_location     (MIMEDirVComponent *vcomponent,
                                                             const gchar **uri);
    void                mimedir_vcomponent_set_geopos       (MIMEDirVComponent *vcomponent,
                                                             gdouble latitude,
                                                             gdouble longitude);
    void                mimedir_vcomponent_get_geopos       (MIMEDirVComponent *vcomponent,
                                                             gdouble *latitude,
                                                             gdouble *longitude);
    void                mimedir_vcomponent_set_recurrence   (MIMEDirVComponent *vcomponent,
                                                             MIMEDirRecurrence *recurrence);
    MIMEDirRecurrence*  mimedir_vcomponent_get_recurrence   (MIMEDirVComponent *vcomponent);
    void                mimedir_vcomponent_set_allday       (MIMEDirVComponent *vcomponent,
                                                             gboolean allday);
    gboolean            mimedir_vcomponent_get_allday       (MIMEDirVComponent *vcomponent);
    gboolean            mimedir_vcomponent_does_recur       (MIMEDirVComponent *vcomponent);
    MIMEDirDateTime*    mimedir_vcomponent_get_next_occurence
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *after);
    GList*              mimedir_vcomponent_get_occurences_between
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *start,
                                                             MIMEDirDateTime *end);
    void                mimedir_vcomponent_free_occurences  (GList *list);
    void                mimedir_vcomponent_set_attachment_list
                                                            (MIMEDirVComponent *vcomponent,
                                                             GList *list);
    GList*              mimedir_vcomponent_get_attachment_list
                                                            (MIMEDirVComponent *vcomponent);

## Description

## Details

### MIMEDirVComponent

    typedef struct {
    	GObject parent;

    	MIMEDirVComponentPriv *priv;
    } MIMEDirVComponent;

### enum MIMEDirClassification

    typedef enum {
    	MIMEDIR_CLASS_PUBLIC,
    	MIMEDIR_CLASS_PRIVATE,
    	MIMEDIR_CLASS_CONFIDENTIAL,
    	MIMEDIR_CLASS_CUSTOM
    } MIMEDirClassification;

Classification of an iCalendar component object, i.e. the "secrecy level".

`MIMEDIR_CLASS_PUBLIC` | Public classification
`MIMEDIR_CLASS_PRIVATE` | Private classification
`MIMEDIR_CLASS_CONFIDENTIAL` | Confidential classification
`MIMEDIR_CLASS_CUSTOM` | Custom classification (string attached)

### enum MIMEDirStatus

    typedef enum {
    	MIMEDIR_STATUS_UNKNOWN,
    	MIMEDIR_STATUS_CANCELLED,
    	MIMEDIR_STATUS_TENTATIVE,	/* VEvent */
    	MIMEDIR_STATUS_CONFIRMED,
    	MIMEDIR_STATUS_NEEDS_ACTION,	/* VTodo */
    	MIMEDIR_STATUS_COMPLETED,
    	MIMEDIR_STATUS_IN_PROCESS,
    	MIMEDIR_STATUS_DRAFT,		/* VJournal */
    	MIMEDIR_STATUS_FINAL
    } MIMEDirStatus;

`MIMEDIR_STATUS_UNKNOWN` | Unknown status
`MIMEDIR_STATUS_CANCELLED` | Cancelled appointment
`MIMEDIR_STATUS_TENTATIVE` | Tentative appointment
`MIMEDIR_STATUS_CONFIRMED` | Confirmed appointment
`MIMEDIR_STATUS_NEEDS_ACTION` | Needs action
`MIMEDIR_STATUS_COMPLETED` | Item completed
`MIMEDIR_STATUS_IN_PROCESS` | Item being worked on
`MIMEDIR_STATUS_DRAFT` | Preliminary item
`MIMEDIR_STATUS_FINAL` | Final item

### MIMEDIR_VCOMPONENT_PERCENT_NONE

    #define MIMEDIR_VCOMPONENT_PERCENT_NONE (101)

Used to signify that a percentage is unknown or unset.

### mimedir_vcomponent_read_from_profile ()

    gboolean            mimedir_vcomponent_read_from_profile
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirProfile *profile,
                                                             GError **error);

Clears the supplied vComponent object and re-initializes it with data read from the supplied profile. If an error occurs during the read, `error` will be set and `FALSE` will be returned. Otherwise, `TRUE` is returned.

`vcomponent` : | a vComponent object
`profile` : | a profile object
`error` : | error storage location or `NULL`
Returns : | success indicator

### mimedir_vcomponent_write_to_profile ()

    MIMEDirProfile*     mimedir_vcomponent_write_to_profile (MIMEDirVComponent *vcomponent,
                                                             const gchar *profile_name);

Saves the vcomponent object to a newly allocated profile object.

`vcomponent` : | a vcomponent
`profile_name` : | the new profile type
Returns : | a new profile

### mimedir_vcomponent_get_categories_as_string ()

    gchar*              mimedir_vcomponent_get_categories_as_string
                                                            (MIMEDirVComponent *vcomponent);

Returns the categories of this object as a human-readable, comma-separated string. The returned string should be freed with `g_free()`.

`vcomponent` : | a MIMEDirVComponent object
Returns : | a human-readable string

### mimedir_vcomponent_set_alarm_list ()

    void                mimedir_vcomponent_set_alarm_list   (MIMEDirVComponent *vcomponent,
                                                             const GList *list);

Sets the list of alarms of this component.

`vcomponent` : | a MIMEDirVComponent object
`list` : | a GList pointer

### mimedir_vcomponent_get_alarm_list ()

    const GList*        mimedir_vcomponent_get_alarm_list   (MIMEDirVComponent *vcomponent);

Returns all alarms of this component. The list must not be modified by the caller. The MIMEDirVAlarm objects in this list must be `g_object_ref()`'ed when they are to be used by the caller.

`vcomponent` : | a MIMEDirVComponent object
Returns : | a GList containing MIMEDirVAlarm objects

### mimedir_vcomponent_set_attendee_list ()

    void                mimedir_vcomponent_set_attendee_list
                                                            (MIMEDirVComponent *vcomponent,
                                                             const GList *list);

Sets the list of attendees for this component.

`vcomponent` : | a MIMEDirVComponent object
`list` : | a GList pointer

### mimedir_vcomponent_get_attendee_list ()

    const GList*        mimedir_vcomponent_get_attendee_list
                                                            (MIMEDirVComponent *vcomponent);

Returns the list of attendees to this particular component.

`vcomponent` : | a MIMEDirVComponent object
Returns : | a GList containing MIMEDirAttendee objects

### mimedir_vcomponent_set_opaque ()

    void                mimedir_vcomponent_set_opaque       (MIMEDirVComponent *vcomponent,
                                                             gboolean opaque);

Sets whether an event is to be considered opaque or transparent. A transparent event does not consume time on the calendar.

`vcomponent` : | a MIMEDirVComponent object
`opaque` : | `TRUE` or `FALSE`

### mimedir_vcomponent_get_opaque ()

    gboolean            mimedir_vcomponent_get_opaque       (MIMEDirVComponent *vcomponent);

Returns whether an event is opaque or transparent. Transparent events do not consume time on the calendar.

`vcomponent` : | a MIMEDirVComponent object
Returns : | a boolean value

### mimedir_vcomponent_set_classification ()

    void                mimedir_vcomponent_set_classification
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirClassification classification,
                                                             const gchar *klass);

Sets the new security classification to `classification`. If and only if the classification is `MIMEDIR_CLASS_CUSTOM` `klass` must be pointing to a string to use as security classification. Be sure you know what you're doing when using `MIMEDIR_CLASS_CUSTOM`!

`vcomponent` : | a MIMEDirVComponent object
`classification` : | the new security classification
`klass` : | textual security classficiation

### mimedir_vcomponent_get_classification ()

    MIMEDirClassification mimedir_vcomponent_get_classification
                                                            (MIMEDirVComponent *vcomponent,
                                                             const gchar **klass);

Returns the component's security classification. If the class ist `MIMEDIR_CLASS_CUSTOM` and `klass` is not `NULL`, `klass` will be filled to point to a string that signifies the security classification.

`vcomponent` : | a MIMEDirVComponent object
`klass` : | pointer to a string storage location or `NULL`
Returns : | the security classification

### mimedir_vcomponent_set_location ()

    void                mimedir_vcomponent_set_location     (MIMEDirVComponent *vcomponent,
                                                             const gchar *location,
                                                             const gchar *uri);

Sets the venue, such as a conference or meeting room. `uri`, if not `NULL`, points to an alternate representation such as an web site or an LDAP entry.

If `location` is `NULL` the property will be unset. In this case, `uri` must be `NULL` as well.

`vcomponent` : | a MIMEDirVComponent object
`location` : | location specification or `NULL`
`uri` : | optional alternate URI or `NULL`

### mimedir_vcomponent_get_location ()

    const gchar*        mimedir_vcomponent_get_location     (MIMEDirVComponent *vcomponent,
                                                             const gchar **uri);

Retrieves the venue, such as a conference or meeting room. If this property is not set, `NULL` will be returned.

If `uri` is not `NULL`, it will be set to an URI to an alternate representation (if one was set). If no alternate representation URI was given, `uri` will be set to `NULL`.

`vcomponent` : | a MIMEDirVComponent object
`uri` : | uri storage pointer or `NULL`
Returns : | location string or `NULL`

### mimedir_vcomponent_set_geopos ()

    void                mimedir_vcomponent_set_geopos       (MIMEDirVComponent *vcomponent,
                                                             gdouble latitude,
                                                             gdouble longitude);

Sets this component's geographic position to `latitude`/`longitude`.

`vcomponent` : | a MIMEDirVComponent object
`latitude` : | latitude from -90 to +90 degrees
`longitude` : | longitude from -180 to + 180 degrees

### mimedir_vcomponent_get_geopos ()

    void                mimedir_vcomponent_get_geopos       (MIMEDirVComponent *vcomponent,
                                                             gdouble *latitude,
                                                             gdouble *longitude);

Sets `latitude` and `longitude` to the component's geographical position.

`vcomponent` : | a MIMEDirVComponent object
`latitude` : | pointer to a gdouble value or `NULL`
`longitude` : | pointer to a gdouble value or `NULL`

### mimedir_vcomponent_set_recurrence ()

    void                mimedir_vcomponent_set_recurrence   (MIMEDirVComponent *vcomponent,
                                                             MIMEDirRecurrence *recurrence);

Sets the recurrence information for `vcomponent`. If `recurrence` is `NULL`, this component does not recur.

`vcomponent` : | a MIMEDirVComponent object
`recurrence` : | a MIMEDirRecurrence object or `NULL`

### mimedir_vcomponent_get_recurrence ()

    MIMEDirRecurrence*  mimedir_vcomponent_get_recurrence   (MIMEDirVComponent *vcomponent);

Returns the recurrence object associated with this component or `NULL` if there is no recurrence object.

`vcomponent` : | a MIMEDirVComponent object
Returns : | a MIMEDirRecurrence object or `NULL`

### mimedir_vcomponent_set_allday ()

    void                mimedir_vcomponent_set_allday       (MIMEDirVComponent *vcomponent,
                                                             gboolean allday);

Set the allday flag to `allday`.

`vcomponent` : | a MIMEDirVComponent object
`allday` : | `TRUE` or `FALSE`

### mimedir_vcomponent_get_allday ()

    gboolean            mimedir_vcomponent_get_allday       (MIMEDirVComponent *vcomponent);

Return `TRUE` if the event lasts a whole day, `FALSE` otherwise.

`vcomponent` : | a MIMEDirVComponent object
Returns : | `TRUE` or `FALSE`

### mimedir_vcomponent_does_recur ()

    gboolean            mimedir_vcomponent_does_recur       (MIMEDirVComponent *vcomponent);

Return `TRUE` if the component has an associated recurrence object.

`vcomponent` : | a MIMEDirVComponent object
Returns : | `TRUE` or `FALSE`

### mimedir_vcomponent_get_next_occurence ()

    MIMEDirDateTime*    mimedir_vcomponent_get_next_occurence
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *after);

Returns the first occurence of this component after or at the date specified by the `after` argument. If `after` is `NULL`, the very first occurence is returned. If there is no occurence after the specified date, `NULL` is returned.

`vcomponent` : | a MIMEDirVComponent object
`after` : | a MIMEDirDateTime object
Returns : | a MIMEDirDateTime object or `NULL`

### mimedir_vcomponent_get_occurences_between ()

    GList*              mimedir_vcomponent_get_occurences_between
                                                            (MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *start,
                                                             MIMEDirDateTime *end);

Return a list of MIMEDirDateTime objects that specify the start and end dates of all occurences of `vcomponent` that overlap with the time interval between `start` and `end`. If `end` is `NULL`, all occurences that intersect with `start` are returned.

Every second element in the list may be `NULL` in which case there is no end time for the occurence.

The returned list should be freed with `mimedir_vcomponent_free_occurences()`.

`vcomponent` : | a MIMEDirVComponent object
`start` : | start time
`end` : | end time, may be `NULL`
Returns : | a GList containing MIMEDirDateTime objects

### mimedir_vcomponent_free_occurences ()

    void                mimedir_vcomponent_free_occurences  (GList *list);

Frees a GList as returned by `mimedir_vcomponent_get_occurences_between()`.

`list` : | a GList as returned by `mimedir_vcomponent_get_occurences_between()`

### mimedir_vcomponent_set_attachment_list ()

    void                mimedir_vcomponent_set_attachment_list
                                                            (MIMEDirVComponent *vcomponent,
                                                             GList *list);

Sets the list of attachments of `vcomponent` to `list`, freeing the old list.

`vcomponent` : | a MIMEDirVComponent object
`list` : | GList of MIMEDirAttachment objects

### mimedir_vcomponent_get_attachment_list ()

    GList*              mimedir_vcomponent_get_attachment_list
                                                            (MIMEDirVComponent *vcomponent);

Returns the list of attachments of `vcomponent`. This list is to be considered read-only and must not be altered in any way.

`vcomponent` : | a MIMEDirVComponent object
Returns : | read-only GList of MIMEDirAttachment objects