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

[Xavier Claessens]

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

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

TpConnection: 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 +
 telepathy-glib/connection-contact-info.c   |   30 +++++++++++++++++++++++++++-
 telepathy-glib/connection.h                |    6 +++++
 3 files changed, 36 insertions(+), 1 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index ef74c09..def0c15 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -4232,6 +4232,7 @@ tp_connection_get_capabilities
 tp_connection_get_avatar_requirements
 tp_connection_get_contact_info_flags
 tp_connection_get_contact_info_supported_fields
+tp_connection_dup_contact_info_supported_fields
 tp_connection_set_contact_info_async
 tp_connection_set_contact_info_finish
 TP_UNKNOWN_CONNECTION_STATUS
diff --git a/telepathy-glib/connection-contact-info.c b/telepathy-glib/connection-contact-info.c
index 7879b2e..79792e1 100644
--- a/telepathy-glib/connection-contact-info.c
+++ b/telepathy-glib/connection-contact-info.c
@@ -345,7 +345,7 @@ G_DEFINE_BOXED_TYPE (TpContactInfoList, tp_contact_info_list,
  *
  * When this feature is prepared, the ContactInfoFlags and SupportedFields of
  * the Connection has been retrieved. Use tp_connection_get_contact_info_flags()
- * and tp_connection_get_contact_info_supported_fields() to get them once
+ * and tp_connection_dup_contact_info_supported_fields() to get them once
  * prepared.
  *
  * One can ask for a feature to be prepared using the
@@ -476,6 +476,8 @@ tp_connection_get_contact_info_flags (TpConnection *self)
  *  a #GList of #TpContactInfoFieldSpec struct, or %NULL if the feature is not
  *  yet prepared or the connection doesn't have the necessary properties.
  * Since: 0.11.7
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_connection_dup_contact_info_supported_fields() instead.
  */
 GList *
 tp_connection_get_contact_info_supported_fields (TpConnection *self)
@@ -485,6 +487,32 @@ tp_connection_get_contact_info_supported_fields (TpConnection *self)
   return g_list_copy (self->priv->contact_info_supported_fields);
 }
 
+/**
+ * tp_connection_dup_contact_info_supported_fields:
+ * @self: a connection
+ *
+ * Returns a newly allocated #GList of supported contact info fields for this
+ * connection. The list must be freed with tp_contact_info_spec_list_free().
+ *
+ * To wait for valid supported fields, call tp_proxy_prepare_async() with the
+ * feature %TP_CONNECTION_FEATURE_CONTACT_INFO.
+ *
+ * This property cannot change after @self goes to the Connected state.
+ *
+ * Returns: (element-type TelepathyGLib.ContactInfoFieldSpec) (transfer full):
+ *  a #GList of #TpContactInfoFieldSpec struct, or %NULL if the feature is not
+ *  yet prepared or the connection doesn't have the necessary properties.
+ * Since: 0.UNRELEASED
+ */
+GList *
+tp_connection_dup_contact_info_supported_fields (TpConnection *self)
+{
+  g_return_val_if_fail (TP_IS_CONNECTION (self), NULL);
+
+  return _tp_g_list_copy_deep (self->priv->contact_info_supported_fields,
+      (GCopyFunc) tp_contact_info_field_spec_copy, NULL);
+}
+
 static void
 set_info_cb (TpConnection *self,
     const GError *error,
diff --git a/telepathy-glib/connection.h b/telepathy-glib/connection.h
index def45fc..33ea3b6 100644
--- a/telepathy-glib/connection.h
+++ b/telepathy-glib/connection.h
@@ -171,7 +171,13 @@ TpCapabilities * tp_connection_get_capabilities (TpConnection *self);
 
 TpContactInfoFlags tp_connection_get_contact_info_flags (TpConnection *self);
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR (tp_connection_dup_contact_info_supported_fields)
 GList *tp_connection_get_contact_info_supported_fields (TpConnection *self);
+#endif
+
+_TP_AVAILABLE_IN_0_20
+GList *tp_connection_dup_contact_info_supported_fields (TpConnection *self);
 
 void tp_connection_set_contact_info_async (TpConnection *self,
     GList *info, GAsyncReadyCallback callback,