AgManager

AgManager — The account manager object

Synopsis

#include <libaccounts-glib/ag-manager.h>

                    AgManager;
enum                AgAccountsError;
AgAccount *         ag_manager_create_account           (AgManager *manager,
                                                         const gchar *provider_name);
gboolean            ag_manager_get_abort_on_db_timeout  (AgManager *manager);
AgAccount *         ag_manager_get_account              (AgManager *manager,
                                                         AgAccountId account_id);
GList *             ag_manager_get_account_services     (AgManager *manager);
AgApplication *     ag_manager_get_application          (AgManager *self,
                                                         const gchar *application_name);
guint               ag_manager_get_db_timeout           (AgManager *manager);
GList *             ag_manager_get_enabled_account_services
                                                        (AgManager *manager);
AgProvider *        ag_manager_get_provider             (AgManager *manager,
                                                         const gchar *provider_name);
AgService *         ag_manager_get_service              (AgManager *manager,
                                                         const gchar *service_name);
const gchar *       ag_manager_get_service_type         (AgManager *manager);
GList *             ag_manager_list                     (AgManager *manager);
GList *             ag_manager_list_applications_by_service
                                                        (AgManager *manager,
                                                         AgService *service);
GList *             ag_manager_list_by_service_type     (AgManager *manager,
                                                         const gchar *service_type);
GList *             ag_manager_list_enabled             (AgManager *manager);
GList *             ag_manager_list_enabled_by_service_type
                                                        (AgManager *manager,
                                                         const gchar *service_type);
void                ag_manager_list_free                (GList *list);
GList *             ag_manager_list_providers           (AgManager *manager);
GList *             ag_manager_list_service_types       (AgManager *manager);
GList *             ag_manager_list_services            (AgManager *manager);
GList *             ag_manager_list_services_by_type    (AgManager *manager,
                                                         const gchar *service_type);
AgAccount *         ag_manager_load_account             (AgManager *manager,
                                                         AgAccountId account_id,
                                                         GError **error);
AgServiceType *     ag_manager_load_service_type        (AgManager *manager,
                                                         const gchar *service_type);
AgManager *         ag_manager_new                      (void);
AgManager *         ag_manager_new_for_service_type     (const gchar *service_type);
void                ag_manager_set_abort_on_db_timeout  (AgManager *manager,
                                                         gboolean abort);
void                ag_manager_set_db_timeout           (AgManager *manager,
                                                         guint timeout_ms);

Object Hierarchy

  GObject
   +----AgManager

Properties

  "service-type"             gchar*                : Read / Write / Construct Only

Signals

  "account-created"                                : Run Last
  "account-deleted"                                : Run Last
  "account-updated"                                : Run Last
  "enabled-event"                                  : Run Last

Description

The AgManager is the main object in this library. Use it to create an AgAccount, and to instantiate boxed types such as AgProvider, AgApplication and AgService.

AgManager can be instantiated with a set service type with ag_manager_new_for_service_type(), which restricts some future operations on the manager, such as ag_manager_list() or ag_manager_list_services(), to only affect accounts or services with the set service type.

Lists of objects instantiated by the manager can be freed with the corresponding functions, such as ag_manager_list_free() for the GList of AgAccountId returned from ag_manager_list(), or ag_service_list_free() for the GList of AgService returned from ag_manager_list_services().

Details

AgManager

typedef struct _AgManager AgManager;

Opaque structure. Use related accessor functions.


enum AgAccountsError

typedef enum {
    AG_ACCOUNTS_ERROR_DB = AG_ERROR_DB,
    AG_ACCOUNTS_ERROR_DISPOSED = AG_ERROR_DISPOSED,
    AG_ACCOUNTS_ERROR_DELETED = AG_ERROR_DELETED,
    AG_ACCOUNTS_ERROR_DB_LOCKED = AG_ERROR_DB_LOCKED,
    AG_ACCOUNTS_ERROR_ACCOUNT_NOT_FOUND = AG_ERROR_ACCOUNT_NOT_FOUND,
    AG_ACCOUNTS_ERROR_STORE_IN_PROGRESS,
    AG_ACCOUNTS_ERROR_READONLY,
} AgAccountsError;

