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.