TpAccountManager: telepathy-glib API Reference Manual

## TpAccountManager TpAccountManager — proxy object for the Telepathy account manager |

## Functions

TpAccountManager * | tp_account_manager_new ()
TpAccountManager * | tp_account_manager_new_with_factory ()
void | tp_account_manager_init_known_interfaces ()
void | tp_account_manager_set_default ()
gboolean | tp_account_manager_can_set_default ()
TpAccountManager * | tp_account_manager_dup ()
void | tp_account_manager_create_account_async ()
TpAccount * | tp_account_manager_create_account_finish ()
TpAccount * | tp_account_manager_ensure_account ()
GList * | tp_account_manager_get_valid_accounts ()
GList * | tp_account_manager_dup_valid_accounts ()
TpConnectionPresenceType | tp_account_manager_get_most_available_presence ()
void | tp_account_manager_set_all_requested_presences ()
void | tp_account_manager_enable_restart ()
gboolean | tp_account_manager_is_prepared ()
void | tp_account_manager_prepare_async ()
gboolean | tp_account_manager_prepare_finish ()
void | (*tp_cli_account_manager_callback_for_create_account) ()
TpProxyPendingCall * | tp_cli_account_manager_call_create_account ()
void | (*tp_cli_account_manager_signal_callback_account_removed) ()
TpProxySignalConnection * | tp_cli_account_manager_connect_to_account_removed ()
void | (*tp_cli_account_manager_signal_callback_account_validity_changed) ()
TpProxySignalConnection * | tp_cli_account_manager_connect_to_account_validity_changed ()

## Signals

void | account-disabled | Run Last
void | account-enabled | Run Last
void | account-removed | Run Last
void | account-validity-changed | Run Last
void | most-available-presence-changed | Run Last

## Types and Values

struct | TpAccountManager
struct | TpAccountManagerClass
#define | TP_ACCOUNT_MANAGER_FEATURE_CORE

## Object Hierarchy

        GObject
        ╰── TpProxy
            ╰── TpAccountManager

## Includes

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

## Description

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

A new TpAccountManager object can be created with `tp_account_manager_dup()`.

To list the existing valid accounts, the client should first prepare the `TP_ACCOUNT_MANAGER_FEATURE_CORE` feature using `tp_proxy_prepare_async()`, then call `tp_account_manager_dup_valid_accounts()`.

The “account-validity-changed” signal is emitted to notify of the validity of an account changing. New accounts are also indicated by the emission of this signal on an account that did not previously exist. (The rationale behind indicating new accounts by an account validity change signal is that clients interested in this kind of thing should be connected to this signal anyway: an account having just become valid is effectively a new account to a client.)

The “account-removed” signal is emitted when existing accounts are removed.

## Functions

### 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 prepared on return. Its “factory” will be a new TpAutomaticClientFactory for `bus_daemon` .

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

#### Parameters

bus_daemon | Proxy for the D-Bus daemon |

#### Returns

a new reference to an account manager proxy

### tp_account_manager_new_with_factory ()

    TpAccountManager *
    tp_account_manager_new_with_factory (TpSimpleClientFactory *factory);

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

Should be used only by applications having their own TpSimpleClientFactory subclass. Usually this should be done at application startup and followed by a call to `tp_account_manager_set_default()` to ensure other libraries/plugins will use this custom factory as well.

#### Parameters

factory | a TpSimpleClientFactory |

#### 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_set_default ()

    void
    tp_account_manager_set_default (TpAccountManager *manager);

Define the TpAccountManager singleton that will be returned by `tp_account_manager_dup()`.

This function may only be called before the first call to `tp_account_manager_dup()`, and may not be called more than once. Applications which use a custom TpSimpleClientFactory and want the default TpAccountManager to use that factory should call this after calling `tp_account_manager_new_with_factory()`.

Unlike `tp_account_manager_dup()`, this function will keep an internal reference to `manager` , so it will never be destroyed.

Note that `manager` must use the default TpDBusDaemon as returned by `tp_dbus_daemon_dup()`

#### Parameters

manager | a TpAccountManager |

Since: 0.15.5

### tp_account_manager_can_set_default ()

    gboolean
    tp_account_manager_can_set_default (void);

Check if `tp_account_manager_set_default()` has already successfully been called.

#### Returns

`TRUE` if `tp_account_manager_set_default()` has already successfully been called in this process, `FALSE` otherwise.

Since: 0.19.6

### 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). This account manager will always have the result of `tp_dbus_daemon_dup()` as its “dbus-daemon”.

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.

If `tp_account_manager_set_default()` has been called successfully, that TpAccountManager will be returned. Otherwise, a new TpAccountManager will be created the first time this function is called, using a new TpAutomaticClientFactory as its “factory”.

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

[transfer full]

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.

The TpAccount returned by `tp_account_manager_create_account_finish()` will already have `TP_ACCOUNT_FEATURE_CORE` prepared, along with all features previously passed to `tp_simple_client_factory_add_account_features()` for the account manager's “factory”.

It is usually better to use TpAccountRequest instead, particularly when using high-level language bindings.

