AgManager

## 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,
    } 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_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.