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

1 files changed, 30 insertions, 4 deletions

diff --git a/telepathy-glib/text-channel.c b/telepathy-glib/text-channel.c
index b4930f160..f1f2cdefb 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