#### Parameters

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. | [element-type utf8 GObject.Value][transfer none]
properties | properties for the new account. | [element-type utf8 GObject.Value][transfer none]
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. It has `TP_ACCOUNT_FEATURE_CORE` prepared, along with all features previously passed to `tp_simple_client_factory_add_account_features()` for the account manager's “factory”.

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

#### Parameters

manager | a TpAccountManager |
result | a GAsyncResult |
error | a GError to be filled |

#### Returns

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

[transfer none]

Since: 0.9.0

### tp_account_manager_ensure_account ()

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

`tp_account_manager_ensure_account` is deprecated and should not be used in newly-written code.

New code should call `tp_simple_client_factory_ensure_account()` on this object's “factory” instead, which ensures that a new reference is returned.

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.

The account will be constructed via this account manager's “factory” (so it will be of an appropriate TpAccount subclass if the factory returns one), but does not necessarily have any features prepared yet. Use `tp_proxy_prepare_async()` to prepare features, using the contents of `tp_simple_client_factory_dup_account_features()` as a parameter if you want to prepare the same features that would normally be used.

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

#### Parameters

manager | a TpAccountManager |
path | the object path for an account |

#### Returns

a new TpAccount at `path` , or `NULL` if `path` is not a valid account path.

[transfer none]

Since: 0.9.0

### tp_account_manager_get_valid_accounts ()

    GList *
    tp_account_manager_get_valid_accounts (TpAccountManager *manager);

`tp_account_manager_get_valid_accounts` is deprecated and should not be used in newly-written code.

Since 0.19.9. New code should use `tp_account_manager_dup_valid_accounts()` instead.

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 returned TpAccounts are guaranteed to have `TP_ACCOUNT_FEATURE_CORE` prepared, along with all features previously passed to `tp_simple_client_factory_add_account_features()` for the account manager's “factory”.

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

#### Parameters

manager | a TpAccountManager |

#### Returns

a newly allocated GList of valid accounts in `manager` .

[element-type TelepathyGLib.Account][transfer container]

Since: 0.9.0

### tp_account_manager_dup_valid_accounts ()

    GList *
    tp_account_manager_dup_valid_accounts (TpAccountManager *manager);

Returns a newly allocated GList of reffed valid accounts in `manager` . The list must be freed with `g_list_free_full()` and `g_object_unref()` after used.

The returned TpAccounts are guaranteed to have `TP_ACCOUNT_FEATURE_CORE` prepared, along with all features previously passed to `tp_simple_client_factory_add_account_features()` for the account manager's “factory”.

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

#### Parameters

manager | a TpAccountManager |

#### Returns

a newly allocated GList of reffed valid accounts in `manager` .

[element-type TelepathyGLib.Account][transfer full]

Since: 0.19.9

### 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", "").

Since 0.17.5, if the only connected accounts does not implement `TP_IFACE_CONNECTION_INTERFACE_SIMPLE_PRESENCE`, the output will be (`TP_CONNECTION_PRESENCE_TYPE_AVAILABLE`, "available", "").

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

#### Parameters

manager | a TpAccountManager |
status | a string to fill with the actual status. | [out][transfer full]
message | a string to fill with the actual status message. | [out][transfer full]

#### 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_proxy_prepare_async()` (or the older `tp_account_manager_prepare_async()`) has finished.

#### Parameters

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.

#### Parameters

manager | a TpAccountManager |

### tp_account_manager_is_prepared ()

    gboolean
    tp_account_manager_is_prepared (TpAccountManager *manager,
                                    GQuark feature);

`tp_account_manager_is_prepared` is deprecated and should not be used in newly-written code.

since 0.23.0, use `tp_proxy_is_prepared()` instead.

[skip]

#### Parameters

manager | a TpAccountManager |
feature | a feature which is required |

#### Returns

the same thing as `tp_proxy_is_prepared()`

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);

`tp_account_manager_prepare_async` is deprecated and should not be used in newly-written code.

since 0.15.6, use `tp_proxy_prepare_async()` instead.

Requests an asynchronous preparation of `manager` with `TP_ACCOUNT_MANAGER_FEATURE_CORE`, plus any 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 `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`.

In version 0.11.3 or later, this is equivalent to calling `tp_proxy_prepare_async()` with the same arguments.

[skip]

#### Parameters

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);

`tp_account_manager_prepare_finish` is deprecated and should not be used in newly-written code.

since 0.15.6, use `tp_proxy_prepare_finish()` instead.

Finishes an async preparation of the account manager `manager` .

[skip]

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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>

#### Parameters

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.

#### Parameters

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>

#### Parameters

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.

## Types and Values

### struct TpAccountManager

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

TpAccountManager is the "top level" object. Since 0.16 it always has a non-`NULL` “factory”, and its “factory” will be propagated to all other objects like TpAccountManager -> TpAccount -> TpConnection -> TpContact and TpChannel. This means that desired features set on that factory will be prepared on all those objects. If a “factory” is not specified when the TpAccountManager is constructed, it will use a TpAutomaticClientFactory.

