AgManager: libaccounts-glib Reference Manual

## AgManager AgManager — The account manager object |

## Functions

AgManager * | ag_manager_new ()
AgManager * | ag_manager_new_for_service_type ()
GList * | ag_manager_list ()
GList * | ag_manager_list_by_service_type ()
void | ag_manager_list_free ()
GList * | ag_manager_get_account_services ()
GList * | ag_manager_get_enabled_account_services ()
AgAccount * | ag_manager_get_account ()
AgAccount * | ag_manager_load_account ()
AgAccount * | ag_manager_create_account ()
AgService * | ag_manager_get_service ()
GList * | ag_manager_list_services ()
GList * | ag_manager_list_services_by_type ()
GList * | ag_manager_list_services_by_application ()
GList * | ag_manager_list_enabled ()
GList * | ag_manager_list_enabled_by_service_type ()
const gchar * | ag_manager_get_service_type ()
AgProvider * | ag_manager_get_provider ()
GList * | ag_manager_list_providers ()
void | ag_manager_set_db_timeout ()
guint | ag_manager_get_db_timeout ()
void | ag_manager_set_abort_on_db_timeout ()
gboolean | ag_manager_get_abort_on_db_timeout ()
GList * | ag_manager_list_service_types ()
AgServiceType * | ag_manager_load_service_type ()
AgApplication * | ag_manager_get_application ()
GList * | ag_manager_list_applications_by_service ()

## Properties

gboolean | abort-on-db-timeout | Read / Write
guint | db-timeout | Read / Write
char * | service-type | Read / Write / Construct Only
gboolean | use-dbus | Read / Write / Construct Only

## Signals

void | account-created | Run Last
void | account-deleted | Run Last
void | account-updated | Run Last
void | enabled-event | Run Last

## Types and Values

struct | AgManagerClass

## Object Hierarchy

        GObject
        ╰── AgManager

## Implemented Interfaces

AgManager implements GInitable.

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

## Functions

### 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` .

#### Parameters

service_type | the name of a service type |

#### Returns

an AgManager instance with the specified service type.

### 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.

#### Parameters

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

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

Lists the accounts supporting the given service type.

#### Parameters

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

#### Parameters

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

### 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.

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.

#### Parameters

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_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.

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.

#### Parameters

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

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

Instantiates the object representing the account identified by `account_id` .

#### Parameters

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

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

Instantiates the object representing the account identified by `account_id` .

#### Parameters

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_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.

#### Parameters

manager | the AgManager. |
provider_name | name of the provider of the account. |

#### Returns

a new AgAccount, or `NULL`.

[transfer full]

### ag_manager_get_service ()

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

Loads the service identified by `service_name` .

#### Parameters

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_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.

#### Parameters

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` .

#### Parameters

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

    GList *
    ag_manager_list_services_by_application
                                   (AgManager *manager,
                                    AgApplication *application);

Get the list of services that are supported by `application` .

#### Parameters

manager | the AgManager. |
application | a AgApplication. |

#### Returns

a GList of AgService items representing all the services which are supported. Must be free'd with `ag_service_list_free()`.

[transfer full][element-type AgService]

### ag_manager_list_enabled ()

    GList *
    ag_manager_list_enabled (AgManager *manager);

Lists the enabled accounts.

#### Parameters

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.

#### Parameters

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

    const gchar *
    ag_manager_get_service_type (AgManager *manager);

Get the service type for `manager` .

#### Parameters

manager | the AgManager. |

#### Returns

the name of the service type for the supplied `manager` .

### ag_manager_get_provider ()

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

Loads the provider identified by `provider_name` .

#### Parameters

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

    GList *
    ag_manager_list_providers (AgManager *manager);

Gets a list of all the installed providers.

#### Parameters

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_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.

#### Parameters

manager | the AgManager. |
timeout_ms | the new timeout, in milliseconds. |

### ag_manager_get_db_timeout ()

    guint
    ag_manager_get_db_timeout (AgManager *manager);

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

#### Parameters

manager | the AgManager. |

#### Returns

the timeout (in milliseconds) for database operations.

### 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`.

#### Parameters

manager | the AgManager. |
abort | whether to abort when a DB timeout occurs. |

### 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.

#### Parameters

manager | the AgManager. |

#### Returns

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

### ag_manager_list_service_types ()

    GList *
    ag_manager_list_service_types (AgManager *manager);

Gets a list of all the installed service types.

#### Parameters

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

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

Instantiate the service type with the name `service_type` .

#### Parameters

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_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.

#### Parameters

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

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

Lists the registered applications which support the given service.

#### Parameters

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]

## Types and Values

### struct AgManagerClass

    struct AgManagerClass {
        GObjectClass parent_class;
        void (*account_deleted) (AgManager *manager, AgAccountId id);
        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.

## Property Details

### The `“abort-on-db-timeout”` property

      “abort-on-db-timeout”      gboolean

Whether to abort the application when a database timeout occurs.

Owner: AgManager

Flags: Read / Write

Default value: FALSE

### The `“db-timeout”` property

      “db-timeout”               guint

Timeout for database operations, in milliseconds.

Owner: AgManager

Flags: Read / Write

Default value: 5000

### The `“service-type”` property

      “service-type”             char *

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.

Owner: AgManager

Flags: Read / Write / Construct Only

Default value: NULL

### The `“use-dbus”` property

      “use-dbus”                 gboolean

Whether to use D-Bus for inter-process change notification. Setting this property to `FALSE` causes libaccounts not to emit the change notification signals, and also not react to changes made by other processes. Disabling D-Bus is only meant to be used for specific cases, such as maintenance programs.

Owner: AgManager

Flags: Read / Write / Construct Only

Default value: TRUE

## Signal Details

### The `“account-created”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“account-deleted”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“account-updated”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“enabled-event”` signal

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

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.

#### Parameters

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

Flags: Run Last