These identify the various errors that can occur with methods in libaccounts-glib that return a GError.

AG_ACCOUNTS_ERROR_DB

there was an error accessing the accounts database

AG_ACCOUNTS_ERROR_DISPOSED

the account was in the process of being disposed

AG_ACCOUNTS_ERROR_DELETED

the account was in the process of being deleted

AG_ACCOUNTS_ERROR_DB_LOCKED

the database was locked

AG_ACCOUNTS_ERROR_ACCOUNT_NOT_FOUND

the requested account was not found

AG_ACCOUNTS_ERROR_STORE_IN_PROGRESS

an asynchronous store operation is already in progress. Since 1.4

AG_ACCOUNTS_ERROR_READONLY

the accounts DB is in read-only mode. Since 1.4

ag_manager_create_account ()

AgAccount *         ag_manager_create_account           (AgManager *manager,
                                                         const gchar *provider_name);

Create a new account. The account is not stored in the database until ag_account_store() has successfully returned; the id field in the AgAccount structure is also not meant to be valid until the account has been stored.

manager :

the AgManager.

provider_name :

name of the provider of the account.

Returns :

a new AgAccount, or NULL. [transfer full]

ag_manager_get_abort_on_db_timeout ()

gboolean            ag_manager_get_abort_on_db_timeout  (AgManager *manager);

Get whether the library will abort when a timeout error occurs.

manager :

the AgManager.

Returns :

TRUE is the library will abort when a timeout error occurs, FALSE otherwise.

ag_manager_get_account ()

AgAccount *         ag_manager_get_account              (AgManager *manager,
                                                         AgAccountId account_id);

Instantiates the object representing the account identified by account_id.

manager :

the AgManager.

account_id :

the AgAccountId of the account.

Returns :

an AgAccount, on which the client must call g_object_unref() when it is no longer required, or NULL if an error occurs. [transfer full]

ag_manager_get_account_services ()

GList *             ag_manager_get_account_services     (AgManager *manager);

Gets all the account services. If the manager was created for a specific service type, only services with that type will be returned.

Note

This method causes the loading of all the service settings for all the returned accounts (unless they have been loaded previously). If you are interested in a specific account/service, consider using ag_manager_load_account() to first load the the account, and then create the AgAccountService for that account only.

manager :

the AgManager.

Returns :

a list of AgAccountService objects. When done with it, call g_object_unref() on the list elements, and g_list_free() on the container. [transfer full][element-type AgAccountService]

ag_manager_get_application ()

AgApplication *     ag_manager_get_application          (AgManager *self,
                                                         const gchar *application_name);

Search for application_name in the list of applications, and return a new AgApplication if a matching application was found.

self :

an AgManager

application_name :

the name of an application to search for

Returns :

a new AgApplication if one was found, NULL otherwise

ag_manager_get_db_timeout ()

guint               ag_manager_get_db_timeout           (AgManager *manager);

Get the timeout of database operations for manager, in milliseconds.

manager :

the AgManager.

Returns :

the timeout (in milliseconds) for database operations.

ag_manager_get_enabled_account_services ()

GList *             ag_manager_get_enabled_account_services
                                                        (AgManager *manager);

Gets all the enabled account services. If the manager was created for a specific service type, only services with that type will be returned.

Note

This method causes the loading of all the service settings for all the returned accounts (unless they have been loaded previously). If you are interested in a specific account/service, consider using ag_manager_load_account() to first load the the account, and then create the AgAccountService for that account only.

manager :

the AgManager.

Returns :

a list of AgAccountService objects. When done with it, call g_object_unref() on the list elements, and g_list_free() on the container. [transfer full][element-type AgAccountService]

ag_manager_get_provider ()

AgProvider *        ag_manager_get_provider             (AgManager *manager,
                                                         const gchar *provider_name);

Loads the provider identified by provider_name.

manager :

the AgManager.

provider_name :

the name of the provider.

Returns :

an AgProvider, which must be free'd with ag_provider_unref() when no longer required.

ag_manager_get_service ()

