McAccountManager

McAccountManager — proxy object for the Telepathy AccountManager D-Bus API

Synopsis

                    McAccountManager;
                    McAccountManagerClass;
McAccountManager *  mc_account_manager_new              (TpDBusDaemon *dbus);
void                (*McAccountManagerWhenReadyCb)      (McAccountManager *manager,
                                                         const GError *error,
                                                         gpointer user_data);
void                mc_account_manager_call_when_ready  (McAccountManager *manager,
                                                         McAccountManagerWhenReadyCb callback,
                                                         gpointer user_data);
void                (*McAccountManagerWhenReadyObjectCb)
                                                        (McAccountManager *manager,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                mc_account_manager_call_when_iface_ready
                                                        (McAccountManager *manager,
                                                         GQuark interface,
                                                         McAccountManagerWhenReadyObjectCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                mc_account_manager_call_when_ready_with_accounts
                                                        (McAccountManager *manager,
                                                         McAccountManagerWhenReadyObjectCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         ...);
McAccount *         mc_account_manager_get_account      (McAccountManager *manager,
                                                         const gchar *account_name);
gboolean            (*McAccountFilterFunc)              (McAccount *account,
                                                         gpointer user_data);
GList *             mc_account_manager_list_accounts    (McAccountManager *manager,
                                                         McAccountFilterFunc filter,
                                                         gpointer user_data);


void                (*mc_cli_account_manager_signal_callback_account_removed)
                                                        (TpProxy *proxy,
                                                         const gchar *arg_Account,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * mc_cli_account_manager_connect_to_account_removed
                                                        (gpointer proxy,
                                                         mc_cli_account_manager_signal_callback_account_removed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*mc_cli_account_manager_signal_callback_account_validity_changed)
                                                        (TpProxy *proxy,
                                                         const gchar *arg_Account,
                                                         gboolean arg_Valid,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * mc_cli_account_manager_connect_to_account_validity_changed
                                                        (gpointer proxy,
                                                         mc_cli_account_manager_signal_callback_account_validity_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*mc_cli_account_manager_callback_for_create_account)
                                                        (TpProxy *proxy,
                                                         const gchar *out_Account,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * mc_cli_account_manager_call_create_account
                                                        (gpointer proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Connection_Manager,
                                                         const gchar *in_Protocol,
                                                         const gchar *in_Display_Name,
                                                         GHashTable *in_Parameters,
                                                         GHashTable *in_Properties,
                                                         mc_cli_account_manager_callback_for_create_account callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*mc_cli_account_manager_interface_query_callback_for_find_accounts)
                                                        (TpProxy *proxy,
                                                         const GPtrArray *out_accounts,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxyPendingCall * mc_cli_account_manager_interface_query_call_find_accounts
                                                        (gpointer proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_params,
                                                         mc_cli_account_manager_interface_query_callback_for_find_accounts callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Object Hierarchy

  GObject
   +----TpProxy
         +----McAccountManager

Signals

  "account-created"                                : Run Last
  "account-ready"                                  : Run Last

Description

This module provides a client-side proxy object for the Telepathy AccountManager D-Bus API.

Details

McAccountManager

typedef struct _McAccountManager McAccountManager;

A proxy object for the Telepathy AccountManager D-Bus API. This is a subclass of TpProxy.

McAccountManagerClass

typedef struct _McAccountManagerClass McAccountManagerClass;

The class of a McAccountManager.

mc_account_manager_new ()

McAccountManager *  mc_account_manager_new              (TpDBusDaemon *dbus);

Creates a proxy for the DBus AccountManager Telepathy object.

dbus :

 a D-Bus daemon; may not be NULL

Returns :

 a new McAccountManager object.

McAccountManagerWhenReadyCb ()

void                (*McAccountManagerWhenReadyCb)      (McAccountManager *manager,
                                                         const GError *error,
                                                         gpointer user_data);

manager :

 the McAccountManager.

error :

 NULL if the interface is ready for use, or the error with which it was invalidated if it is now invalid.

user_data :

 the user data that was passed to mc_account_manager_call_when_ready().

mc_account_manager_call_when_ready ()

void                mc_account_manager_call_when_ready  (McAccountManager *manager,
                                                         McAccountManagerWhenReadyCb callback,
                                                         gpointer user_data);

Start retrieving and monitoring the properties of the base interface of manager. If they have already been retrieved, call callback immediately, then return. Otherwise, callback will be called when the properties are ready.

manager :

 the McAccountManager.

callback :

 called when the interface becomes ready or invalidated, whichever happens first.

user_data :

 user data to be passed to callback.

McAccountManagerWhenReadyObjectCb ()

void                (*McAccountManagerWhenReadyObjectCb)
                                                        (McAccountManager *manager,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

manager :

 the McAccountManager.

error :

 NULL if the interface is ready for use, or the error with which it was invalidated if it is now invalid.

user_data :

 the user data that was passed to mc_account_call_when_iface_ready() or mc_account_call_when_all_ready().

weak_object :

 the GObject that was passed to mc_account_call_when_iface_ready() or mc_account_call_when_all_ready().

mc_account_manager_call_when_iface_ready ()

void                mc_account_manager_call_when_iface_ready
                                                        (McAccountManager *manager,
                                                         GQuark interface,
                                                         McAccountManagerWhenReadyObjectCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start retrieving and monitoring the properties of the interface interface of account. If they have already been retrieved, call callback immediately, then return. Otherwise, callback will be called when the properties are ready.

manager :

 the McAccountManager.

interface :

 a GQuark representing the interface to process.

callback :

 called when the interface becomes ready or invalidated, whichever happens first.

user_data :

 user data to be passed to callback.

destroy :

 called with the user_data as argument, after the call has succeeded, failed or been cancelled.

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

mc_account_manager_call_when_ready_with_accounts ()

void                mc_account_manager_call_when_ready_with_accounts
                                                        (McAccountManager *manager,
                                                         McAccountManagerWhenReadyObjectCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         ...);

This is a convenience function that waits for the account manager to be ready, after which it requests the desired interfaces out of all accounts and returns only once they are all ready. After this function has been called, all new accounts that should appear will have their desired interfaces retrieved, and the "account-ready" signal will be emitted.

manager :

 the McAccountManager.

callback :

 called when the account manager and all the accounts are ready, or some error occurs.

user_data :

 user data to be passed to callback.

destroy :

 called with the user_data as argument, after the call has succeeded, failed or been cancelled.

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

... :

 a list of GQuark types representing the account interfaces to process, followed by 0.

mc_account_manager_get_account ()

McAccount *         mc_account_manager_get_account      (McAccountManager *manager,
                                                         const gchar *account_name);

Get the McAccount for the account whose name is account_name. It looks up the accounts from an internal cache, and if the McAccount is not found there it is created, provided that the account_name refers to a proper account.

manager :

 the McAccountManager.

account_name :

 the name of a McAccount, or an object path.

Returns :

 a McAccount, not referenced. NULL if account_name does not match any account.

McAccountFilterFunc ()

gboolean            (*McAccountFilterFunc)              (McAccount *account,
                                                         gpointer user_data);

account :

 a McAccount.

user_data :

 the user data that was passed to mc_account_manager_list_accounts().

Returns :

 TRUE if account must be listed, FALSE otherwise.

mc_account_manager_list_accounts ()

GList *             mc_account_manager_list_accounts    (McAccountManager *manager,
                                                         McAccountFilterFunc filter,
                                                         gpointer user_data);

List all accounts known by the manager. For this function to be really useful, you first need to have waited for mc_account_manager_call_when_ready_with_accounts() to succeed, or it will only return those accounts for which mc_account_manager_get_account() has been called.

manager :

 the McAccountManager.

filter :

 a function for filtering accounts, or NULL.

user_data :

 user data to be supplied to the filtering callback.

Returns :

 a GList of McAccount objects; to be free'd with g_list_free().

mc_cli_account_manager_signal_callback_account_removed ()

void                (*mc_cli_account_manager_signal_callback_account_removed)
                                                        (TpProxy *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 mc_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

mc_cli_account_manager_connect_to_account_removed ()

TpProxySignalConnection * mc_cli_account_manager_connect_to_account_removed
                                                        (gpointer proxy,
                                                         mc_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 TpProxy 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.

mc_cli_account_manager_signal_callback_account_validity_changed ()

void                (*mc_cli_account_manager_signal_callback_account_validity_changed)
                                                        (TpProxy *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 mc_cli_account_manager_connect_to_account_validity_changed() was called

arg_Account :

 An Account.

arg_Valid :

 True if the account is now valid.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

mc_cli_account_manager_connect_to_account_validity_changed ()

TpProxySignalConnection * mc_cli_account_manager_connect_to_account_validity_changed
                                                        (gpointer proxy,
                                                         mc_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 TpProxy 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.

mc_cli_account_manager_callback_for_create_account ()

void                (*mc_cli_account_manager_callback_for_create_account)
                                                        (TpProxy *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

mc_cli_account_manager_call_create_account ()

TpProxyPendingCall * mc_cli_account_manager_call_create_account
                                                        (gpointer proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Connection_Manager,
                                                         const gchar *in_Protocol,
                                                         const gchar *in_Display_Name,
                                                         GHashTable *in_Parameters,
                                                         GHashTable *in_Properties,
                                                         mc_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.

mc_cli_account_manager_interface_query_callback_for_find_accounts ()

void                (*mc_cli_account_manager_interface_query_callback_for_find_accounts)
                                                        (TpProxy *proxy,
                                                         const GPtrArray *out_accounts,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

 the proxy on which the call was made

out_accounts :

 Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The array of account objects.

error :

 NULL on success, or an error on failure

user_data :

 user-supplied data

weak_object :

 user-supplied object

mc_cli_account_manager_interface_query_call_find_accounts ()

TpProxyPendingCall * mc_cli_account_manager_interface_query_call_find_accounts
                                                        (gpointer proxy,
                                                         gint timeout_ms,
                                                         GHashTable *in_params,
                                                         mc_cli_account_manager_interface_query_callback_for_find_accounts callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a FindAccounts method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Find all accounts which match the search query.</p> <p>An empty parameter should return all accounts</p>

proxy :

 the TpProxy

timeout_ms :

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

in_params :

 Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The search query data. The keys can be any Connection Manager parameter (in which case they must be prepended with the string &quot;param-&quot;), any readable Account property (in the form <code>Interface.PropertyName</code>) or any of these special keys:</p> <ul> <li>s: Manager</li> <li>s: Protocol</li> <li>u: RequestedPresence</li> <li>s: RequestedStatus</li> <li>u: CurrentPresence</li> <li>s: CurrentStatus</li> </ul>

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.

Signal Details

The "account-created" signal

void                user_function                      (McAccountManager *account_manager,
                                                        gchar            *object_path,
                                                        gboolean          valid,
                                                        gpointer          user_data)            : Run Last

Emitted when a new account is created.

This signal will be emitted only once mc_account_manager_call_when_ready() has been successfully invoked.

account_manager :

 the McAccountManager.

object_path :

 the path to the DBus Account object.

valid :

 TRUE if this is a valid account.

user_data :

 user data set when the signal handler was connected.

The "account-ready" signal

void                user_function                      (McAccountManager *account_manager,
                                                        McAccount        *account,
                                                        gpointer          user_data)            : Run Last

Emitted when a new account has appeared on the D-Bus and all the requested interfaces (see mc_account_manager_call_when_ready_with_accounts()) have become ready.

Clients should connect to this signal only after mc_account_manager_call_when_ready_with_accounts() has called the callback function.

In the unlikely case that this signal is emitted several times for the same account, clients should ignore all but the first emission.

account_manager :

 the McAccountManager.

account :

 the McAccount that became ready.

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.11