AgAccount: libaccounts-glib Reference Manual

## AgAccount

AgAccount — A representation of an account.

## Functions

gboolean | ag_account_supports_service ()
GList * | ag_account_list_services ()
GList * | ag_account_list_services_by_type ()
GList * | ag_account_list_enabled_services ()
AgManager * | ag_account_get_manager ()
const gchar * | ag_account_get_provider_name ()
const gchar * | ag_account_get_display_name ()
void | ag_account_set_display_name ()
void | ag_account_select_service ()
AgService * | ag_account_get_selected_service ()
gboolean | ag_account_get_enabled ()
void | ag_account_set_enabled ()
void | ag_account_delete ()
AgSettingSource | ag_account_get_value ()
void | ag_account_set_value ()
GVariant * | ag_account_get_variant ()
void | ag_account_set_variant ()
void | ag_account_settings_iter_free ()
void | ag_account_settings_iter_init ()
gboolean | ag_account_settings_iter_next ()
gboolean | ag_account_settings_iter_get_next ()
AgAccountSettingIter * | ag_account_get_settings_iter ()
void | (*AgAccountNotifyCb) ()
AgAccountWatch | ag_account_watch_key ()
AgAccountWatch | ag_account_watch_dir ()
void | ag_account_remove_watch ()
void | (*AgAccountStoreCb) ()
void | ag_account_store ()
void | ag_account_store_async ()
gboolean | ag_account_store_finish ()
gboolean | ag_account_store_blocking ()
void | ag_account_sign ()
gboolean | ag_account_verify ()
gboolean | ag_account_verify_with_tokens ()

## Properties

char * | display-name | Read
gboolean | enabled | Read
gboolean | foreign | Write / Construct Only
guint | id | Read / Write / Construct Only
AgManager * | manager | Read / Write / Construct Only
char * | provider | Read / Write / Construct Only

## Signals

void | deleted | Run Last
void | display-name-changed | Run Last
void | enabled | Run Last

## Types and Values

struct | AgAccountClass
enum | AgSettingSource
struct | AgAccountSettingIter
typedef | AgAccountWatch

## Object Hierarchy

        GBoxed
        ╰── AgAccountSettingIter
        GObject
        ╰── AgAccount

## Implemented Interfaces

AgAccount implements GInitable.

## 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);
    }

## Functions

### ag_account_supports_service ()

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

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

#### Parameters

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_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.

#### Parameters

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` .

#### Parameters

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_list_enabled_services ()

    GList *
    ag_account_list_enabled_services (AgAccount *account);

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

#### Parameters

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_get_manager ()

    AgManager *
    ag_account_get_manager (AgAccount *account);

Get the AgManager for `account` .

#### Parameters

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` .

#### Parameters

account | the AgAccount. |

#### Returns

the name of the provider.

### ag_account_get_display_name ()

    const gchar *
    ag_account_get_display_name (AgAccount *account);

Get the display name of `account` .

#### Parameters

account | the AgAccount. |

#### Returns

the display name.

### 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` .

#### Parameters

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

### 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.

#### Parameters

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

### ag_account_get_selected_service ()

    AgService *
    ag_account_get_selected_service (AgAccount *account);

Gets the selected AgService for `account` .

#### Parameters

account | the AgAccount. |

#### Returns

the selected service, or `NULL` if no service is selected.

### ag_account_get_enabled ()

    gboolean
    ag_account_get_enabled (AgAccount *account);

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

#### Parameters

account | the AgAccount. |

#### Returns

`TRUE` if the selected service for `account` is enabled, `FALSE` otherwise.

### ag_account_set_enabled ()

    void
    ag_account_set_enabled (AgAccount *account,
                            gboolean enabled);

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

#### Parameters

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

### 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.

#### Parameters

account | the AgAccount. |

### ag_account_get_value ()

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

`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.

#### Parameters

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_set_value ()

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

`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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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_free ()

    void
    ag_account_settings_iter_free (AgAccountSettingIter *iter);

Frees the memory associated with an AgAccountSettingIter.

#### Parameters

iter | a AgAccountSettingIter. |

### 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.

#### Parameters

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_next ()

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

`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()`.

#### Parameters

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_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()`.

#### Parameters

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_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.

#### Parameters

account | the AgAccount. |
key_prefix | enumerate only the settings whose key starts with `key_prefix` . | [allow-none]

#### Returns

an AgAccountSettingIter.

[transfer full]

### 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.

#### Parameters

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. |

### 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).

#### Parameters

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]

### 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).

#### Parameters

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_remove_watch ()

    void
    ag_account_remove_watch (AgAccount *account,
                             AgAccountWatch watch);

Removes the notification callback identified by `watch` .

#### Parameters

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

### AgAccountStoreCb ()

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

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.

#### Parameters

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

### ag_account_store ()

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

`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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

account | the AgAccount. |
error | pointer to receive the GError, or `NULL`. |

#### Returns

`TRUE` on success, `FALSE` on failure.

### 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.

#### Parameters

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_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` .

#### Parameters

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.

#### Parameters

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.

## Types and Values

### struct AgAccountClass

    struct AgAccountClass {
        GObjectClass parent_class;
        void (*_ag_reserved1) (void);
        void (*_ag_reserved2) (void);
        void (*_ag_reserved3) (void);
        void (*_ag_reserved4) (void);
        void (*_ag_reserved5) (void);
        void (*_ag_reserved6) (void);
        void (*_ag_reserved7) (void);
    };

Use the accessor functions below.

### enum AgSettingSource

The source of a setting on a AgAccount.

#### Members

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 |

### struct AgAccountSettingIter

    struct AgAccountSettingIter {
        AgAccount *account;
    };

Iterator for account settings.

#### Members

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

### AgAccountWatch

    typedef struct _AgAccountWatch *AgAccountWatch;

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

## Property Details

### The `“display-name”` property

      “display-name”             char *

The display name of the account.

Owner: AgAccount

Flags: Read

Default value: NULL

Since: 1.4

### The `“enabled”` property

      “enabled”                  gboolean

Whether the account is currently enabled.

Owner: AgAccount

Flags: Read

Default value: FALSE

Since: 1.4

### The `“foreign”` property

      “foreign”                  gboolean

foreign.

Owner: AgAccount

Flags: Write / Construct Only

Default value: FALSE

### The `“id”` property

      “id”                       guint

The AgAccountId for the account.

Owner: AgAccount

Flags: Read / Write / Construct Only

Default value: 0

### The `“manager”` property

      “manager”                  AgManager *

The AgManager from which the account was instantiated.

Owner: AgAccount

Flags: Read / Write / Construct Only

Since: 1.4

### The `“provider”` property

      “provider”                 char *

The ID of the provider for the account.

Owner: AgAccount

Flags: Read / Write / Construct Only

Default value: NULL

Since: 1.4

## Signal Details

### The `“deleted”` signal

    void
    user_function (AgAccount *account,
                   gpointer   user_data)

Emitted when the account has been deleted.

#### Parameters

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

Flags: Run Last

### The `“display-name-changed”` signal

    void
    user_function (AgAccount *account,
                   gpointer   user_data)

Emitted when the account display name has changed.

#### Parameters

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

Flags: Run Last

### The `“enabled”` signal

    void
    user_function (AgAccount *account,
                   char      *service,
                   gboolean   enabled,
                   gpointer   user_data)

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

#### Parameters

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. |

Flags: Run Last