TpAccountManager

TpAccountManager — proxy object for the Telepathy account manager

Synopsis

#include <telepathy-glib/account-manager.h>

                    TpAccountManager;
                    TpAccountManagerClass;
TpAccountManager *  tp_account_manager_new              (TpDBusDaemon *bus_daemon);
void                tp_account_manager_init_known_interfaces
                                                        (void);
TpAccountManager *  tp_account_manager_dup              (void);
void                tp_account_manager_create_account_async
                                                        (TpAccountManager *manager,
                                                         const gchar *connection_manager,
                                                         const gchar *protocol,
                                                         const gchar *display_name,
                                                         GHashTable *parameters,
                                                         GHashTable *properties,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
TpAccount *         tp_account_manager_create_account_finish
                                                        (TpAccountManager *manager,
                                                         GAsyncResult *result,
                                                         GError **error);
TpAccount *         tp_account_manager_ensure_account   (TpAccountManager *manager,
                                                         const gchar *path);
GList *             tp_account_manager_get_valid_accounts
                                                        (TpAccountManager *manager);
TpConnectionPresenceType  tp_account_manager_get_most_available_presence
                                                        (TpAccountManager *manager,
                                                         gchar **status,
                                                         gchar **message);
void                tp_account_manager_set_all_requested_presences
                                                        (TpAccountManager *manager,
                                                         TpConnectionPresenceType type,
                                                         const gchar *status,
                                                         const gchar *message);
void                tp_account_manager_enable_restart   (TpAccountManager *manager);

#define             TP_ACCOUNT_MANAGER_FEATURE_CORE
gboolean            tp_account_manager_is_prepared      (TpAccountManager *manager,
                                                         GQuark feature);
void                tp_account_manager_prepare_async    (TpAccountManager *manager,
                                                         const GQuark *features,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            tp_account_manager_prepare_finish   (TpAccountManager *manager,
                                                         GAsyncResult *result,
                                                         GError **error);


void                (*tp_cli_account_manager_callback_for_create_account)
                                                        (TpAccountManager *proxy,
                                                         const gchar *out_Account,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_account_manager_call_create_account
                                                        (TpAccountManager *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Connection_Manager,
                                                         const gchar *in_Protocol,
                                                         const gchar *in_Display_Name,
                                                         GHashTable *in_Parameters,
                                                         GHashTable *in_Properties,
                                                         tp_cli_account_manager_callback_for_create_account callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_account_manager_signal_callback_account_removed)
                                                        (TpAccountManager *proxy,
                                                         const gchar *arg_Account,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_account_manager_connect_to_account_removed
                                                        (TpAccountManager *proxy,
                                                         tp_cli_account_manager_signal_callback_account_removed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_account_manager_signal_callback_account_validity_changed)
                                                        (TpAccountManager *proxy,
                                                         const gchar *arg_Account,
                                                         gboolean arg_Valid,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_account_manager_connect_to_account_validity_changed
                                                        (TpAccountManager *proxy,
                                                         tp_cli_account_manager_signal_callback_account_validity_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpAccountManager

Signals

  "account-disabled"                               : Run Last
  "account-enabled"                                : Run Last
  "account-removed"                                : Run Last
  "account-validity-changed"                       : Run Last
  "most-available-presence-changed"                : Run Last

Description

The TpAccountManager object is used to communicate with the Telepathy AccountManager service.

Details

TpAccountManager

typedef struct _TpAccountManager TpAccountManager;

The Telepathy Account Manager stores real-time communication accounts and their configuration, places accounts online on request, and manipulates accounts' presence, nicknames and avatars.

Since 0.7.32

TpAccountManagerClass

typedef struct {
} TpAccountManagerClass;

The class of a TpAccount.

tp_account_manager_new ()

TpAccountManager *  tp_account_manager_new              (TpDBusDaemon *bus_daemon);

Convenience function to create a new account manager proxy. The returned TpAccountManager is not guaranteed to be ready on return.

Use tp_account_manager_dup() instead if you want an account manager proxy on the starter or session bus (which is almost always the right thing for Telepathy).

bus_daemon :

 Proxy for the D-Bus daemon

Returns :

 a new reference to an account manager proxy

tp_account_manager_init_known_interfaces ()

void                tp_account_manager_init_known_interfaces
                                                        (void);

Ensure that the known interfaces for TpAccountManager have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument TP_TYPE_ACCOUNT_MANAGER.

Since 0.7.32

tp_account_manager_dup ()

TpAccountManager *  tp_account_manager_dup              (void);

Returns an account manager proxy on the D-Bus daemon on which this process was activated (if it was launched by D-Bus service activation), or the session bus (otherwise).

The returned TpAccountManager is cached; the same TpAccountManager object will be returned by this function repeatedly, as long as at least one reference exists. Note that the returned TpAccountManager is not guaranteed to be ready on return.

Returns :

 an account manager proxy on the starter or session bus, or NULL if it wasn't possible to get a dbus daemon proxy for the appropriate bus

Since 0.9.0

tp_account_manager_create_account_async ()

void                tp_account_manager_create_account_async
                                                        (TpAccountManager *manager,
                                                         const gchar *connection_manager,
                                                         const gchar *protocol,
                                                         const gchar *display_name,
                                                         GHashTable *parameters,
                                                         GHashTable *properties,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Requests an asynchronous create of an account on the account manager manager. When the operation is finished, callback will be called. You can then call tp_account_manager_create_account_finish() to get the result of the operation.

callback will only be called when the newly created TpAccount has the TP_ACCOUNT_FEATURE_CORE feature ready on it, so when calling tp_account_manager_create_account_finish(), one can guarantee this feature will be ready.

manager :

 a TpAccountManager

connection_manager :

 the name of a connection manager

protocol :

 the name of a protocol

display_name :

 the display name for the account

parameters :

 parameters for the new account

properties :

 properties for the new account

callback :

 a callback to call when the request is satisfied

user_data :

 data to pass to callback

Since 0.9.0

tp_account_manager_create_account_finish ()

TpAccount *         tp_account_manager_create_account_finish
                                                        (TpAccountManager *manager,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async create account operation, and returns a new TpAccount object, with the TP_ACCOUNT_FEATURE_CORE feature ready on it.

manager :

 a TpAccountManager

result :

 a GAsyncResult

error :

 a GError to be filled

Returns :

 a new TpAccount which was just created on success, otherwise NULL

Since 0.9.0

tp_account_manager_ensure_account ()

TpAccount *         tp_account_manager_ensure_account   (TpAccountManager *manager,
                                                         const gchar *path);

Lookup an account in the account manager manager. If the desired account has already been ensured then the same object will be returned, otherwise it will create a new TpAccount and add it to manager. As a result, if manager thinks that the account doesn't exist, this will still add it to manager to avoid races. Note that the returned TpAccount is not guaranteed to be ready on return.

The caller must keep a ref to the returned object using g_object_ref() if it is to be kept.

manager :

 a TpAccountManager

path :

 the object path for an account

Returns :

 a new TpAccount at path

Since 0.9.0

tp_account_manager_get_valid_accounts ()

GList *             tp_account_manager_get_valid_accounts
                                                        (TpAccountManager *manager);

Returns a newly allocated GList of valid accounts in manager. The list must be freed with g_list_free() after used. None of the accounts in the returned list are guaranteed to be ready.

Note that the TpAccounts in the returned GList are not reffed before returning from this function. One could ref every item in the list like the following example: 

1
2
3
 
GList *accounts;
account = tp_account_manager_get_valid_accounts (manager);
g_list_foreach (accounts, (GFunc) g_object_ref, NULL);

The list of valid accounts returned is not guaranteed to have been retrieved until TP_ACCOUNT_MANAGER_FEATURE_CORE is prepared (tp_account_manager_prepare_async() has returned). Until this feature has been prepared, an empty list (NULL) will be returned.

manager :

 a TpAccountManager

Returns :

 a newly allocated GList of valid accounts in manager

Since 0.9.0

tp_account_manager_get_most_available_presence ()

TpConnectionPresenceType  tp_account_manager_get_most_available_presence
                                                        (TpAccountManager *manager,
                                                         gchar **status,
                                                         gchar **message);

Gets the most available presence over all accounts in manager. This function does not average presences across all accounts, but it merely finds the "most available" presence. As a result, there is a guarantee that there exists at least one account in manager with the returned presence.

If no accounts are enabled or valid the output will be (TP_CONNECTION_PRESENCE_TYPE_OFFLINE, "offline", "").

The return value of this function is not guaranteed to have been retrieved until tp_account_manager_prepare_async() has finished; until then, the value will be the same as if no accounts are enabled or valid.

manager :

 a TpAccountManager

status :

 a string to fill with the actual status

message :

 a string to fill with the actual status message

Returns :

 the most available presence across all accounts

Since 0.9.0

tp_account_manager_set_all_requested_presences ()

void                tp_account_manager_set_all_requested_presences
                                                        (TpAccountManager *manager,
                                                         TpConnectionPresenceType type,
                                                         const gchar *status,
                                                         const gchar *message);

Iterates through the accounts in manager and requests the presence (type, status and message). Note that the presence requested here is merely a request, and if might not be satisfiable.

You can find the most available presence across all accounts by calling tp_account_manager_get_most_available_presence().

Setting a requested presence on all accounts will have no effect until tp_account_manager_prepare_async() has finished.

manager :

 a TpAccountManager

type :

 a presence type to request

status :

 a status to request

message :

 a status message to request

Since 0.9.0

tp_account_manager_enable_restart ()

void                tp_account_manager_enable_restart   (TpAccountManager *manager);

Enable autostarting the account manager D-Bus service. This means that the account manager will be restarted if it disappears from the bus.

manager :

 a TpAccountManager

TP_ACCOUNT_MANAGER_FEATURE_CORE

#define             TP_ACCOUNT_MANAGER_FEATURE_CORE

Expands to a call to a function that returns a quark for the "core" feature on a TpAccountManager.

When this feature is prepared, the list of accounts have been retrieved and are available for use, and change-notification has been set up.

One can ask for a feature to be prepared using the tp_account_manager_prepare_async() function, and waiting for it to callback.

Since 0.9.0

tp_account_manager_is_prepared ()

gboolean            tp_account_manager_is_prepared      (TpAccountManager *manager,
                                                         GQuark feature);

manager :

 a TpAccountManager

feature :

 a feature which is required

Returns :

 TRUE if feature is ready on manager, otherwise FALSE

Since 0.9.0

tp_account_manager_prepare_async ()

void                tp_account_manager_prepare_async    (TpAccountManager *manager,
                                                         const GQuark *features,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Requests an asynchronous preparation of manager with the features specified by features. When the operation is finished, callback will be called. You can then call tp_account_manager_prepare_finish() to get the result of the operation.

If features is NULL, then callback will be called when the implied TP_ACCOUNT_MANAGER_FEATURE_CORE feature is ready.

If NULL is given to callback, then no callback will be called when the operation is finished. Instead, it will simply set features on manager. Note that if callback is NULL, then user_data must also be NULL.

manager :

 a TpAccountManager

features :

 a 0-terminated list of features, or NULL

callback :

 a callback to call when the request is satisfied

user_data :

 data to pass to callback

Since 0.9.0

tp_account_manager_prepare_finish ()

gboolean            tp_account_manager_prepare_finish   (TpAccountManager *manager,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an async preparation of the account manager manager.

manager :

 a TpAccountManager

result :

 a GAsyncResult

error :

 a GError to fill

Returns :

 TRUE if the preparation was successful, otherwise FALSE

Since 0.9.0

tp_cli_account_manager_callback_for_create_account ()

void                (*tp_cli_account_manager_callback_for_create_account)
                                                        (TpAccountManager *proxy,
                                                         const gchar *out_Account,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a CreateAccount method call succeeds or fails.

proxy :

 the proxy on which the call was made

out_Account :

 Used to return an 'out' argument if error is NULL: The new <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.

error :

 NULL on success, or an error on failure

user_data :

 user-supplied data

weak_object :

 user-supplied object

tp_cli_account_manager_call_create_account ()

TpProxyPendingCall * tp_cli_account_manager_call_create_account
                                                        (TpAccountManager *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Connection_Manager,
                                                         const gchar *in_Protocol,
                                                         const gchar *in_Display_Name,
                                                         GHashTable *in_Parameters,
                                                         GHashTable *in_Properties,
                                                         tp_cli_account_manager_callback_for_create_account callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a CreateAccount method call.

Request the creation of a new <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The account manager SHOULD NOT allow invalid accounts to be created.

proxy :

 the TpProxy

timeout_ms :

 the timeout in milliseconds, or -1 to use the default

in_Connection_Manager :

 Used to pass an 'in' argument: The name of the connection manager, e.g. &quot;salut&quot;.

in_Protocol :

 Used to pass an 'in' argument: The protocol, e.g. &quot;local-xmpp&quot;.

in_Display_Name :

 Used to pass an 'in' argument: The initial value of the new account's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> property. The account manager SHOULD modify this to make it unique if an Account already exists with the same display name, for instance by appending a number or the 'account' parameter. Account manager implementations SHOULD accept an empty string, but account editing user interfaces should avoid passing an empty string for this parameter. <tp:rationale> <p>The account creation UI may ask the user for a name for the new account. If the author of the UI chooses not to do this, the account creation UI is better able to suggest a default display name because it has protocol-specific knowledge which the account manager does not.</p> <p>The account manager always knows the complete list of accounts so it can easily tell whether it should append something to the display name to avoid presenting two identically-named accounts to the user.</p> </tp:rationale>

in_Parameters :

 Used to pass an 'in' argument: Initial parameter values, as would be passed to <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.

in_Properties :

 Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The values of any other properties to be set immediately on the new Account.</p> <p>Only the properties mentioned in <tp:member-ref>SupportedAccountProperties</tp:member-ref> are acceptable here. In particular, the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> properties are never allowed here, since they are set using the other arguments to this method.</p> <p>Account manager implementations SHOULD support creating accounts with an empty value for this argument.</p>

callback :

 called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

 user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

 called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

 If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

 a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_account_manager_signal_callback_account_removed ()

void                (*tp_cli_account_manager_signal_callback_account_removed)
                                                        (TpAccountManager *proxy,
                                                         const gchar *arg_Account,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal AccountRemoved.

proxy :

 The proxy on which tp_cli_account_manager_connect_to_account_removed() was called

arg_Account :

 An Account, which must not be used any more.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

tp_cli_account_manager_connect_to_account_removed ()

TpProxySignalConnection * tp_cli_account_manager_connect_to_account_removed
                                                        (TpAccountManager *proxy,
                                                         tp_cli_account_manager_signal_callback_account_removed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal AccountRemoved.

The given account has been removed. <tp:rationale> This is effectively change notification for the valid and invalid accounts lists. On emission of this signal, the Account indicated will no longer be present in either of the lists. </tp:rationale>

proxy :

 A TpAccountManager or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_account_manager_signal_callback_account_validity_changed ()

void                (*tp_cli_account_manager_signal_callback_account_validity_changed)
                                                        (TpAccountManager *proxy,
                                                         const gchar *arg_Account,
                                                         gboolean arg_Valid,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal AccountValidityChanged.

proxy :

 The proxy on which tp_cli_account_manager_connect_to_account_validity_changed() was called

arg_Account :

 An <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.

arg_Valid :

 True if the account is now valid.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

tp_cli_account_manager_connect_to_account_validity_changed ()

TpProxySignalConnection * tp_cli_account_manager_connect_to_account_validity_changed
                                                        (TpAccountManager *proxy,
                                                         tp_cli_account_manager_signal_callback_account_validity_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal AccountValidityChanged.

The validity of the given account has changed. New accounts are also indicated by this signal, as an account validity change (usually to True) on an account that did not previously exist. <tp:rationale> This is effectively change notification for the valid and invalid accounts lists. </tp:rationale>

proxy :

 A TpAccountManager or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

Signal Details

The "account-disabled" signal

void                user_function                      (TpAccountManager *manager,
                                                        TpAccount        *account,
                                                        gpointer          user_data)      : Run Last

Emitted when an account from manager is disabled.

manager :

 a TpAccountManager

account :

 a TpAccount

user_data :

 user data set when the signal handler was connected.

Since 0.9.0

The "account-enabled" signal

void                user_function                      (TpAccountManager *manager,
                                                        TpAccount        *account,
                                                        gpointer          user_data)      : Run Last

Emitted when an account from manager is enabled.

Note that the returned TpAccount account is not guaranteed to have any features pre-prepared, including TP_ACCOUNT_FEATURE_CORE.

manager :

 a TpAccountManager

account :

 a TpAccount

user_data :

 user data set when the signal handler was connected.

Since 0.9.0

The "account-removed" signal

void                user_function                      (TpAccountManager *manager,
                                                        TpAccount        *account,
                                                        gpointer          user_data)      : Run Last

Emitted when an account is removed from manager.

manager :

 a TpAccountManager

account :

 a TpAccount

user_data :

 user data set when the signal handler was connected.

Since 0.9.0

The "account-validity-changed" signal

void                user_function                      (TpAccountManager *manager,
                                                        TpAccount        *account,
                                                        gboolean          valid,
                                                        gpointer          user_data)      : Run Last

Emitted when the validity on account changes. account is not guaranteed to be ready when this signal is emitted.

manager :

 a TpAccountManager

account :

 a TpAccount

valid :

 TRUE if the account is now valid

user_data :

 user data set when the signal handler was connected.

Since 0.9.0

The "most-available-presence-changed" signal

void                user_function                      (TpAccountManager *manager,
                                                        guint             presence,
                                                        gchar            *status,
                                                        gchar            *message,
                                                        gpointer          user_data)      : Run Last

Emitted when the most available presence on manager changes.

manager :

 a TpAccountManager

presence :

 new presence type

status :

 new status

message :

 new status message

user_data :

 user data set when the signal handler was connected.

Since 0.9.0

See Also

TpAccount
Generated by GTK-Doc V1.15