![]() |
![]() |
![]() |
libaccounts-glib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#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
);
"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
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); }
typedef guint AgAccountId;
ID of an account. Often used when retrieving lists of accounts from AgManager.
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.
|
the AgAccount. |
|
the name of the key whose value has changed. |
|
the user data that was passed when installing this callback. |
struct AgAccountSettingIter { AgAccount *account; };
Iterator for account settings.
AgAccount * |
the AgAccount to iterate over |
void (*AgAccountStoreCb) (AgAccount *account
,const GError *error
,gpointer user_data
);
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.
|
the AgAccount. |
|
a GError, or NULL . |
|
the user data that was passed to ag_account_store() . |
typedef struct _AgAccountWatch *AgAccountWatch;
An opaque struct returned from ag_account_watch_dir()
and
ag_account_watch_key()
.
typedef enum { AG_SETTING_SOURCE_NONE = 0, AG_SETTING_SOURCE_ACCOUNT, AG_SETTING_SOURCE_PROFILE, } AgSettingSource;
The source of a setting on a AgAccount.
void ag_account_delete (AgAccount *account
);
Deletes the account. Call ag_account_store()
in order to record the change
in the storage.
|
the AgAccount. |
const gchar * ag_account_get_display_name (AgAccount *account
);
Get the display name of account
.
|
the AgAccount. |
Returns : |
the display name. |
gboolean ag_account_get_enabled (AgAccount *account
);
Gets whether the selected service is enabled for account
.
AgManager * ag_account_get_manager (AgAccount *account
);
Get the AgManager for account
.
const gchar * ag_account_get_provider_name (AgAccount *account
);
Get the name of the provider of account
.
|
the AgAccount. |
Returns : |
the name of the provider. |
AgService * ag_account_get_selected_service (AgAccount *account
);
Gets the selected AgService for account
.
AgAccountSettingIter * ag_account_get_settings_iter (AgAccount *account
,const gchar *key_prefix
);
Creates a new iterator. This method is useful for language bindings only.
|
the AgAccount. |
|
enumerate only the settings whose key starts with
key_prefix . [allow-none]
|
Returns : |
an AgAccountSettingIter. [transfer full] |
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.
|
the AgAccount. |
|
the name of the setting to retrieve. |
|
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. |
GList * ag_account_list_enabled_services (AgAccount *account
);
Gets a list of services that are enabled for 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]
|
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.
|
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]
|
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
.
|
the AgAccount. |
|
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]
|
void ag_account_remove_watch (AgAccount *account
,AgAccountWatch watch
);
Removes the notification callback identified by watch
.
|
the AgAccount. |
|
the watch to remove. |
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.
void ag_account_set_display_name (AgAccount *account
,const gchar *display_name
);
Changes the display name for account
to display_name
.
|
the AgAccount. |
|
the display name to set. |
void ag_account_set_enabled (AgAccount *account
,gboolean enabled
);
Sets the "enabled" flag on the selected service for account
.
|
the AgAccount. |
|
whether account should be enabled. |
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.
GVariant * ag_account_get_variant (AgAccount *account
,const gchar *key
,AgSettingSource *source
);
Gets the value of the configuration setting key
.
|
the AgAccount. |
|
the name of the setting to retrieve. |
|
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
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.
|
the AgAccount. |
|
the name of the setting to change. |
|
a GVariant holding the new setting's value. [allow-none] |
Since 1.4
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.
|
the AgAccount. |
|
an uninitialized AgAccountSettingIter structure. |
|
enumerate only the settings whose key starts with
key_prefix . [allow-none]
|
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()
.
|
an initialized AgAccountSettingIter structure. |
|
a pointer to a string receiving the key name. [out callee-allocates][transfer none] |
|
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
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()
.
|
an initialized AgAccountSettingIter structure. |
|
a pointer to a string receiving the key name. [out callee-allocates][transfer none] |
|
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. |
void ag_account_settings_iter_free (AgAccountSettingIter *iter
);
Frees the memory associated with an AgAccountSettingIter.
|
a AgAccountSettingIter. |
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.
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.
|
the AgAccount. |
|
function to be called when the settings have been written. [scope async] |
|
pointer to user data, to be passed to callback . |
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.
|
the AgAccount. |
|
optional GCancellable object, NULL to ignore. [allow-none]
|
|
function to be called when the settings have been written. [scope async] |
|
pointer to user data, to be passed to callback . |
Since 1.4
gboolean ag_account_store_finish (AgAccount *account
,GAsyncResult *res
,GError **error
);
Finishes the store operation started by ag_account_store_async()
.
|
the AgAccount. |
|
A GAsyncResult obtained from the GAsyncReadyCallback passed to
ag_account_store_async() . |
|
return location for error, or NULL . |
Returns : |
TRUE on success, FALSE otherwise. |
Since 1.4
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.
gboolean ag_account_supports_service (AgAccount *account
,const gchar *service_type
);
Get whether service_type
is supported on account
.
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
.
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.
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).
|
the AgAccount. |
|
the prefix of the keys to watch. |
|
a AgAccountNotifyCb callback to be called. [scope async] |
|
pointer to user data, to be passed to callback . |
Returns : |
a AgAccountWatch, which can then be used to remove this watch. [transfer none] |
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).
|
the AgAccount. |
|
the name of the key to watch. |
|
a AgAccountNotifyCb callback to be called. [scope async] |
|
pointer to user data, to be passed to callback . |
Returns : |
a AgAccountWatch, which can then be used to remove this watch. [transfer none] |
"display-name"
property"display-name" gchar* : Read
The display name of the account.
Default value: NULL
Since 1.4
"enabled"
property"enabled" gboolean : Read
Whether the account is currently enabled.
Default value: FALSE
Since 1.4
"id"
property"id" guint : Read / Write / Construct Only
The AgAccountId for the account.
Default value: 0
"manager"
property"manager" AgManager* : Read / Write / Construct Only
The AgManager from which the account was instantiated.
Since 1.4
"provider"
property"provider" gchar* : Read / Write / Construct Only
The ID of the provider for the account.
Default value: NULL
Since 1.4
"deleted"
signalvoid user_function (AgAccount *account,
gpointer user_data) : Run Last
Emitted when the account has been deleted.
|
the AgAccount. |
|
user data set when the signal handler was connected. |
"display-name-changed"
signalvoid user_function (AgAccount *account,
gpointer user_data) : Run Last
Emitted when the account display name has changed.
|
the AgAccount. |
|
user data set when the signal handler was connected. |