AgService *         ag_manager_get_service              (AgManager *manager,
                                                         const gchar *service_name);

Loads the service identified by service_name.

manager :

the AgManager.

service_name :

the name of the service.

Returns :

an AgService, which must be free'd with ag_service_unref() when no longer required.

ag_manager_get_service_type ()

const gchar *       ag_manager_get_service_type         (AgManager *manager);

Get the service type for manager.

manager :

the AgManager.

Returns :

the name of the service type for the supplied manager.

ag_manager_list ()

GList *             ag_manager_list                     (AgManager *manager);

Lists the accounts. If the AgManager is created with a specified "service-type", it will return only the accounts supporting this service type.

manager :

the AgManager.

Returns :

a GList of AgAccountId representing the accounts. Must be free'd with ag_manager_list_free() when no longer required. [transfer full][element-type AgAccountId]

ag_manager_list_applications_by_service ()

GList *             ag_manager_list_applications_by_service
                                                        (AgManager *manager,
                                                         AgService *service);

Lists the registered applications which support the given service.

manager :

the AgManager.

service :

the AgService for which we want to get the applications list.

Returns :

a GList of all the applications which have declared support for the given service or for its service type. [transfer full][element-type AgApplication]

ag_manager_list_by_service_type ()

GList *             ag_manager_list_by_service_type     (AgManager *manager,
                                                         const gchar *service_type);

Lists the accounts supporting the given service type.

manager :

the AgManager.

service_type :

the name of the service type to check for.

Returns :

a GList of AgAccountId representing the accounts. Must be free'd with ag_manager_list_free() when no longer required. [transfer full][element-type AgAccountId]

ag_manager_list_enabled ()

GList *             ag_manager_list_enabled             (AgManager *manager);

Lists the enabled accounts.

manager :

the AgManager.

Returns :

a GList of the enabled AgAccountId representing the accounts. Must be free'd with ag_manager_list_free() when no longer required. [transfer full][element-type AgAccountId]

ag_manager_list_enabled_by_service_type ()

GList *             ag_manager_list_enabled_by_service_type
                                                        (AgManager *manager,
                                                         const gchar *service_type);

Lists the enabled accounts supporting the given service type.

manager :

the AgManager.

service_type :

the name of the service type to check for.

Returns :

a GList of the enabled AgAccountId representing the accounts. Must be free'd with ag_manager_list_free() when no longer required. [transfer full][element-type AgAccountId]

ag_manager_list_free ()

void                ag_manager_list_free                (GList *list);

Frees the memory taken by a GList of AgAccountId allocated by AgManager, such as by ag_manager_list(), ag_manager_list_enabled() or ag_manager_list_enabled_by_service_type().

list :

a GList returned from a AgManager method which returns account IDs. [element-type AgAccountId]

ag_manager_list_providers ()

GList *             ag_manager_list_providers           (AgManager *manager);

Gets a list of all the installed providers.

manager :

the AgManager.

Returns :

a list of AgProvider, which must be then free'd with ag_provider_list_free(). [transfer full][element-type AgProvider]

ag_manager_list_service_types ()

GList *             ag_manager_list_service_types       (AgManager *manager);

Gets a list of all the installed service types.

manager :

the AgManager.

Returns :

a list of AgServiceType, which must be free'd with ag_service_type_list_free() when no longer required. [transfer full][element-type AgServiceType]

ag_manager_list_services ()

GList *             ag_manager_list_services            (AgManager *manager);

Gets a list of all the installed services. If the AgManager was created with a specified "service_type" it will return only the installed services supporting that service type.

manager :

the AgManager.

Returns :

a list of AgService, which must be free'd with ag_service_list_free() when no longer required. [transfer full][element-type AgService]

ag_manager_list_services_by_type ()

GList *             ag_manager_list_services_by_type    (AgManager *manager,
                                                         const gchar *service_type);

Gets a list of all the installed services where the service type name is service_type.

manager :

the AgManager.

service_type :

the type of the service.

Returns :

a list of AgService, which must be free'd with ag_service_list_free() when no longer required. [transfer full][element-type AgService]

ag_manager_load_account ()

