AgAccountService

## AgAccountService AgAccountService — Account settings for a specific service |

## Synopsis

    #include <libaccounts-glib/ag-account-service.h>

                        AgAccountService;
    AgAccount *         ag_account_service_get_account      (AgAccountService *self);
    gchar **            ag_account_service_get_changed_fields
                                                            (AgAccountService *self);
    gboolean            ag_account_service_get_enabled      (AgAccountService *self);
    AgService *         ag_account_service_get_service      (AgAccountService *self);
    AgAccountSettingIter * ag_account_service_get_settings_iter
                                                            (AgAccountService *self,
                                                             const gchar *key_prefix);
    AgSettingSource     ag_account_service_get_value        (AgAccountService *self,
                                                             const gchar *key,
                                                             GValue *value);
    AgAccountService *  ag_account_service_new              (AgAccount *account,
                                                             AgService *service);
    void                ag_account_service_set_value        (AgAccountService *self,
                                                             const gchar *key,
                                                             const GValue *value);
    GVariant *          ag_account_service_get_variant      (AgAccountService *self,
                                                             const gchar *key,
                                                             AgSettingSource *source);
    void                ag_account_service_set_variant      (AgAccountService *self,
                                                             const gchar *key,
                                                             GVariant *value);
    void                ag_account_service_settings_iter_init
                                                            (AgAccountService *self,
                                                             AgAccountSettingIter *iter,
                                                             const gchar *key_prefix);
    gboolean            ag_account_service_settings_iter_next
                                                            (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             const GValue **value);
    AgAuthData *        ag_account_service_get_auth_data    (AgAccountService *self);

## Object Hierarchy

      GObject
       +----AgAccountService

## Properties

      "account"                  AgAccount*            : Read / Write / Construct Only
      "enabled"                  gboolean              : Read
      "service"                  AgService*            : Read / Write / Construct Only

## Signals

      "changed"                                        : Run Last
      "enabled"                                        : Run Last

## Description

The AgAccountService object provides access to the account settings for a specific service type. It is meant to be easier to use than the AgAccount class because it hides the complexity of the account structure and gives access to only the limited subset of account settings which are relevant to a service.

To get an AgAccountService one can use the AgManager methods `ag_manager_get_account_services()` or `ag_manager_get_enabled_account_services()`, which both return a GList of account services. Note that if the AgManager was instantiated for a specific service type, these lists will contain only those account services matching that service type. Another way to get an AgAccountService is to instantiate one using `ag_account_service_new()`: this is useful if one already has an AgAccount instance.

This is intended to be a convenient wrapper over the accounts settings specific for a service; as such, it doesn't offer all the editing possibilities offered by the AgAccount class, such as enabling the service itself: these operations should ideally not be performed by consumer applications, but by the account editing UI only.

Example 2. Querying available e-mail services

    AgManager *manager;
    GList *services, *list;

    // Instantiate an account manager interested in e-mail services only.
    manager = ag_manager_new_for_service_type ("e-mail");

    // Get the list of enabled AgAccountService objects of type e-mail.
    services = ag_manager_get_enabled_account_services (manager);

    // Loop through the account services and do something useful with them.
    for (list = services; list != NULL; list = list->next)
    {
        AgAccountService *service = AG_ACCOUNT_SERVICE (list->data);
        GVariant *v_server, *v_port, *v_username;
        gchar *server = NULL, *username = NULL;
        gint port;
        AgAccount *account;

        v_server = ag_account_service_get_variant (service, "pop3/hostname", NULL);
        if (v_server != NULL)
            server = g_variant_dup_string (v_server, NULL);

        v_port = ag_account_service_get_variant (service, "pop3/port", NULL);
        if (v_port != NULL)
            port = g_variant_get_int16 (&v_port);

        // Suppose that the e-mail address is stored in the global account
        // settings; let's get it from there:
        account = ag_account_service_get_account (service);
        ag_account_select_service (NULL);
        v_username = ag_account_get_variant (account, "username", NULL);
        if (v_username != NULL)
            username = g_variant_dup_string (&v_username);

        ...

        g_free (username);
        g_free (server);
    }

### Note

User applications (with the notable exception of the accounts editing application) should never use account services which are not enabled, and should stop using an account when the account service becomes disabled. The latter can be done by connecting to the "changed" signal and checking if `ag_account_service_get_enabled()` still returns `TRUE`. Note that if the account gets deleted, it will always get disabled first; so, there is no need to connect to the "deleted" signal; one can just monitor the "changed" signal.

## Details

### AgAccountService

    typedef struct _AgAccountService AgAccountService;

Opaque structure. Use related accessor functions.

### ag_account_service_get_account ()

    AgAccount *         ag_account_service_get_account      (AgAccountService *self);

Get the AgAccount associated with `self`.

`self` : | the AgAccountService.
Returns : | the underlying AgAccount. The reference count on it is not incremented, so if you need to use it beyond the lifetime of `self`, you need to call `g_object_ref()` on it yourself. [transfer none]

### ag_account_service_get_changed_fields ()

    gchar **            ag_account_service_get_changed_fields
                                                            (AgAccountService *self);

This method should be called only in the context of a handler of the "changed" signal, and can be used to retrieve the set of changes.

`self` : | the AgAccountService.
Returns : | a newly allocated array of strings describing the keys of the fields which have been altered. It must be free'd with `g_strfreev()`. [transfer full]

