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.

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

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.

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

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.

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

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.

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.

Since 0.9.0

tp_account_manager_ensure_account ()

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

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

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.

Since 0.9.0

tp_account_manager_get_valid_accounts ()

GList *             tp_account_manager_get_valid_accounts
                                                        (TpAccountManager *manager);

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

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

1
2
3

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

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

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.

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.

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.

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.

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

tp_account_manager_is_prepared ()

gboolean            tp_account_manager_is_prepared      (TpAccountManager *manager,
                                                         GQuark feature);

Since 0.9.0

tp_account_manager_prepare_async ()

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

Requests an asynchronous preparation of manager with 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.

Since 0.9.0

tp_account_manager_prepare_finish ()

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

Finishes an async preparation of the account manager manager.

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.

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.

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.

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>

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.

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>

The "account-disabled" signal

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

Emitted when an account from manager is disabled.

Since 0.9.0

The "account-enabled" signal

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

Emitted when an account from manager is enabled.

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

Since 0.9.0

The "account-removed" signal

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

Emitted when an account is removed from manager.

Since 0.9.0

The "account-validity-changed" signal

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

Emitted when the validity on account changes.

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

Since 0.9.0

The "most-available-presence-changed" signal

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

Emitted when the most available presence on manager changes.

Since 0.9.0