AgAccount *         ag_manager_load_account             (AgManager *manager,
                                                         AgAccountId account_id,
                                                         GError **error);

Instantiates the object representing the account identified by account_id.

manager :

the AgManager.

account_id :

the AgAccountId of the account.

error :

pointer to a GError, or NULL.

Returns :

an AgAccount, on which the client must call g_object_unref() when it is no longer required, or NULL if an error occurs. [transfer full]

ag_manager_load_service_type ()

AgServiceType *     ag_manager_load_service_type        (AgManager *manager,
                                                         const gchar *service_type);

Instantiate the service type with the name service_type.

manager :

the AgManager.

service_type :

the name of the service type.

Returns :

an AgServiceType, which must be free'd with ag_service_type_unref() when no longer required. [transfer full]

ag_manager_new ()

AgManager *         ag_manager_new                      (void);

Create a new AgManager.

Returns :

an instance of an AgManager.

ag_manager_new_for_service_type ()

AgManager *         ag_manager_new_for_service_type     (const gchar *service_type);

Create a new AgManager with the service type with the name service_type.

service_type :

the name of a service type

Returns :

an AgManager instance with the specified service type.

ag_manager_set_abort_on_db_timeout ()

void                ag_manager_set_abort_on_db_timeout  (AgManager *manager,
                                                         gboolean abort);

Tells libaccounts whether it should make the client application abort when a timeout error occurs. The default is FALSE.

manager :

the AgManager.

abort :

whether to abort when a DB timeout occurs.

ag_manager_set_db_timeout ()

void                ag_manager_set_db_timeout           (AgManager *manager,
                                                         guint timeout_ms);

Sets the timeout for database operations. This tells the library how long it is allowed to block while waiting for a locked DB to become accessible. Higher values mean a higher chance of successful reads, but also mean that the execution might be blocked for a longer time. The default is 5 seconds.

manager :

the AgManager.

timeout_ms :

the new timeout, in milliseconds.

Property Details

The "service-type" property

  "service-type"             gchar*                : Read / Write / Construct Only

If the service type is set, certain operations on the AgManager, such as ag_manager_list() and ag_manager_list_services(), will be restricted to only affect accounts or services with that service type.

Default value: NULL

Signal Details

The "account-created" signal

void                user_function                      (AgManager *manager,
                                                        guint      account_id,
                                                        gpointer   user_data)       : Run Last

Emitted when a new account has been created; note that the account must have been stored in the database: the signal is not emitted just in response to ag_manager_create_account().

manager :

the AgManager.

account_id :

the AgAccountId of the account that has been created.

user_data :

user data set when the signal handler was connected.

The "account-deleted" signal

void                user_function                      (AgManager *manager,
                                                        guint      account_id,
                                                        gpointer   user_data)       : Run Last

Emitted when an account has been deleted. This signal is redundant with "deleted", but it is convenient to provide full change notification with AgManager.

manager :

the AgManager.

account_id :

the AgAccountId of the account that has been deleted.

user_data :

user data set when the signal handler was connected.

The "account-updated" signal

void                user_function                      (AgManager *manager,
                                                        guint      account_id,
                                                        gpointer   user_data)       : Run Last

Emitted when particular service of an account has been updated. This signal is redundant with "deleted", but it is convenient to provide full change notification with AgManager.

manager :

the AgManager.

account_id :

the AgAccountId of the account that has been update.

user_data :

user data set when the signal handler was connected.

The "enabled-event" signal

void                user_function                      (AgManager *manager,
                                                        guint      account_id,
                                                        gpointer   user_data)       : Run Last

If the manager has been created with ag_manager_new_for_service_type(), this signal will be emitted when an account (identified by account_id) has been modified in such a way that the application might be interested to start or stop using it: the "enabled" flag on the account or in some service supported by the account and matching the "service-type" have changed. In practice, this signal might be emitted more often than when strictly needed; applications must call ag_account_list_enabled_services() or ag_manager_list_enabled() to get the current state.

manager :

the AgManager.

account_id :

the AgAccountId of the account that has been enabled.

user_data :

user data set when the signal handler was connected.