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

[Xavier Claessens]

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

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

TpBaseClient: 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 |    2 +
 telepathy-glib/base-client.c               |   59 ++++++++++++++++++++++++++--
 telepathy-glib/base-client.h               |    9 ++++
 3 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 4bdf9ce..b6da578 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -5738,6 +5738,7 @@ tp_base_client_add_connection_features_varargs
 tp_base_client_add_channel_features
 tp_base_client_add_channel_features_varargs
 tp_base_client_get_handled_channels
+tp_base_client_dup_handled_channels
 tp_base_client_is_handling_channel
 tp_base_client_delegate_channels_async
 tp_base_client_delegate_channels_finish
@@ -5746,6 +5747,7 @@ tp_base_client_set_delegated_channels_callback
 tp_channel_dispatcher_present_channel_async
 tp_channel_dispatcher_present_channel_finish
 tp_base_client_get_pending_requests
+tp_base_client_dup_pending_requests
 tp_base_client_set_handler_bypass_approval
 tp_base_client_set_handler_request_notification
 tp_base_client_register
diff --git a/telepathy-glib/base-client.c b/telepathy-glib/base-client.c
index f25c2c9..033d870 100644
--- a/telepathy-glib/base-client.c
+++ b/telepathy-glib/base-client.c
@@ -907,6 +907,8 @@ tp_base_client_register (TpBaseClient *self,
  * #GList of #TpChannelRequest
  *
  * Since: 0.11.6
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_base_client_dup_pending_requests() instead.
  */
 GList *
 tp_base_client_get_pending_requests (TpBaseClient *self)
@@ -927,6 +929,8 @@ tp_base_client_get_pending_requests (TpBaseClient *self)
  * handled channels
  *
  * Since: 0.11.6
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_base_client_dup_handled_channels() instead.
  */
 GList *
 tp_base_client_get_handled_channels (TpBaseClient *self)
@@ -960,6 +964,53 @@ tp_base_client_get_handled_channels (TpBaseClient *self)
   return result;
 }
 
+/**
+ * tp_base_client_dup_pending_requests:
+ * @self: a #TpBaseClient
+ *
+ * Only works if tp_base_client_set_handler_request_notification() has been
+ * called.
+ * Returns the list of requests @self is likely be asked to handle.
+ *
+ * Returns: (transfer full) (element-type TelepathyGLib.ChannelRequest): a
+ * #GList of #TpChannelRequest
+ *
+ * Since: 0.UNRELEASED
+ */
+GList *
+tp_base_client_dup_pending_requests (TpBaseClient *self)
+{
+  g_return_val_if_fail (self->priv->flags & CLIENT_IS_HANDLER, NULL);
+
+  return _tp_g_list_copy_deep (self->priv->pending_requests,
+      (GCopyFunc) g_object_ref, NULL);
+}
+
+/**
+ * tp_base_client_dup_handled_channels:
+ * @self: a #TpBaseClient
+ *
+ * Returns the set of channels currently handled by this base client or by any
+ * other #TpBaseClient with which it shares a unique name.
+ *
+ * Returns: (transfer full) (element-type TelepathyGLib.Channel): the
+ * handled channels
+ *
+ * Since: 0.UNRELEASED
+ */
+GList *
+tp_base_client_dup_handled_channels (TpBaseClient *self)
+{
+  GList *ret;
+
+  G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+  ret = tp_base_client_get_handled_channels (self);
+  G_GNUC_END_IGNORE_DEPRECATIONS
+  g_list_foreach (ret, (GFunc) g_object_ref, NULL);
+
+  return ret;
+}
+
 static void
 tp_base_client_init (TpBaseClient *self)
 {
@@ -1279,7 +1330,7 @@ tp_base_client_get_dbus_properties (GObject *object,
 
     case DP_HANDLED_CHANNELS:
         {
-          GList *channels = tp_base_client_get_handled_channels (self);
+          GList *channels = tp_base_client_dup_handled_channels (self);
           GList *iter;
           GPtrArray *arr = g_ptr_array_sized_new (g_list_length (channels));
 
@@ -1288,7 +1339,7 @@ tp_base_client_get_dbus_properties (GObject *object,
                 g_strdup (tp_proxy_get_object_path (iter->data)));
 
           g_value_take_boxed (value, arr);
-          g_list_free (channels);
+          g_list_free_full (channels, g_object_unref);
         }
       break;
 
@@ -3023,7 +3074,7 @@ tp_base_client_is_handling_channel (TpBaseClient *self,
   g_return_val_if_fail (TP_IS_BASE_CLIENT (self), FALSE);
   g_return_val_if_fail (self->priv->flags & CLIENT_IS_HANDLER, FALSE);
 
-  channels = tp_base_client_get_handled_channels (self);
+  channels = tp_base_client_dup_handled_channels (self);
   for (l = channels; l != NULL && !found; l = g_list_next (l))
     {
       TpChannel *chan = l->data;
@@ -3033,7 +3084,7 @@ tp_base_client_is_handling_channel (TpBaseClient *self,
         found = TRUE;
     }
 
-  g_list_free (channels);
+  g_list_free_full (channels, g_object_unref);
   return found;
 }
 
diff --git a/telepathy-glib/base-client.h b/telepathy-glib/base-client.h
index 07c1302..ae5ba3d 100644
--- a/telepathy-glib/base-client.h
+++ b/telepathy-glib/base-client.h
@@ -198,8 +198,17 @@ gboolean tp_base_client_register (TpBaseClient *self,
 
 /* Normal methods, can be called at any time */
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR (tp_base_client_dup_pending_requests)
 GList *tp_base_client_get_pending_requests (TpBaseClient *self);
+_TP_DEPRECATED_IN_0_20_FOR (tp_base_client_dup_handled_channels)
 GList *tp_base_client_get_handled_channels (TpBaseClient *self);
+#endif
+
+_TP_AVAILABLE_IN_0_20
+GList *tp_base_client_dup_pending_requests (TpBaseClient *self);
+_TP_AVAILABLE_IN_0_20
+GList *tp_base_client_dup_handled_channels (TpBaseClient *self);
 
 gboolean tp_base_client_is_handling_channel (TpBaseClient *self,
     TpChannel *channel);