[next] telepathy-glib: TpTextChannel: Deprecate _get_ functions returning a GList and replace them by _dup_

[Xavier Claessens]

Module: telepathy-glib
Branch: next
Commit: 8a628bd8efeee4fe359a72cf56bdde6350c024dc
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=8a628bd8efeee4fe359a72cf56bdde6350c024dc

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

TpTextChannel: 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/text-handler.c             |    4 +-
 telepathy-glib/text-channel.c              |   34 ++++++++++++++++++++++++---
 telepathy-glib/text-channel.h              |    6 +++++
 4 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index b6da578..7c91be2 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -6639,6 +6639,7 @@ tp_text_channel_get_supported_content_types
 tp_text_channel_get_message_part_support_flags
 tp_text_channel_get_delivery_reporting_support
 tp_text_channel_get_pending_messages
+tp_text_channel_dup_pending_messages
 tp_text_channel_get_message_types
 TP_TEXT_CHANNEL_FEATURE_INCOMING_MESSAGES
 tp_text_channel_send_message_async
diff --git a/examples/client/text-handler.c b/examples/client/text-handler.c
index d2c0aa2..c9cf2d7 100644
--- a/examples/client/text-handler.c
+++ b/examples/client/text-handler.c
@@ -66,7 +66,7 @@ display_pending_messages (TpTextChannel *channel)
 {
   GList *messages, *l;
 
-  messages = tp_text_channel_get_pending_messages (channel);
+  messages = tp_text_channel_dup_pending_messages (channel);
 
   for (l = messages; l != NULL; l = g_list_next (l))
     {
@@ -77,7 +77,7 @@ display_pending_messages (TpTextChannel *channel)
 
   tp_text_channel_ack_messages_async (channel, messages, NULL, NULL);
 
-  g_list_free (messages);
+  g_list_free_full (messages, g_object_unref);
 }
 
 static void
diff --git a/telepathy-glib/text-channel.c b/telepathy-glib/text-channel.c
index b4930f1..f1f2cde 100644
--- a/telepathy-glib/text-channel.c
+++ b/telepathy-glib/text-channel.c
@@ -1229,7 +1229,7 @@ tp_text_channel_get_delivery_reporting_support (
  * Expands to a call to a function that returns a quark representing the
  * incoming messages features of a #TpTextChannel.
  *
- * When this feature is prepared, tp_text_channel_get_pending_messages() will
+ * When this feature is prepared, tp_text_channel_dup_pending_messages() will
  * return a non-empty list if any unacknowledged messages are waiting, and the
  * #TpTextChannel::message-received and #TpTextChannel::pending-message-removed
  * signals will be emitted.
@@ -1261,6 +1261,8 @@ tp_text_channel_get_feature_quark_incoming_messages (void)
  * a #GList of borrowed #TpSignalledMessage
  *
  * Since: 0.13.10
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_text_channel_dup_pending_messages() instead.
  */
 GList *
 tp_text_channel_get_pending_messages (TpTextChannel *self)
@@ -1268,6 +1270,30 @@ tp_text_channel_get_pending_messages (TpTextChannel *self)
   return g_list_copy (g_queue_peek_head_link (self->priv->pending_messages));
 }
 
+/**
+ * tp_text_channel_dup_pending_messages:
+ * @self: a #TpTextChannel
+ *
+ * Return a newly allocated list of unacknowledged #TpSignalledMessage
+ * objects.
+ *
+ * It is guaranteed that the #TpSignalledMessage:sender of each
+ * #TpSignalledMessage has all of the features previously passed to
+ * tp_simple_client_factory_add_contact_features() prepared.
+ *
+ * Returns: (transfer full) (element-type TelepathyGLib.SignalledMessage):
+ * a #GList of reffed #TpSignalledMessage
+ *
+ * Since: 0.UNRELEASED
+ */
+GList *
+tp_text_channel_dup_pending_messages (TpTextChannel *self)
+{
+  return _tp_g_list_copy_deep (
+      g_queue_peek_head_link (self->priv->pending_messages),
+      (GCopyFunc) g_object_ref, NULL);
+}
+
 static void
 send_message_cb (TpChannel *proxy,
     const gchar *token,
@@ -1408,7 +1434,7 @@ acknowledge_pending_messages_cb (TpChannel *channel,
  * result of the operation.
  *
  * You should use the #TpSignalledMessage received from
- * tp_text_channel_get_pending_messages() or the
+ * tp_text_channel_dup_pending_messages() or the
  * #TpTextChannel::message-received signal.
  *
  * See tp_text_channel_ack_message_async() about acknowledging messages.
@@ -1506,7 +1532,7 @@ tp_text_channel_ack_messages_finish (TpTextChannel *self,
  * signal is fired.
  *
  * You should use the #TpSignalledMessage received from
- * tp_text_channel_get_pending_messages() or the
+ * tp_text_channel_dup_pending_messages() or the
  * #TpTextChannel::message-received signal.
  *
  * Since: 0.13.10
@@ -1946,7 +1972,7 @@ tp_text_channel_get_sms_length_finish (TpTextChannel *self,
  *
  * Acknowledge all the pending messages. This is equivalent of calling
  * tp_text_channel_ack_messages_async() with the list of #TpSignalledMessage
- * returned by tp_text_channel_get_pending_messages().
+ * returned by tp_text_channel_dup_pending_messages().
  *
  * Once the messages have been acked, @callback will be called.
  * You can then call tp_text_channel_ack_all_pending_messages_finish() to get
diff --git a/telepathy-glib/text-channel.h b/telepathy-glib/text-channel.h
index 0474822..3389908 100644
--- a/telepathy-glib/text-channel.h
+++ b/telepathy-glib/text-channel.h
@@ -85,7 +85,13 @@ gboolean tp_text_channel_supports_message_type (TpTextChannel *self,
   tp_text_channel_get_feature_quark_incoming_messages ()
 GQuark tp_text_channel_get_feature_quark_incoming_messages (void) G_GNUC_CONST;
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR (tp_text_channel_dup_pending_messages)
 GList * tp_text_channel_get_pending_messages (TpTextChannel *self);
+#endif
+
+_TP_AVAILABLE_IN_0_20
+GList * tp_text_channel_dup_pending_messages (TpTextChannel *self);
 
 void tp_text_channel_send_message_async (TpTextChannel *self,
     TpMessage *message,