# MIMEDirVAlarm

## Name

MIMEDirVAlarm -- iCalendar alarm object

## Synopsis

    #include <mimedir/mimedir-valarm.h>

    enum                MIMEDirVAlarmType;

                        MIMEDirVAlarm;

    MIMEDirVAlarm*      mimedir_valarm_new                  (MIMEDirVAlarmType type);
    MIMEDirVAlarm*      mimedir_valarm_new_from_profile     (MIMEDirProfile *profile,
                                                             GError **error);
    gboolean            mimedir_valarm_read_from_profile    (MIMEDirVAlarm *valarm,
                                                             MIMEDirProfile *profile,
                                                             GError **error);
    MIMEDirProfile*     mimedir_valarm_write_to_profile     (MIMEDirVAlarm *valarm);
    gchar*              mimedir_valarm_write_to_string      (MIMEDirVAlarm *valarm);
    gboolean            mimedir_valarm_write_to_channel     (MIMEDirVAlarm *valarm,
                                                             GIOChannel *channel,
                                                             GError **error);
    void                mimedir_valarm_set_alarm_type       (MIMEDirVAlarm *valarm,
                                                             MIMEDirVAlarmType type);
    MIMEDirVAlarmType   mimedir_valarm_get_alarm_type       (MIMEDirVAlarm *valarm);
    MIMEDirDateTime*    mimedir_valarm_get_next_occurence   (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *after);
    MIMEDirDateTime*    mimedir_valarm_get_trigger          (MIMEDirVAlarm *valarm,
                                                             MIMEDirDateTime *start,
                                                             MIMEDirDateTime *end);
    MIMEDirDateTime*    mimedir_valarm_get_trigger_from_vcomponent
                                                            (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent);
    gchar*              mimedir_valarm_get_reminder_string  (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent);

## Description

## Details

### enum MIMEDirVAlarmType

    typedef enum {
    	MIMEDIR_VALARM_UNKNOWN,
    	MIMEDIR_VALARM_AUDIO,
    	MIMEDIR_VALARM_DISPLAY,
    	MIMEDIR_VALARM_EMAIL,
    	MIMEDIR_VALARM_PROCEDURE
    } MIMEDirVAlarmType;

### MIMEDirVAlarm

    typedef struct {
    	MIMEDirVComponent parent;

    	MIMEDirVAlarmPriv *priv;
    } MIMEDirVAlarm;

### mimedir_valarm_new ()

    MIMEDirVAlarm*      mimedir_valarm_new                  (MIMEDirVAlarmType type);

Creates a new (empty) vAlarm object.

`type` : | the alarm type
Returns : | a new vAlarm object

### mimedir_valarm_new_from_profile ()

    MIMEDirVAlarm*      mimedir_valarm_new_from_profile     (MIMEDirProfile *profile,
                                                             GError **error);

Create a new vAlarm object and fills it with data retrieved from the supplied profile object. If an error occurs during the read, `error` will be set and `NULL` will be returned.

`profile` : | a MIMEDirProfile object
`error` : | error storage location or `NULL`
Returns : | the new vAlarm object or `NULL`

### mimedir_valarm_read_from_profile ()

    gboolean            mimedir_valarm_read_from_profile    (MIMEDirVAlarm *valarm,
                                                             MIMEDirProfile *profile,
                                                             GError **error);

Clears the supplied vAlarm 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.

`valarm` : | a vAlarm object
`profile` : | a profile object
`error` : | error storage location or `NULL`
Returns : | success indicator

### mimedir_valarm_write_to_profile ()

    MIMEDirProfile*     mimedir_valarm_write_to_profile     (MIMEDirVAlarm *valarm);

Saves the valarm object to a newly allocated profile object.

`valarm` : | a valarm
Returns : | a new profile

### mimedir_valarm_write_to_string ()

    gchar*              mimedir_valarm_write_to_string      (MIMEDirVAlarm *valarm);

Saves the valarm object to a newly allocated memory buffer. You should free the returned buffer with `g_free()`.

`valarm` : | a valarm
Returns : | a newly allocated memory buffer

### mimedir_valarm_write_to_channel ()

    gboolean            mimedir_valarm_write_to_channel     (MIMEDirVAlarm *valarm,
                                                             GIOChannel *channel,
                                                             GError **error);

Saves the valarm object to the supplied I/O channel. If an error occurs during the write, `error` will be set and `FALSE` will be returned. Otherwise, `TRUE` is returned.

`valarm` : | a valarm
`channel` : | I/O channel to save to
`error` : | error storage location or `NULL`
Returns : | success indicator

### mimedir_valarm_set_alarm_type ()

    void                mimedir_valarm_set_alarm_type       (MIMEDirVAlarm *valarm,
                                                             MIMEDirVAlarmType type);

Sets the notification type of the MIMEDirVAlarm object.

`valarm` : | a MIMEDirVAlarm object
`type` : | the new type

### mimedir_valarm_get_alarm_type ()

    MIMEDirVAlarmType   mimedir_valarm_get_alarm_type       (MIMEDirVAlarm *valarm);

Returns the notification type of the MIMEDirVAlarm object.

`valarm` : | a MIMEDirVAlarm object
Returns : | alarm type

### mimedir_valarm_get_next_occurence ()

    MIMEDirDateTime*    mimedir_valarm_get_next_occurence   (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent,
                                                             MIMEDirDateTime *after);

Returns the first occurence of this alarm 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.

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

### mimedir_valarm_get_trigger ()

    MIMEDirDateTime*    mimedir_valarm_get_trigger          (MIMEDirVAlarm *valarm,
                                                             MIMEDirDateTime *start,
                                                             MIMEDirDateTime *end);

Returns a newly allocated MIMEDirDateTime object that relates the trigger time of the vAlarm object, depending on the supplied `start` or `end` clamp times. If `end` is `NULL` it is assumed that `end` equals `start`.

The returned object should be freed with `g_object_unref()`.

`valarm` : | a MIMEDirVAlarm object
`start` : | a MIMEDirDateTime object
`end` : | a MIMEDirDateTime object or `NULL`
Returns : | a new MIMEDirDateTime object

### mimedir_valarm_get_trigger_from_vcomponent ()

    MIMEDirDateTime*    mimedir_valarm_get_trigger_from_vcomponent
                                                            (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent);

Returns a newly allocated MIMEDirDateTime object that relates the trigger time of the vAlarm object, corresponding to the start and end date of `component`.

The returned object should be freed with `g_object_unref()`.

`valarm` : | a MIMEDirVAlarm object
`vcomponent` : | a MIMEDirVComponent object
Returns : | a new MIMEDirDateTime object

### mimedir_valarm_get_reminder_string ()

    gchar*              mimedir_valarm_get_reminder_string  (MIMEDirVAlarm *valarm,
                                                             MIMEDirVComponent *vcomponent);

Return a string that can be presented to the user as reminder for the corresponding appointment or to-do list entry. The returned string should be freed with `g_free()`.

`valarm` : | a MIMEDirVAlarm object
`vcomponent` : | the corresponding MIMEDirVComponent object
Returns : | a reminder string