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

gchar *	display-name	Read
gboolean	enabled	Read
gboolean	foreign	Write / Construct Only
guint	id	Read / Write / Construct Only
AgManager *	manager	Read / Write / Construct Only
gchar *	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”             gchar *

The display name of the account.

Flags: Read

Default value: NULL

Since: 1.4

The `“enabled”` property

  “enabled”                  gboolean

Whether the account is currently enabled.

Flags: Read

Default value: FALSE

Since: 1.4

The `“foreign”` property

  “foreign”                  gboolean

foreign.

Flags: Write / Construct Only

Default value: FALSE

The `“id”` property

  “id”                       guint

The AgAccountId for the account.

Flags: Read / Write / Construct Only

Default value: 0

The `“manager”` property

  “manager”                  AgManager *

The AgManager from which the account was instantiated.

Flags: Read / Write / Construct Only

Since: 1.4

The `“provider”` property

  “provider”                 gchar *

The ID of the provider for the account.

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,
               gchar     *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