GalagoAccount

## GalagoAccount GalagoAccount — An account on a messaging service. |

## Synopsis

                GalagoAccount;
    #define     GALAGO_DBUS_ACCOUNT_INTERFACE
    void        galago_account_set_connected    (GalagoAccount *account,
                                                 gboolean connected);
    GalagoService* galago_account_get_service   (const GalagoAccount *account);
    GalagoPerson* galago_account_get_person     (const GalagoAccount *account);
    const char* galago_account_get_username     (const GalagoAccount *account);
    gboolean    galago_account_is_connected     (const GalagoAccount *account);
    void        galago_account_set_display_name (GalagoAccount *account,
                                                 const char *display_name);
    const char* galago_account_get_display_name (const GalagoAccount *account);
    gboolean    galago_account_is_display_name_set
                                                (const GalagoAccount *account);
    void        galago_account_add_contact      (GalagoAccount *account,
                                                 GalagoAccount *contact);
    void        galago_account_remove_contact   (GalagoAccount *account,
                                                 GalagoAccount *contact);
    GalagoAccount* galago_account_get_contact   (const GalagoAccount *account,
                                                 const char *username,
                                                 gboolean query);
    GList*      galago_account_get_contacts     (const GalagoAccount *account,
                                                 gboolean query);
    GalagoPresence* galago_account_create_presence
                                                (GalagoAccount *account);
    GalagoPresence* galago_account_get_presence (const GalagoAccount *account,
                                                 gboolean query);
    void        galago_account_set_avatar       (GalagoAccount *account,
                                                 GalagoImage *avatar);
    GalagoImage* galago_account_get_avatar      (const GalagoAccount *account,
                                                 gboolean query);

## Object Hierarchy

      GObject
       +----GalagoObject
             +----GalagoAccount

## Properties

      "avatar"               GalagoImage           : Read / Write
      "connected"            gboolean              : Read / Write
      "display-name"         gchararray            : Read / Write
      "person"               GalagoPerson          : Read / Write / Construct Only
      "presence"             GalagoPresence        : Read
      "service"              GalagoService         : Read / Write / Construct Only
      "username"             gchararray            : Read / Write / Construct Only

