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

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.

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.

Flags: Read

Default value: FALSE

Since: 1.4

The `“service”` property

  “service”                  AgService *

The AgService used by the account service.

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