GalagoPresence

## GalagoPresence GalagoPresence — An account's presence. |

## Synopsis

                GalagoPresence;
    #define     GALAGO_DBUS_PRESENCE_INTERFACE
    void        galago_presence_set_idle        (GalagoPresence *presence,
                                                 gboolean idle,
                                                 time_t idle_start_time);
    void        galago_presence_set_statuses    (GalagoPresence *presence,
                                                 GList *statuses);
    void        galago_presence_add_status      (GalagoPresence *presence,
                                                 GalagoStatus *status);
    void        galago_presence_remove_status   (GalagoPresence *presence,
                                                 const char *status_id);
    void        galago_presence_clear_statuses  (GalagoPresence *presence);
    GalagoAccount* galago_presence_get_account  (const GalagoPresence *presence);
    gboolean    galago_presence_is_idle         (const GalagoPresence *presence);
    time_t      galago_presence_get_idle_time   (const GalagoPresence *presence);
    time_t      galago_presence_get_idle_start_time
                                                (const GalagoPresence *presence);
    gboolean    galago_presence_is_discarded    (const GalagoPresence *presence);
    gboolean    galago_presence_is_available    (const GalagoPresence *presence);
    GList*      galago_presence_get_statuses    (const GalagoPresence *presence);
    GalagoStatus* galago_presence_get_active_status
                                                (const GalagoPresence *presence);
    gboolean    galago_presence_is_status_exclusive
                                                (const GalagoPresence *presence,
                                                 const char *status_id);
    GalagoStatus* galago_presence_get_status    (const GalagoPresence *presence,
                                                 const char *status_id);
    gboolean    galago_presence_has_status      (const GalagoPresence *presence,
                                                 const char *status_id);
    gboolean    galago_presence_has_status_type (const GalagoPresence *presence,
                                                 GalagoStatusType type);
    int         galago_presence_compare         (const GalagoPresence *presence1,
                                                 const GalagoPresence *presence2);

## Object Hierarchy

      GObject
       +----GalagoObject
             +----GalagoPresence

## Properties

      "account"              GalagoAccount         : Read / Write / Construct Only

## Signals

    "changed"   void        user_function      (GalagoPresence *presence,
                                                gpointer        user_data)      : Run last / Action
    "idle-changed"
                void        user_function      (GalagoPresence *presence,
                                                gboolean        idle,
                                                gulong          idle_start_time,
                                                gpointer        user_data)            : Run last / Action
    "status-added"
                void        user_function      (GalagoPresence *presence,
                                                gpointer        status,
                                                gpointer        user_data)      : Run last / Action
    "status-removed"
                void        user_function      (GalagoPresence *presence,
                                                gpointer        status,
                                                gpointer        user_data)      : Run last / Action
    "status-updated"
                void        user_function      (GalagoPresence *presence,
                                                gpointer        status,
                                                gchar          *name,
                                                gpointer        user_data)      : Run last / Action

## Description

GalagoPresence contains information on a GalagoAccount's presence, including idle time and a list of statuses.

## Details

### GalagoPresence

    typedef struct _GalagoPresence GalagoPresence;

This is an opaque structure representing a presence. This should not be used directly. Use the accessor functions below.

### GALAGO_DBUS_PRESENCE_INTERFACE

    #define     GALAGO_DBUS_PRESENCE_INTERFACE

The D-BUS interface that GalagoPresence maps to.

### galago_presence_set_idle ()

    void        galago_presence_set_idle        (GalagoPresence *presence,
                                                 gboolean idle,
                                                 time_t idle_start_time);

Sets the idle start time on a presence.

`presence` : | The presence.
`idle` : | `TRUE` if the user is idle, otherwise `FALSE`.
`idle_start_time` : | The idle start time in seconds.

### galago_presence_set_statuses ()

    void        galago_presence_set_statuses    (GalagoPresence *presence,
                                                 GList *statuses);

Sets a list of statuses in a presence.

The presence claims ownership of the list and will free it when destroyed.

`presence` : | The presence.
`statuses` : | The list of statuses.

### galago_presence_add_status ()

    void        galago_presence_add_status      (GalagoPresence *presence,
                                                 GalagoStatus *status);

Adds a single status to a presence.

`presence` : | The presence.
`status` : | The status.

### galago_presence_remove_status ()

    void        galago_presence_remove_status   (GalagoPresence *presence,
                                                 const char *status_id);

Removes a single status from a presence.

The status being removed must not be an exclusive status.

`presence` : | The presence.
`status_id` : | The ID of the status to remove.

### galago_presence_clear_statuses ()

    void        galago_presence_clear_statuses  (GalagoPresence *presence);

Clears all statuses in a presence.

`presence` : | The presence.

### galago_presence_get_account ()

    GalagoAccount* galago_presence_get_account  (const GalagoPresence *presence);

Returns the account from a presence.

`presence` : | The presence.
Returns : | The presence's account.

### galago_presence_is_idle ()

    gboolean    galago_presence_is_idle         (const GalagoPresence *presence);

Returns the idle state from a presence.

`presence` : | The presence.
Returns : | The presence's idle state.

