![]() |
![]() |
![]() |
libaccounts-glib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#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
);
"account" AgAccount* : Read / Write / Construct Only "enabled" gboolean : Read "service" AgService* : Read / Write / Construct Only
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.
typedef struct _AgAccountService AgAccountService;
Opaque structure. Use related accessor functions.
AgAccount * ag_account_service_get_account (AgAccountService *self
);
Get the AgAccount associated with 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]
|
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.
|
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]
|
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.
|
the AgAccountService. |
Returns : |
TRUE if the service is enabled, FALSE otherwise. |
AgService * ag_account_service_get_service (AgAccountService *self
);
Get the AgService associated with 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]
|
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.
|
the AgAccountService. |
|
enumerate only the settings whose key starts with
key_prefix . [allow-none]
|
Returns : |
an AgAccountSettingIter. [transfer full] |
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.
|
the AgAccountService. |
|
the name of the setting to retrieve. |
|
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. |
AgAccountService * ag_account_service_new (AgAccount *account
,AgService *service
);
Constructor. If service
is NULL
, the returned object will operate on the
global account settings.
|
an AgAccount. [transfer full] |
|
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. |
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.
|
the AgAccountService. |
|
the name of the setting to change. |
|
a GValue holding the new setting's value. [allow-none] |
GVariant * ag_account_service_get_variant (AgAccountService *self
,const gchar *key
,AgSettingSource *source
);
Gets the value of the configuration setting key
.
|
the AgAccountService. |
|
the name of the setting to retrieve. |
|
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
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.
|
the AgAccountService. |
|
the name of the setting to change. |
|
a GVariant holding the new setting's value. [allow-none] |
Since 1.4
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.
|
the AgAccountService. |
|
an uninitialized AgAccountSettingIter structure. |
|
enumerate only the settings whose key starts with
key_prefix . [allow-none]
|
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()
.
|
an initialized AgAccountSettingIter structure. |
|
a pointer to a string receiving the key name. [out callee-allocates][transfer none] |
|
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. |
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.
|
the AgAccountService. |
Returns : |
a newly allocated AgAuthData structure. [transfer full] |
"account"
property"account" AgAccount* : Read / Write / Construct Only
The AgAccount used by the account service.
Since 1.4
"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
"changed"
signalvoid 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.
|
the AgAccountService. |
|
user data set when the signal handler was connected. |
"enabled"
signalvoid user_function (AgAccountService *self,
gboolean enabled,
gpointer user_data) : Run Last
Emitted when the service enabled state changes.
|
the AgAccountService. |
|
whether the service is enabled. |
|
user data set when the signal handler was connected. |