AgAccountService: libaccounts-glib Reference Manual

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

## Functions

AgAccountService * | ag_account_service_new ()
AgAccount * | ag_account_service_get_account ()
AgService * | ag_account_service_get_service ()
gboolean | ag_account_service_get_enabled ()
AgSettingSource | ag_account_service_get_value ()
void | ag_account_service_set_value ()
GVariant * | ag_account_service_get_variant ()
void | ag_account_service_set_variant ()
AgAccountSettingIter * | ag_account_service_get_settings_iter ()
void | ag_account_service_settings_iter_init ()
gboolean | ag_account_service_settings_iter_next ()
AgAuthData * | ag_account_service_get_auth_data ()
gchar ** | ag_account_service_get_changed_fields ()

## Properties

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

## Signals

void | changed | Run Last
void | enabled | Run Last

## Types and Values

struct | AgAccountServiceClass

## Object Hierarchy

        GObject
        ╰── AgAccountService

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    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);
    }

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.

## Functions

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

#### Parameters

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

    AgAccount *
    ag_account_service_get_account (AgAccountService *self);

Get the AgAccount associated with `self` .

#### Parameters

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

    AgService *
    ag_account_service_get_service (AgAccountService *self);

Get the AgService associated with `self` .

#### Parameters

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

#### Parameters

self | the AgAccountService. |

#### Returns

`TRUE` if the service is enabled, `FALSE` otherwise.

### ag_account_service_get_value ()

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

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

#### Parameters

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

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

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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);

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

#### Parameters

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.

#### Parameters

self | the AgAccountService. |

#### Returns

a newly allocated AgAuthData structure.

[transfer full]

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

#### Parameters

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]

## Types and Values

### struct AgAccountServiceClass

    struct AgAccountServiceClass {
        GObjectClass parent_class;
        void (*_ag_reserved1) (void);
        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 `“account”` property

      “account”                  AgAccount *

The AgAccount used by the account service.

Owner: AgAccountService

Flags: Read / Write / Construct Only

Since: 1.4

### The `“enabled”` property

      “enabled”                  gboolean

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.

Owner: AgAccountService

Flags: Read

Default value: FALSE

Since: 1.4

### The `“service”` property

      “service”                  AgService *

The AgService used by the account service.

Owner: AgAccountService

Flags: Read / Write / Construct Only

Since: 1.4

## Signal Details

### The `“changed”` signal

    void
    user_function (AgAccountService *self,
                   gpointer          user_data)

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.

#### Parameters

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

Flags: Run Last

### The `“enabled”` signal

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

Emitted when the service enabled state changes.

#### Parameters

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

Flags: Run Last