## Signals

    "avatar-set"
                void        user_function      (GalagoAccount *account,
                                                gpointer       avatar,
                                                gpointer       user_data)      : Run last / Action
    "connection-state-changed"
                void        user_function      (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action
    "contact-added"
                void        user_function      (GalagoAccount *account,
                                                gpointer       contact,
                                                gpointer       user_data)      : Run last / Action
    "contact-removed"
                void        user_function      (GalagoAccount *account,
                                                gpointer       contact,
                                                gpointer       user_data)      : Run last / Action
    "display-name-changed"
                void        user_function      (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action
    "presence-created"
                void        user_function      (GalagoAccount *account,
                                                gpointer       presence,
                                                gpointer       user_data)      : Run last / Action
    "presence-deleted"
                void        user_function      (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action

## Description

The GalagoAccount object represents an account on a messaging or VoIP service, The account may belong to the local user, or someone on the user's contact list.

Each GalagoAccount is owned and managed by a GalagoService, and has an associated GalagoPerson. To create a GalagoAccount, use `galago_service_create_account()`.

## Details

### GalagoAccount

    typedef struct _GalagoAccount GalagoAccount;

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

### GALAGO_DBUS_ACCOUNT_INTERFACE

    #define     GALAGO_DBUS_ACCOUNT_INTERFACE

The D-BUS interface that GalagoAccount maps to.

### galago_account_set_connected ()

    void        galago_account_set_connected    (GalagoAccount *account,
                                                 gboolean connected);

Sets whether or not the account is connected.

`account` : | The account.
`connected` : | The connected state.

### galago_account_get_service ()

    GalagoService* galago_account_get_service   (const GalagoAccount *account);

Returns an account's service.

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

### galago_account_get_person ()

    GalagoPerson* galago_account_get_person     (const GalagoAccount *account);

Returns the person that owns an account.

`account` : | The account.
Returns : | The person that owns the account.

### galago_account_get_username ()

    const char* galago_account_get_username     (const GalagoAccount *account);

Returns an account's username.

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

### galago_account_is_connected ()

    gboolean    galago_account_is_connected     (const GalagoAccount *account);

Returns whether or not an account is connected.

`account` : | The account.
Returns : | The account's connected state.

### galago_account_set_display_name ()

    void        galago_account_set_display_name (GalagoAccount *account,
                                                 const char *display_name);

Sets the account's displayed name.

This is the alias that the account may be shown as on another client. It's purely optional.

`account` : | The account.
`display_name` : | The display name.

### galago_account_get_display_name ()

    const char* galago_account_get_display_name (const GalagoAccount *account);

Returns the account's displayed name. If the displayed name is not explicitly set, this will return the screen name.

`account` : | The account.
Returns : | The displayed name.

### galago_account_is_display_name_set ()

    gboolean    galago_account_is_display_name_set
                                                (const GalagoAccount *account);

Returns whether or not a custom displayed name is set.

`account` : | The account.
Returns : | TRUE if a custom displayed name is set, or FALSE.

### galago_account_add_contact ()

    void        galago_account_add_contact      (GalagoAccount *account,
                                                 GalagoAccount *contact);

Adds a contact to an account.

`account` : | The account.
`contact` : | The contact's account to add.

### galago_account_remove_contact ()

    void        galago_account_remove_contact   (GalagoAccount *account,
                                                 GalagoAccount *contact);

Removes a contact from an account.

`account` : | The account.
`contact` : | The contact's account to remove.

### galago_account_get_contact ()

    GalagoAccount* galago_account_get_contact   (const GalagoAccount *account,
                                                 const char *username,
                                                 gboolean query);

Returns the contact with the specified username in an account.

`account` : | The account.
`username` : | The username.
`query` : | TRUE if a remote query should be done if there is no local contact found, or FALSE.
Returns : | The contact's account, if found, or NULL.

### galago_account_get_contacts ()

    GList*      galago_account_get_contacts     (const GalagoAccount *account,
                                                 gboolean query);

Returns a list of accounts of users seen from this account.

This may emit a contact-added signal for every object that returns. If your code connects to this signal and calls `galago_account_get_contacts()` as a result, you will want to add a lock so that you don't end up with unwanted side-effects.

`account` : | The account.
`query` : | TRUE if a remote query should be done if there is no local contact found, or FALSE.
Returns : | A list of accounts of other users, or NULL.

### galago_account_create_presence ()

    GalagoPresence* galago_account_create_presence
                                                (GalagoAccount *account);

Creates an account's presence.

The account should be a local account. If the account already has a presence, this will return the existing one.

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

### galago_account_get_presence ()

    GalagoPresence* galago_account_get_presence (const GalagoAccount *account,
                                                 gboolean query);

Returns the account's presence.

`account` : | The account.
`query` : | TRUE if a remote query should be done if there is no local presence found, or FALSE.
Returns : | The presence, if found, or NULL.

### galago_account_set_avatar ()

    void        galago_account_set_avatar       (GalagoAccount *account,
                                                 GalagoImage *avatar);

Sets the account's avatar. The account should be a local account.

`account` : | The account.
`avatar` : | The avatar to set.

### galago_account_get_avatar ()

    GalagoImage* galago_account_get_avatar      (const GalagoAccount *account,
                                                 gboolean query);

Returns the account's avatar.

`account` : | The account.
`query` : | TRUE if a remote query should be done if there is no local avatar found, or FALSE.
Returns : | The avatar, if found, or NULL.

## Property Details

### The "`avatar`" property

      "avatar"               GalagoImage           : Read / Write

The account's avatar.

### The "`connected`" property

      "connected"            gboolean              : Read / Write

The account's connected state.

Default value: FALSE

### The "`display-name`" property

      "display-name"         gchararray            : Read / Write

The account's username intended for display.

Default value: NULL

### The "`person`" property

      "person"               GalagoPerson          : Read / Write / Construct Only

The person the account belongs to.

### The "`presence`" property

      "presence"             GalagoPresence        : Read

The account's presence.

### The "`service`" property

      "service"              GalagoService         : Read / Write / Construct Only

The service the account is on.

### The "`username`" property

      "username"             gchararray            : Read / Write / Construct Only

The account's username.

Default value: NULL

## Signal Details

### The "avatar-set" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       avatar,
                                                gpointer       user_data)      : Run last / Action

Emitted whenever an avatar is set for this account.

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

### The "connection-state-changed" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action

Emitted when the state of the connection changes, when the account goes online or offline.

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

### The "contact-added" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       contact,
                                                gpointer       user_data)      : Run last / Action

Emitted whenever a contact has been added to this account.

`account` : | The object which received the signal.
`contact` : | The contact added to this account.
`user_data` : | user data set when the signal handler was connected.

### The "contact-removed" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       contact,
                                                gpointer       user_data)      : Run last / Action

Emitted whenever a contact has been removed from this account.

`account` : | The object which received the signal.
`contact` : | The contact removed from this account.
`user_data` : | user data set when the signal handler was connected.

### The "display-name-changed" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action

Emitted whenever the display name of the account changes.

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

### The "presence-created" signal

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

Emitted whenever a new GalagoPresence object is created for this account.

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

### The "presence-deleted" signal

    void        user_function                  (GalagoAccount *account,
                                                gpointer       user_data)      : Run last / Action

Emitted whenever a GalagoPresence object associated with this account is destroyed.

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