Example 2. TpAccountManager example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    /*
     * contact-list
     *
     * Copyright © 2011 Collabora Ltd. <http://www.collabora.co.uk/>
     *
     * Copying and distribution of this file, with or without modification,
     * are permitted in any medium without royalty provided the copyright
     * notice and this notice are preserved.
     */

    #include "config.h"

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

    static void
    account_manager_prepared_cb (GObject *object,
        GAsyncResult *res,
        gpointer user_data)
    {
      TpAccountManager *manager = (TpAccountManager *) object;
      GMainLoop *loop = user_data;
      GList *accounts, *l;
      GError *error = NULL;

      if (!tp_proxy_prepare_finish (object, res, &error))
        {
          g_print ("Error preparing AM: %s\n", error->message);
          goto OUT;
        }

      accounts = tp_account_manager_dup_valid_accounts (manager);
      for (l = accounts; l != NULL; l = l->next)
        {
          TpAccount *account = l->data;
          TpConnection *connection = tp_account_get_connection (account);
          GPtrArray *contacts;
          guint i;

          /* Verify account is online and received its contact list. If state is not
           * SUCCESS this means we didn't received the roster from server yet and
           * we would have to wait for the "notify:contact-list-state" signal. */
          if (connection == NULL ||
              tp_connection_get_contact_list_state (connection) !=
                  TP_CONTACT_LIST_STATE_SUCCESS)
            continue;

          contacts = tp_connection_dup_contact_list (connection);
          for (i = 0; i < contacts->len; i++)
            {
              TpContact *contact = g_ptr_array_index (contacts, i);
              const gchar * const *groups;

              g_print ("contact %s (%s) in groups:\n",
                  tp_contact_get_identifier (contact),
                  tp_contact_get_alias (contact));

              for (groups = tp_contact_get_contact_groups (contact);
                   *groups != NULL; groups++)
                g_print ("  %s\n", *groups);
            }
          g_ptr_array_unref (contacts);
        }
      g_list_free_full (accounts, g_object_unref);

    OUT:
      g_main_loop_quit (loop);
    }

    int
    main (int argc,
          char **argv)
    {
      TpAccountManager *manager;
      TpSimpleClientFactory *factory;
      GMainLoop *loop;

      tp_debug_set_flags (g_getenv ("EXAMPLE_DEBUG"));

      loop = g_main_loop_new (NULL, FALSE);

      manager = tp_account_manager_dup ();
      factory = tp_proxy_get_factory (manager);
      tp_simple_client_factory_add_account_features_varargs (factory,
          TP_ACCOUNT_FEATURE_CONNECTION,
          0);
      tp_simple_client_factory_add_connection_features_varargs (factory,
          TP_CONNECTION_FEATURE_CONTACT_LIST,
          0);
      tp_simple_client_factory_add_contact_features_varargs (factory,
          TP_CONTACT_FEATURE_ALIAS,
          TP_CONTACT_FEATURE_CONTACT_GROUPS,
          TP_CONTACT_FEATURE_INVALID);

      tp_proxy_prepare_async (manager, NULL, account_manager_prepared_cb, loop);

      g_main_loop_run (loop);

      g_object_unref (manager);
      g_main_loop_unref (loop);

      return 0;
    }

Since: 0.7.32

### struct TpAccountManagerClass

    struct TpAccountManagerClass {
    };

The class of a TpAccount.

### 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. Additionally, since 0.16 the TpAccount objects returned by `tp_account_manager_dup_valid_accounts()` have their features prepared as configured by the “factory”; in particular, they will all have `TP_ACCOUNT_FEATURE_CORE`.

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

Since: 0.9.0

## Signal Details

### The `“account-disabled”` signal

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

Emitted when an account from `manager` is disabled.

#### Parameters

manager | a TpAccountManager |
account | a TpAccount |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.9.0

### The `“account-enabled”` signal

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

Emitted when an account from `manager` is enabled.

`account` is guaranteed to have `TP_ACCOUNT_FEATURE_CORE` prepared, along with all the features previously passed to the “factory”'s `tp_simple_client_factory_add_account_features()`.

#### Parameters

manager | a TpAccountManager |
account | a TpAccount |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.9.0

### The `“account-removed”` signal

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

Emitted when an account is removed from `manager` .

#### Parameters

manager | a TpAccountManager |
account | a TpAccount |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.9.0

### The `“account-validity-changed”` signal

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

Emitted when the validity on `account` changes.

This signal is also used to indicate a new account that did not previously exist has been added (with `valid` set to `TRUE`).

If `valid` is `TRUE`, `account` is guaranteed to have `TP_ACCOUNT_FEATURE_CORE` prepared, along with all the features previously passed to the “factory”'s `tp_simple_client_factory_add_account_features()`.

#### Parameters

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

Flags: Run Last

Since: 0.9.0

### The `“most-available-presence-changed”` signal

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

Emitted when the most available presence on `manager` changes.

#### Parameters

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

Flags: Run Last

Since: 0.9.0

## See Also

TpAccount