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.
Generated by GTK-Doc V1.18