AgAccount

## AgAccount AgAccount — A representation of an account. |

## Synopsis

    #include <libaccounts-glib/ag-account.h>

                        AgAccount;
    typedef             AgAccountId;
    void                (*AgAccountNotifyCb)                (AgAccount *account,
                                                             const gchar *key,
                                                             gpointer user_data);
    struct              AgAccountSettingIter;
    void                (*AgAccountStoreCb)                 (AgAccount *account,
                                                             const GError *error,
                                                             gpointer user_data);
    typedef             AgAccountWatch;
    enum                AgSettingSource;
    void                ag_account_delete                   (AgAccount *account);
    const gchar *       ag_account_get_display_name         (AgAccount *account);
    gboolean            ag_account_get_enabled              (AgAccount *account);
    AgManager *         ag_account_get_manager              (AgAccount *account);
    const gchar *       ag_account_get_provider_name        (AgAccount *account);
    AgService *         ag_account_get_selected_service     (AgAccount *account);
    AgAccountSettingIter * ag_account_get_settings_iter     (AgAccount *account,
                                                             const gchar *key_prefix);
    AgSettingSource     ag_account_get_value                (AgAccount *account,
                                                             const gchar *key,
                                                             GValue *value);
    GList *             ag_account_list_enabled_services    (AgAccount *account);
    GList *             ag_account_list_services            (AgAccount *account);
    GList *             ag_account_list_services_by_type    (AgAccount *account,
                                                             const gchar *service_type);
    void                ag_account_remove_watch             (AgAccount *account,
                                                             AgAccountWatch watch);
    void                ag_account_select_service           (AgAccount *account,
                                                             AgService *service);
    void                ag_account_set_display_name         (AgAccount *account,
                                                             const gchar *display_name);
    void                ag_account_set_enabled              (AgAccount *account,
                                                             gboolean enabled);
    void                ag_account_set_value                (AgAccount *account,
                                                             const gchar *key,
                                                             const GValue *value);
    GVariant *          ag_account_get_variant              (AgAccount *account,
                                                             const gchar *key,
                                                             AgSettingSource *source);
    void                ag_account_set_variant              (AgAccount *account,
                                                             const gchar *key,
                                                             GVariant *value);
    void                ag_account_settings_iter_init       (AgAccount *account,
                                                             AgAccountSettingIter *iter,
                                                             const gchar *key_prefix);
    gboolean            ag_account_settings_iter_get_next   (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             GVariant **value);
    gboolean            ag_account_settings_iter_next       (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             const GValue **value);
    void                ag_account_settings_iter_free       (AgAccountSettingIter *iter);
    void                ag_account_sign                     (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar *token);
    void                ag_account_store                    (AgAccount *account,
                                                             AgAccountStoreCb callback,
                                                             gpointer user_data);
    void                ag_account_store_async              (AgAccount *account,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            ag_account_store_finish             (AgAccount *account,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            ag_account_store_blocking           (AgAccount *account,
                                                             GError **error);
    gboolean            ag_account_supports_service         (AgAccount *account,
                                                             const gchar *service_type);
    gboolean            ag_account_verify                   (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar **token);
    gboolean            ag_account_verify_with_tokens       (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar **tokens);
    AgAccountWatch      ag_account_watch_dir                (AgAccount *account,
                                                             const gchar *key_prefix,
                                                             AgAccountNotifyCb callback,
                                                             gpointer user_data);
    AgAccountWatch      ag_account_watch_key                (AgAccount *account,
                                                             const gchar *key,
                                                             AgAccountNotifyCb callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----AgAccount

      GBoxed
       +----AgAccountSettingIter

## Properties

      "display-name"             gchar*                : Read
      "enabled"                  gboolean              : Read
      "foreign"                  gboolean              : Write / Construct Only
      "id"                       guint                 : Read / Write / Construct Only
      "manager"                  AgManager*            : Read / Write / Construct Only
      "provider"                 gchar*                : Read / Write / Construct Only

## Signals

      "deleted"                                        : Run Last
      "display-name-changed"                           : Run Last
      "enabled"                                        : Run Last

## Description

An AgAccount is an object which represents an account. It provides a method for enabling/disabling the account and methods for editing the account settings.

Accounts are created by AgManager with `ag_manager_create_account()`, and deleted by AgAccount with `ag_account_delete()`. These operations, and any other operations which modify the account settings, must be followed by `ag_account_store()` before the changes are committed to the database.

Example 1. Creating a new AgAccount

    GMainLoop *main_loop = NULL;

    gboolean account_cleanup_idle (gpointer user_data)
    {
        AgManager *manager;
        AgAccount *account = AG_ACCOUNT (user_data);
        manager = ag_account_get_manager (account);

        g_object_unref (account);
        g_object_unref (manager);

        g_main_loop_quit (main_loop);

        return FALSE;
    }

    void account_stored_cb (AgAccount *account,
                            const GError *error,
                            gpointer user_data)
    {
        AgManager *manager = AG_MANAGER (user_data);

        if (error != NULL)
        {
            g_warning ("Account with ID '%u' failed to store, with error: %s",
                       account->id,
                       error->message);
        }
        else
        {
            g_print ("Account stored with ID: %u", account->id);
        }

        /* Clean up in an idle callback. */
        g_idle_add (account_cleanup_idle, account);
        g_main_loop_run (main_loop);
    }

    void store_account (void)
    {
        AgManager *manager;
        GList *providers;
        const gchar *provider_name;
        AgAccount *account;

        main_loop = g_main_loop_new (NULL, FALSE);
        manager = ag_manager_new ();
        providers = ag_manager_list_providers (manager);
        g_assert (providers != NULL);
        provider_name = ag_provider_get_name ((AgProvider *) providers->data);
        account = ag_manager_create_account (manager, provider_name);

        ag_provider_list_free (providers);

        /* The account is not valid until it has been stored. */
        ag_account_store (account, account_stored_cb, (gpointer) manager);
    }

## Details

### AgAccount

    typedef struct _AgAccount AgAccount;

Opaque structure. Use related accessor functions.

### AgAccountId

    typedef guint AgAccountId;

ID of an account. Often used when retrieving lists of accounts from AgManager.

### AgAccountNotifyCb ()

    void                (*AgAccountNotifyCb)                (AgAccount *account,
                                                             const gchar *key,
                                                             gpointer user_data);

This callback is invoked when the value of an account configuration setting changes. If the callback was installed with `ag_account_watch_key()` then `key` is the name of the configuration setting which changed; if it was installed with `ag_account_watch_dir()` then `key` is the same key prefix that was used when installing this callback.

`account` : | the AgAccount.
`key` : | the name of the key whose value has changed.
`user_data` : | the user data that was passed when installing this callback.

### struct AgAccountSettingIter

    struct AgAccountSettingIter {
        AgAccount *account;
    };

Iterator for account settings.

AgAccount *`account`; | the AgAccount to iterate over

### AgAccountStoreCb ()

    void                (*AgAccountStoreCb)                 (AgAccount *account,
                                                             const GError *error,
                                                             gpointer user_data);

### Warning

`AgAccountStoreCb` is deprecated and should not be used in newly-written code.

This callback is invoked when storing the account settings is completed. If `error` is not `NULL`, then some error occurred and the data has most likely not been written.

`account` : | the AgAccount.
`error` : | a GError, or `NULL`.
`user_data` : | the user data that was passed to `ag_account_store()`.

### AgAccountWatch

    typedef struct _AgAccountWatch *AgAccountWatch;

An opaque struct returned from `ag_account_watch_dir()` and `ag_account_watch_key()`.

### enum AgSettingSource

    typedef enum {
        AG_SETTING_SOURCE_NONE = 0,
        AG_SETTING_SOURCE_ACCOUNT,
        AG_SETTING_SOURCE_PROFILE,
    } AgSettingSource;

The source of a setting on a AgAccount.

`AG_SETTING_SOURCE_NONE` | the setting is not present
`AG_SETTING_SOURCE_ACCOUNT` | the setting comes from the current account configuration
`AG_SETTING_SOURCE_PROFILE` | the setting comes from the predefined profile

### ag_account_delete ()

    void                ag_account_delete                   (AgAccount *account);

Deletes the account. Call `ag_account_store()` in order to record the change in the storage.

`account` : | the AgAccount.

### ag_account_get_display_name ()

    const gchar *       ag_account_get_display_name         (AgAccount *account);

Get the display name of `account`.

`account` : | the AgAccount.
Returns : | the display name.

### ag_account_get_enabled ()

    gboolean            ag_account_get_enabled              (AgAccount *account);

Gets whether the selected service is enabled for `account`.

`account` : | the AgAccount.
Returns : | `TRUE` if the selected service for `account` is enabled, `FALSE` otherwise.

### ag_account_get_manager ()

    AgManager *         ag_account_get_manager              (AgAccount *account);

Get the AgManager for `account`.

`account` : | the AgAccount.
Returns : | the AgManager. [transfer none]

### ag_account_get_provider_name ()

    const gchar *       ag_account_get_provider_name        (AgAccount *account);

Get the name of the provider of `account`.

`account` : | the AgAccount.
Returns : | the name of the provider.

### ag_account_get_selected_service ()

    AgService *         ag_account_get_selected_service     (AgAccount *account);

Gets the selected AgService for `account`.

`account` : | the AgAccount.
Returns : | the selected service, or `NULL` if no service is selected.

### ag_account_get_settings_iter ()

    AgAccountSettingIter * ag_account_get_settings_iter     (AgAccount *account,
                                                             const gchar *key_prefix);

Creates a new iterator. This method is useful for language bindings only.

`account` : | the AgAccount.
`key_prefix` : | enumerate only the settings whose key starts with `key_prefix`. [allow-none]
Returns : | an AgAccountSettingIter. [transfer full]

### ag_account_get_value ()

    AgSettingSource     ag_account_get_value                (AgAccount *account,
                                                             const gchar *key,
                                                             GValue *value);

### Warning

`ag_account_get_value` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_get_variant()` instead.

Gets the value of the configuration setting `key`: `value` must be a GValue initialized to the type of the setting.

`account` : | the AgAccount.
`key` : | the name of the setting to retrieve.
`value` : | an initialized GValue to receive the setting's value. [inout]
Returns : | one of AgSettingSource: `AG_SETTING_SOURCE_NONE` if the setting is not present, `AG_SETTING_SOURCE_ACCOUNT` if the setting comes from the account configuration, or `AG_SETTING_SOURCE_PROFILE` if the value comes as predefined in the profile.

### ag_account_list_enabled_services ()

    GList *             ag_account_list_enabled_services    (AgAccount *account);

Gets a list of services that are enabled for `account`.

`account` : | the AgAccount.
Returns : | a GList of AgService items representing all the services which are enabled. Must be free'd with `ag_service_list_free()`. [transfer full][element-type AgService]

### ag_account_list_services ()

    GList *             ag_account_list_services            (AgAccount *account);

Get the list of services for `account`. If the AgManager was created with specified service_type this will return only services with this service_type.

`account` : | the AgAccount.
Returns : | a GList of AgService items representing all the services supported by this account. Must be free'd with `ag_service_list_free()`. [transfer full][element-type AgService]

### ag_account_list_services_by_type ()

    GList *             ag_account_list_services_by_type    (AgAccount *account,
                                                             const gchar *service_type);

Get the list of services supported by `account`, filtered by `service_type`.

`account` : | the AgAccount.
`service_type` : | the service type which all the returned services should provide.
Returns : | a GList of AgService items representing all the services supported by this account which provide `service_type`. Must be free'd with `ag_service_list_free()`. [transfer full][element-type AgService]

### ag_account_remove_watch ()

    void                ag_account_remove_watch             (AgAccount *account,
                                                             AgAccountWatch watch);

Removes the notification callback identified by `watch`.

`account` : | the AgAccount.
`watch` : | the watch to remove.

### ag_account_select_service ()

    void                ag_account_select_service           (AgAccount *account,
                                                             AgService *service);

Selects the configuration of service `service`: from now on, all the subsequent calls on the AgAccount configuration will act on the `service`. If `service` is `NULL`, the global account configuration is selected.

Note that if `account` is being shared with other code one must take special care to make sure the desired service is always selected.

`account` : | the AgAccount.
`service` : | the AgService to select. [allow-none]

### ag_account_set_display_name ()

    void                ag_account_set_display_name         (AgAccount *account,
                                                             const gchar *display_name);

Changes the display name for `account` to `display_name`.

`account` : | the AgAccount.
`display_name` : | the display name to set.

### ag_account_set_enabled ()

    void                ag_account_set_enabled              (AgAccount *account,
                                                             gboolean enabled);

Sets the "enabled" flag on the selected service for `account`.

`account` : | the AgAccount.
`enabled` : | whether `account` should be enabled.

### ag_account_set_value ()

    void                ag_account_set_value                (AgAccount *account,
                                                             const gchar *key,
                                                             const GValue *value);

### Warning

`ag_account_set_value` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_set_variant()` instead.

Sets the value of the configuration setting `key` to the value `value`. If `value` is `NULL`, then the setting is unset.

`account` : | the AgAccount.
`key` : | the name of the setting to change.
`value` : | a GValue holding the new setting's value. [allow-none]

### ag_account_get_variant ()

    GVariant *          ag_account_get_variant              (AgAccount *account,
                                                             const gchar *key,
                                                             AgSettingSource *source);

Gets the value of the configuration setting `key`.

`account` : | the AgAccount.
`key` : | the name of the setting to retrieve.
`source` : | a pointer to an AgSettingSource variable which will tell whether the setting was retrieved from the accounts DB or from a service template. [allow-none][out]
Returns : | a GVariant holding the setting value, or `NULL`. The returned GVariant is owned by the account, and no guarantees are made about its lifetime. If the client wishes to keep it, it should call `g_variant_ref()` on it. [transfer none]

Since 1.4

### ag_account_set_variant ()

    void                ag_account_set_variant              (AgAccount *account,
                                                             const gchar *key,
                                                             GVariant *value);

Sets the value of the configuration setting `key` to the value `value`. If `value` has a floating reference, the `account` will take ownership of it. If `value` is `NULL`, then the setting is unset.

`account` : | the AgAccount.
`key` : | the name of the setting to change.
`value` : | a GVariant holding the new setting's value. [allow-none]

Since 1.4

### ag_account_settings_iter_init ()

    void                ag_account_settings_iter_init       (AgAccount *account,
                                                             AgAccountSettingIter *iter,
                                                             const gchar *key_prefix);

Initializes `iter` to iterate over the account settings. If `key_prefix` is not `NULL`, only keys whose names start with `key_prefix` will be iterated over.

`account` : | the AgAccount.
`iter` : | an uninitialized AgAccountSettingIter structure.
`key_prefix` : | enumerate only the settings whose key starts with `key_prefix`. [allow-none]

### ag_account_settings_iter_get_next ()

    gboolean            ag_account_settings_iter_get_next   (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             GVariant **value);

Iterates over the account keys. `iter` must be an iterator previously initialized with `ag_account_settings_iter_init()`.

`iter` : | an initialized AgAccountSettingIter structure.
`key` : | a pointer to a string receiving the key name. [out callee-allocates][transfer none]
`value` : | a pointer to a pointer to a GVariant, to receive the key value. [out callee-allocates][transfer none]
Returns : | `TRUE` if `key` and `value` have been set, `FALSE` if we there are no more account settings to iterate over.

Since 1.4

### ag_account_settings_iter_next ()

    gboolean            ag_account_settings_iter_next       (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             const GValue **value);

### Warning

`ag_account_settings_iter_next` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_settings_iter_get_next()` instead.

Iterates over the account keys. `iter` must be an iterator previously initialized with `ag_account_settings_iter_init()`.

`iter` : | an initialized AgAccountSettingIter structure.
`key` : | a pointer to a string receiving the key name. [out callee-allocates][transfer none]
`value` : | a pointer to a pointer to a GValue, to receive the key value. [out callee-allocates][transfer none]
Returns : | `TRUE` if `key` and `value` have been set, `FALSE` if we there are no more account settings to iterate over.

### ag_account_settings_iter_free ()

    void                ag_account_settings_iter_free       (AgAccountSettingIter *iter);

Frees the memory associated with an AgAccountSettingIter.

`iter` : | a AgAccountSettingIter.

### ag_account_sign ()

    void                ag_account_sign                     (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar *token);

Creates signature of the `key` with given `token`. The account must be stored prior to calling this function.

`account` : | the AgAccount.
`key` : | the name of the key or prefix of the keys to be signed.
`token` : | a signing token (`NULL`-terminated string) for creating the signature. The application must possess (request) the token.

### ag_account_store ()

    void                ag_account_store                    (AgAccount *account,
                                                             AgAccountStoreCb callback,
                                                             gpointer user_data);

### Warning

`ag_account_store` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_store_async()` instead.

Commit the changed account settings to the account database, and invoke `callback` when the operation has been completed.

`account` : | the AgAccount.
`callback` : | function to be called when the settings have been written. [scope async]
`user_data` : | pointer to user data, to be passed to `callback`.

### ag_account_store_async ()

    void                ag_account_store_async              (AgAccount *account,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Commit the changed account settings to the account database, and invoke `callback` when the operation has been completed.

`account` : | the AgAccount.
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`callback` : | function to be called when the settings have been written. [scope async]
`user_data` : | pointer to user data, to be passed to `callback`.

Since 1.4

### ag_account_store_finish ()

    gboolean            ag_account_store_finish             (AgAccount *account,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes the store operation started by `ag_account_store_async()`.

`account` : | the AgAccount.
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `ag_account_store_async()`.
`error` : | return location for error, or `NULL`.
Returns : | `TRUE` on success, `FALSE` otherwise.

Since 1.4

### ag_account_store_blocking ()

    gboolean            ag_account_store_blocking           (AgAccount *account,
                                                             GError **error);

Commit the changed account settings to the account database, and invoke `callback` when the operation has been completed.

`account` : | the AgAccount.
`error` : | pointer to receive the GError, or `NULL`.
Returns : | `TRUE` on success, `FALSE` on failure.

### ag_account_supports_service ()

    gboolean            ag_account_supports_service         (AgAccount *account,
                                                             const gchar *service_type);

Get whether `service_type` is supported on `account`.

`account` : | the AgAccount.
`service_type` : | the name of the service type to check for
Returns : | `TRUE` if `account` supports the service type `service_type`, `FALSE` otherwise.

### ag_account_verify ()

    gboolean            ag_account_verify                   (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar **token);

Verify if the key is signed and the signature matches the value and provides the aegis token which was used for signing the `key`.

`account` : | the AgAccount.
`key` : | the name of the key or prefix of the keys to be verified.
`token` : | location to receive the pointer to aegis token.
Returns : | `TRUE` if the key is signed and the signature matches the value, `FALSE` otherwise.

### ag_account_verify_with_tokens ()

    gboolean            ag_account_verify_with_tokens       (AgAccount *account,
                                                             const gchar *key,
                                                             const gchar **tokens);

Verify if the `key` is signed with any of the tokens from the `tokens` and the signature is valid.

`account` : | the AgAccount.
`key` : | the name of the key or prefix of the keys to be verified.
`tokens` : | array of aegis tokens.
Returns : | `TRUE` if the key is signed with any of the given tokens and the signature is valid, `FALSE` otherwise.

### ag_account_watch_dir ()

    AgAccountWatch      ag_account_watch_dir                (AgAccount *account,
                                                             const gchar *key_prefix,
                                                             AgAccountNotifyCb callback,
                                                             gpointer user_data);

Installs a watch on all the keys under `key_prefix`: `callback` will be invoked whenever the value of any of these keys changes (or a key is removed).

`account` : | the AgAccount.
`key_prefix` : | the prefix of the keys to watch.
`callback` : | a AgAccountNotifyCb callback to be called. [scope async]
`user_data` : | pointer to user data, to be passed to `callback`.
Returns : | a AgAccountWatch, which can then be used to remove this watch. [transfer none]

### ag_account_watch_key ()

    AgAccountWatch      ag_account_watch_key                (AgAccount *account,
                                                             const gchar *key,
                                                             AgAccountNotifyCb callback,
                                                             gpointer user_data);

Installs a watch on `key`: `callback` will be invoked whenever the value of `key` changes (or the key is removed).

`account` : | the AgAccount.
`key` : | the name of the key to watch.
`callback` : | a AgAccountNotifyCb callback to be called. [scope async]
`user_data` : | pointer to user data, to be passed to `callback`.
Returns : | a AgAccountWatch, which can then be used to remove this watch. [transfer none]

## Property Details

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

      "display-name"             gchar*                : Read

The display name of the account.

Default value: NULL

Since 1.4

### The `"enabled"` property

      "enabled"                  gboolean              : Read

Whether the account is currently enabled.

Default value: FALSE

Since 1.4

### The `"foreign"` property

      "foreign"                  gboolean              : Write / Construct Only

foreign.

Default value: FALSE

### The `"id"` property

      "id"                       guint                 : Read / Write / Construct Only

The AgAccountId for the account.

Default value: 0

### The `"manager"` property

      "manager"                  AgManager*            : Read / Write / Construct Only

The AgManager from which the account was instantiated.

Since 1.4

### The `"provider"` property

      "provider"                 gchar*                : Read / Write / Construct Only

The ID of the provider for the account.

Default value: NULL

Since 1.4

## Signal Details

### The `"deleted"` signal

    void                user_function                      (AgAccount *account,
                                                            gpointer   user_data)      : Run Last

Emitted when the account has been deleted.

`account` : | the AgAccount.
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (AgAccount *account,
                                                            gpointer   user_data)      : Run Last

Emitted when the account display name has changed.

`account` : | the AgAccount.
`user_data` : | user data set when the signal handler was connected.

### The `"enabled"` signal

    void                user_function                      (AgAccount *account,
                                                            gchar     *service,
                                                            gboolean   enabled,
                                                            gpointer   user_data)      : Run Last

Emitted when the account "enabled" status was changed for one of its services, or for the account globally.

`account` : | the AgAccount.
`service` : | the service which was enabled/disabled, or `NULL` if the global enabledness of the account changed.
`enabled` : | the new state of the `account`.
`user_data` : | user data set when the signal handler was connected.