AgAccount

AgAccount — A representation of an account.

Functions

Types and Values

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


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