GDataGDWhen

## GDataGDWhen GDataGDWhen — GData when element |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/gd/gdata-gd-when.h>

                        GDataGDWhen;
                        GDataGDWhenClass;
    GDataGDWhen *       gdata_gd_when_new                   (GTimeVal *start_time,
                                                             GTimeVal *end_time,
                                                             gboolean is_date);
    gint                gdata_gd_when_compare               (const GDataGDWhen *a,
                                                             const GDataGDWhen *b);
    void                gdata_gd_when_get_start_time        (GDataGDWhen *self,
                                                             GTimeVal *start_time);
    void                gdata_gd_when_set_start_time        (GDataGDWhen *self,
                                                             GTimeVal *start_time);
    void                gdata_gd_when_get_end_time          (GDataGDWhen *self,
                                                             GTimeVal *end_time);
    void                gdata_gd_when_set_end_time          (GDataGDWhen *self,
                                                             GTimeVal *end_time);
    gboolean            gdata_gd_when_is_date               (GDataGDWhen *self);
    void                gdata_gd_when_set_is_date           (GDataGDWhen *self,
                                                             gboolean is_date);
    const gchar *       gdata_gd_when_get_value_string      (GDataGDWhen *self);
    void                gdata_gd_when_set_value_string      (GDataGDWhen *self,
                                                             const gchar *value_string);
    GList *             gdata_gd_when_get_reminders         (GDataGDWhen *self);

## Object Hierarchy

      GObject
       +----GDataParsable
             +----GDataGDWhen

## Properties

      "end-time"                 GDataTimeVal*         : Read / Write
      "is-date"                  gboolean              : Read / Write
      "start-time"               GDataTimeVal*         : Read / Write
      "value-string"             gchar*                : Read / Write

## Description

GDataGDWhen represents a "when" element from the GData specification.

## Details

### GDataGDWhen

    typedef struct _GDataGDWhen GDataGDWhen;

All the fields in the GDataGDWhen structure are private and should never be accessed directly.

Since 0.2.0

### GDataGDWhenClass

    typedef struct {
    } GDataGDWhenClass;

All the fields in the GDataGDWhenClass structure are private and should never be accessed directly.

Since 0.4.0

### gdata_gd_when_new ()

    GDataGDWhen *       gdata_gd_when_new                   (GTimeVal *start_time,
                                                             GTimeVal *end_time,
                                                             gboolean is_date);

Creates a new GDataGDWhen. More information is available in the GData specification.

`start_time` : | when the event starts or (for zero-duration events) when it occurs
`end_time` : | when the event ends, or `NULL`. [allow-none]
`is_date` : | `TRUE` if `start_time` and `end_time` specify dates rather than times, `FALSE` otherwise
Returns : | a new GDataGDWhen, or `NULL`; unref with `g_object_unref()`

Since 0.2.0

### gdata_gd_when_compare ()

    gint                gdata_gd_when_compare               (const GDataGDWhen *a,
                                                             const GDataGDWhen *b);

Compares the two times in a `strcmp()` fashion. `NULL` values are handled gracefully, with `0` returned if both `a` and `b` are `NULL`, `-1` if `a` is `NULL` and `1` if `b` is `NULL`.

The comparison of non-`NULL` values is done on the basis of the `start_time`, `end_time` and `is_date` properties of the GDataGDWhens.

`a` : | a GDataGDWhen, or `NULL`
`b` : | another GDataGDWhen, or `NULL`
Returns : | `0` if `a` equals `b`, `-1` or `1` as appropriate otherwise

Since 0.4.0

### gdata_gd_when_get_start_time ()

    void                gdata_gd_when_get_start_time        (GDataGDWhen *self,
                                                             GTimeVal *start_time);

Gets the "start-time" property and returns it in `start_time`.

`self` : | a GDataGDWhen
`start_time` : | return location for the start time. [out caller-allocates]

Since 0.4.0

### gdata_gd_when_set_start_time ()

    void                gdata_gd_when_set_start_time        (GDataGDWhen *self,
                                                             GTimeVal *start_time);

Sets the "start-time" property to `start_time`.

`self` : | a GDataGDWhen
`start_time` : | the new start time

Since 0.4.0

### gdata_gd_when_get_end_time ()

    void                gdata_gd_when_get_end_time          (GDataGDWhen *self,
                                                             GTimeVal *end_time);

Gets the "end-time" property and returns it in `end_time`.

If the end time is unset, both fields of the GTimeVal will be `0`.

`self` : | a GDataGDWhen
`end_time` : | return location for the end time. [out caller-allocates]

Since 0.4.0

### gdata_gd_when_set_end_time ()

    void                gdata_gd_when_set_end_time          (GDataGDWhen *self,
                                                             GTimeVal *end_time);

Sets the "end-time" property to `end_time`.

Set `end_time` to `NULL` to unset the property.

`self` : | a GDataGDWhen
`end_time` : | the new end time, or `NULL`. [allow-none]

Since 0.4.0

### gdata_gd_when_is_date ()

    gboolean            gdata_gd_when_is_date               (GDataGDWhen *self);

Gets the "is-date" property.

`self` : | a GDataGDWhen
Returns : | `TRUE` if "start-time" and "end-time" are dates rather than times, `FALSE` otherwise

Since 0.4.0

### gdata_gd_when_set_is_date ()

    void                gdata_gd_when_set_is_date           (GDataGDWhen *self,
                                                             gboolean is_date);

Sets the "is-date" property to `is_date`.

`self` : | a GDataGDWhen
`is_date` : | `TRUE` if "start-time" and "end-time" should be dates rather than times, `FALSE` otherwise

Since 0.4.0

### gdata_gd_when_get_value_string ()

    const gchar *       gdata_gd_when_get_value_string      (GDataGDWhen *self);

Gets the "value-string" property.

`self` : | a GDataGDWhen
Returns : | the value string, or `NULL`

Since 0.4.0

### gdata_gd_when_set_value_string ()

    void                gdata_gd_when_set_value_string      (GDataGDWhen *self,
                                                             const gchar *value_string);

Sets the "value-string" property to `value_string`.

Set `value_string` to `NULL` to unset the property.

`self` : | a GDataGDWhen
`value_string` : | the new value string, or `NULL`. [allow-none]

Since 0.4.0

### gdata_gd_when_get_reminders ()

    GList *             gdata_gd_when_get_reminders         (GDataGDWhen *self);

Returns a list of the GDataGDReminders which are associated with this GDataGDWhen.

`self` : | a GDataGDWhen
Returns : | a GList of GDataGDReminders, or `NULL`. [element-type GData.GDReminder][transfer none]

Since 0.4.0

## Property Details

### The `"end-time"` property

      "end-time"                 GDataTimeVal*         : Read / Write

The title of a person within the when.

For more information, see the GData specification.

Since 0.4.0

### The `"is-date"` property

      "is-date"                  gboolean              : Read / Write

A programmatic value that identifies the type of when.

For more information, see the GData specification.

Default value: FALSE

Since 0.4.0

### The `"start-time"` property

      "start-time"               GDataTimeVal*         : Read / Write

The name of the when.

For more information, see the GData specification.

Since 0.4.0

### The `"value-string"` property

      "value-string"             gchar*                : Read / Write

A simple string value used to name this when. It allows UIs to display a label such as "Work", "Volunteer", "Professional Society", etc.

For more information, see the GData specification.

Default value: NULL

Since 0.4.0