telepathy-glib: TpAccountManager: Deprecate _get_ functions returning a GList and replace them by _dup_

[Xavier Claessens]

Module: telepathy-glib
Branch: master
Commit: a934de9b7cdec5204046dacf38afcac9a12eef69
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=a934de9b7cdec5204046dacf38afcac9a12eef69

Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date:   Wed Sep  5 11:15:00 2012 +0200

TpAccountManager: Deprecate _get_ functions returning a GList and replace them by _dup_

New transfer and naming policy has been discussed in
https://bugs.freedesktop.org/show_bug.cgi?id=39189 and is
documented there: http://telepathy.freedesktop.org/wiki/Style/TelepathyGLib

---

 docs/reference/telepathy-glib-sections.txt |    1 +
 examples/client/contact-list.c             |    9 +++---
 telepathy-glib/account-manager.c           |   41 ++++++++++++++++++++++++++-
 telepathy-glib/account-manager.h           |    7 +++++
 4 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index d0f8cb9..4bdf9ce 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -5324,6 +5324,7 @@ tp_account_manager_create_account_async
 tp_account_manager_create_account_finish
 tp_account_manager_ensure_account
 tp_account_manager_get_valid_accounts
+tp_account_manager_dup_valid_accounts
 tp_account_manager_get_most_available_presence
 tp_account_manager_set_all_requested_presences
 tp_account_manager_enable_restart
diff --git a/examples/client/contact-list.c b/examples/client/contact-list.c
index 825d8c6..36b9734 100644
--- a/examples/client/contact-list.c
+++ b/examples/client/contact-list.c
@@ -18,8 +18,8 @@ account_manager_prepared_cb (GObject *object,
     gpointer user_data)
 {
   TpAccountManager *manager = (TpAccountManager *) object;
-  GMainLoop *loop = user_data;  
-  GList *accounts;
+  GMainLoop *loop = user_data;
+  GList *accounts, *l;
   GError *error = NULL;
 
   if (!tp_proxy_prepare_finish (object, res, &error))
@@ -28,8 +28,8 @@ account_manager_prepared_cb (GObject *object,
       goto OUT;
     }
 
-  for (accounts = tp_account_manager_get_valid_accounts (manager);
-       accounts != NULL; accounts = g_list_delete_link (accounts, accounts))
+  accounts = tp_account_manager_dup_valid_accounts (manager);
+  for (l = accounts; l != NULL; l = l->next)
     {
       TpAccount *account = accounts->data;
       TpConnection *connection = tp_account_get_connection (account);
@@ -60,6 +60,7 @@ account_manager_prepared_cb (GObject *object,
         }
       g_ptr_array_unref (contacts);
     }
+  g_list_free_full (accounts, g_object_unref);
 
 OUT:
   g_main_loop_quit (loop);
diff --git a/telepathy-glib/account-manager.c b/telepathy-glib/account-manager.c
index eb59962..7743923 100644
--- a/telepathy-glib/account-manager.c
+++ b/telepathy-glib/account-manager.c
@@ -56,7 +56,7 @@
  * 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_get_valid_accounts().
+ * tp_account_manager_dup_valid_accounts().
  *
  * The #TpAccountManager::account-validity-changed signal is emitted
  * to notify of the validity of an account changing. New accounts are
@@ -156,7 +156,7 @@ G_DEFINE_TYPE (TpAccountManager, tp_account_manager, TP_TYPE_PROXY)
  * #TpAccount objects subsequently announced by
  * #TpAccountManager::account-validity-changed are <emphasis>not</emphasis>
  * guaranteed to have this feature prepared. In practice, this means that
- * the accounts returned by calling tp_account_manager_get_valid_accounts()
+ * the accounts returned by calling tp_account_manager_dup_valid_accounts()
  * immediately after successfully calling tp_proxy_prepare_finish() on the
  * #TpAccountManager will have #TP_ACCOUNT_FEATURE_CORE prepared, but later
  * calls to that function do not have the same guarantee.
@@ -1116,6 +1116,8 @@ tp_account_manager_ensure_account (TpAccountManager *self,
  * Returns: (element-type TelepathyGLib.Account) (transfer container): a newly allocated #GList of valid accounts in @manager
  *
  * Since: 0.9.0
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_account_manager_dup_valid_accounts() instead.
  */
 GList *
 tp_account_manager_get_valid_accounts (TpAccountManager *manager)
@@ -1126,6 +1128,41 @@ tp_account_manager_get_valid_accounts (TpAccountManager *manager)
 }
 
 /**
+ * tp_account_manager_dup_valid_accounts:
+ * @manager: a #TpAccountManager
+ *
+ * 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 #TpAccount<!-- -->s are guaranteed to have
+ * %TP_ACCOUNT_FEATURE_CORE prepared, along with all features previously passed
+ * to tp_simple_client_factory_add_account_features().
+ *
+ * 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.
+ *
+ * Returns: (element-type TelepathyGLib.Account) (transfer full): a newly
+ *  allocated #GList of reffed valid accounts in @manager
+ *
+ * Since: 0.UNRELEASED
+ */
+GList *
+tp_account_manager_dup_valid_accounts (TpAccountManager *manager)
+{
+  GList *ret;
+
+  g_return_val_if_fail (TP_IS_ACCOUNT_MANAGER (manager), NULL);
+
+  ret = g_hash_table_get_values (manager->priv->accounts);
+  g_list_foreach (ret, (GFunc) g_object_ref, NULL);
+
+  return ret;
+}
+
+/**
  * tp_account_manager_set_all_requested_presences:
  * @manager: a #TpAccountManager
  * @type: a presence type to request
diff --git a/telepathy-glib/account-manager.h b/telepathy-glib/account-manager.h
index 58e1e19..8c52f10 100644
--- a/telepathy-glib/account-manager.h
+++ b/telepathy-glib/account-manager.h
@@ -96,8 +96,15 @@ TpAccount *tp_account_manager_ensure_account (TpAccountManager *manager,
     const gchar *path);
 #endif
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR (tp_account_manager_dup_valid_accounts)
 GList *tp_account_manager_get_valid_accounts (TpAccountManager *manager)
   G_GNUC_WARN_UNUSED_RESULT;
+#endif
+
+_TP_AVAILABLE_IN_0_20
+GList *tp_account_manager_dup_valid_accounts (TpAccountManager *manager)
+  G_GNUC_WARN_UNUSED_RESULT;
 
 void tp_account_manager_set_all_requested_presences (TpAccountManager *manager,
     TpConnectionPresenceType type, const gchar *status, const gchar *message);