McAccountManager

## 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.