### galago_presence_get_idle_time ()

    time_t      galago_presence_get_idle_time   (const GalagoPresence *presence);

Returns the presence's idle time in seconds.

`presence` : | The presence.
Returns : | The presence's idle time in seconds.

### galago_presence_get_idle_start_time ()

    time_t      galago_presence_get_idle_start_time
                                                (const GalagoPresence *presence);

Returns the time the presence was marked idle.

`presence` : | The presence.
Returns : | The presence's start idle time.

### galago_presence_is_discarded ()

    gboolean    galago_presence_is_discarded    (const GalagoPresence *presence);

Returns whether or not this is a discarded presence.

A discarded presence signifies that all existing presence info for that user is to be discarded.

`presence` : | The presence.
Returns : | `TRUE` if the presence is discarded, or `FALSE`.

### galago_presence_is_available ()

    gboolean    galago_presence_is_available    (const GalagoPresence *presence);

Returns whether or not a presence is considered available.

`presence` : | The presence.
Returns : | `TRUE` if the presence is available, or `FALSE`.

### galago_presence_get_statuses ()

    GList*      galago_presence_get_statuses    (const GalagoPresence *presence);

Returns the list of statuses from a presence.

`presence` : | The presence.
Returns : | The list of statuses.

### galago_presence_get_active_status ()

    GalagoStatus* galago_presence_get_active_status
                                                (const GalagoPresence *presence);

Returns the active exclusive status from a presence.

`presence` : | The presence.
Returns : | The active exclusive status, if set, or NULL.

### galago_presence_is_status_exclusive ()

    gboolean    galago_presence_is_status_exclusive
                                                (const GalagoPresence *presence,
                                                 const char *status_id);

Returns whether or not the status with the specified ID in a presence is exclusive.

`presence` : | The presence.
`status_id` : | The ID of the status.
Returns : | `TRUE` if the status is exclusive, or `FALSE`.

### galago_presence_get_status ()

    GalagoStatus* galago_presence_get_status    (const GalagoPresence *presence,
                                                 const char *status_id);

Returns the status from a presence with the specified ID.

`presence` : | The presence.
`status_id` : | The status ID.
Returns : | The status, if found, or NULL.

### galago_presence_has_status ()

    gboolean    galago_presence_has_status      (const GalagoPresence *presence,
                                                 const char *status_id);

Returns whether or not a presence has a status with the specified ID.

`presence` : | The presence.
`status_id` : | The status ID.
Returns : | `TRUE` if the presence has the status, or `FALSE`.

### galago_presence_has_status_type ()

    gboolean    galago_presence_has_status_type (const GalagoPresence *presence,
                                                 GalagoStatusType type);

Returns whether or not a presence has a status with the specified primitive type.

`presence` : | The presence.
`type` : | The status type.
Returns : | `TRUE` if the presence has the status, or `FALSE`.

### galago_presence_compare ()

    int         galago_presence_compare         (const GalagoPresence *presence1,
                                                 const GalagoPresence *presence2);

Compares two presences for availability.

`presence1` : | The first presence.
`presence2` : | The second presence.
Returns : | -1 if `presence1` is less available than `presence2`, 0 if `presence1` is as available as `presence2`, and 1 if `presence1` is more available than `presence2`.

## Property Details

### The "`account`" property

      "account"              GalagoAccount         : Read / Write / Construct Only

The account that owns this presence.

## Signal Details

### The "changed" signal

    void        user_function                  (GalagoPresence *presence,
                                                gpointer        user_data)      : Run last / Action

Emitted when a property (idle state or a status added or removed) on the presence is updated.

`presence` : | The object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "idle-changed" signal

    void        user_function                  (GalagoPresence *presence,
                                                gboolean        idle,
                                                gulong          idle_start_time,
                                                gpointer        user_data)            : Run last / Action

Emitted whenever the idle state changes. If `idle` is `TRUE`, `idle_start_time` will be a UNIX timestamp indicating when the user went idle. Otherwise, it will be 0.

`presence` : | The object which received the signal.
`idle` : | The idle state.
`idle_start_time` : | The time the user went idle, if `idle` is `TRUE`, or 0.
`user_data` : | user data set when the signal handler was connected.

### The "status-added" signal

    void        user_function                  (GalagoPresence *presence,
                                                gpointer        status,
                                                gpointer        user_data)      : Run last / Action

Emitted whenever a status is added.

`presence` : | The object which received the signal.
`status` : | The status that was added.
`user_data` : | user data set when the signal handler was connected.

### The "status-removed" signal

    void        user_function                  (GalagoPresence *presence,
                                                gpointer        status,
                                                gpointer        user_data)      : Run last / Action

Emitted whenever a status is removed.

`presence` : | The object which received the signal.
`status` : | The status that was removed.
`user_data` : | user data set when the signal handler was connected.

### The "status-updated" signal

    void        user_function                  (GalagoPresence *presence,
                                                gpointer        status,
                                                gchar          *name,
                                                gpointer        user_data)      : Run last / Action

Emitted when an attribute on a status was set or updated.

`presence` : | The object which received the signal.
`status` : | The status that was updated.
`name` : | The name of the attribute updated.
`user_data` : | user data set when the signal handler was connected.