### ag_account_service_get_enabled ()

    gboolean            ag_account_service_get_enabled      (AgAccountService *self);

Checks whether the underlying AgAccount is enabled and the selected AgService is enabled on it. If this method returns `FALSE`, applications should not try to use this object.

`self` : | the AgAccountService.
Returns : | `TRUE` if the service is enabled, `FALSE` otherwise.

### ag_account_service_get_service ()

    AgService *         ag_account_service_get_service      (AgAccountService *self);

Get the AgService associated with `self`.

`self` : | the AgAccountService.
Returns : | the underlying AgService. The reference count on it is not incremented, so if you need to use it beyond the lifetime of `self`, you need to call `ag_service_ref()` on it yourself. [transfer none]

### ag_account_service_get_settings_iter ()

    AgAccountSettingIter * ag_account_service_get_settings_iter
                                                            (AgAccountService *self,
                                                             const gchar *key_prefix);

Creates a new iterator. This method is useful for language bindings only.

`self` : | the AgAccountService.
`key_prefix` : | enumerate only the settings whose key starts with `key_prefix`. [allow-none]
Returns : | an AgAccountSettingIter. [transfer full]

### ag_account_service_get_value ()

    AgSettingSource     ag_account_service_get_value        (AgAccountService *self,
                                                             const gchar *key,
                                                             GValue *value);

### Warning

`ag_account_service_get_value` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_service_get_variant()` instead.

Gets the value of the configuration setting `key`: `value` must be a GValue initialized to the type of the setting.

`self` : | the AgAccountService.
`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_service_new ()

    AgAccountService *  ag_account_service_new              (AgAccount *account,
                                                             AgService *service);

Constructor. If `service` is `NULL`, the returned object will operate on the global account settings.

`account` : | an AgAccount. [transfer full]
`service` : | an AgService supported by `account`. [transfer full][allow-none]
Returns : | a new AgAccountService; call `g_object_unref()` when you don't need this object anymore.

### ag_account_service_set_value ()

    void                ag_account_service_set_value        (AgAccountService *self,
                                                             const gchar *key,
                                                             const GValue *value);

### Warning

`ag_account_service_set_value` has been deprecated since version 1.4 and should not be used in newly-written code. Use `ag_account_service_set_variant()` instead.

Sets the value of the configuration setting `key` to the value `value`. If `value` is `NULL`, then the setting is unset.

`self` : | the AgAccountService.
`key` : | the name of the setting to change.
`value` : | a GValue holding the new setting's value. [allow-none]

### ag_account_service_get_variant ()

    GVariant *          ag_account_service_get_variant      (AgAccountService *self,
                                                             const gchar *key,
                                                             AgSettingSource *source);

Gets the value of the configuration setting `key`.

`self` : | the AgAccountService.
`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_service_set_variant ()

    void                ag_account_service_set_variant      (AgAccountService *self,
                                                             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.

`self` : | the AgAccountService.
`key` : | the name of the setting to change.
`value` : | a GVariant holding the new setting's value. [allow-none]

Since 1.4

### ag_account_service_settings_iter_init ()

    void                ag_account_service_settings_iter_init
                                                            (AgAccountService *self,
                                                             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. After calling this method, one would typically call `ag_account_settings_iter_get_next()` to read the settings one by one.

`self` : | the AgAccountService.
`iter` : | an uninitialized AgAccountSettingIter structure.
`key_prefix` : | enumerate only the settings whose key starts with `key_prefix`. [allow-none]

### ag_account_service_settings_iter_next ()

    gboolean            ag_account_service_settings_iter_next
                                                            (AgAccountSettingIter *iter,
                                                             const gchar **key,
                                                             const GValue **value);

### Warning

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

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

    AgAuthData *        ag_account_service_get_auth_data    (AgAccountService *self);

Reads the authentication data stored in the account (merging the service-specific settings with the global account settings) and returns an AgAuthData structure. The method and mechanism are read from the "auth/method" and "auth/mechanism" keys, respectively. The authentication parameters are found under the "auth/<method>/<mechanism>/" group.

`self` : | the AgAccountService.
Returns : | a newly allocated AgAuthData structure. [transfer full]

## Property Details

### The `"account"` property

      "account"                  AgAccount*            : Read / Write / Construct Only

The AgAccount used by the account service.

Since 1.4

### The `"enabled"` property

      "enabled"                  gboolean              : Read

Whether the account service is currently enabled. The value of this property is `TRUE` if and only if the underlying AgAccount is enabled and the selected AgService is enabled on it. If this property is `FALSE`, applications should not try to use this object.

Default value: FALSE

Since 1.4

### The `"service"` property

      "service"                  AgService*            : Read / Write / Construct Only

The AgService used by the account service.

Since 1.4

## Signal Details

### The `"changed"` signal

    void                user_function                      (AgAccountService *self,
                                                            gpointer          user_data)      : Run Last

Emitted when some setting has changed on the account service. You can use the `ag_account_service_get_changed_fields()` method to retrieve the list of the settings which have changed.

`self` : | the AgAccountService.
`user_data` : | user data set when the signal handler was connected.

### The `"enabled"` signal

    void                user_function                      (AgAccountService *self,
                                                            gboolean          enabled,
                                                            gpointer          user_data)      : Run Last

Emitted when the service enabled state changes.

`self` : | the AgAccountService.
`enabled` : | whether the service is enabled.
`user_data` : | user data set when the signal handler was connected.