TpChannel: Deprecate _borrow_ functions and replace them by _get_

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

_tp_channel_get_immutable_properties() is kept internal because we don't
want to expose more dbus-glib structures. tp_channel_dup_immutable_properties()
is added, it returns a GVariant and should be needed only to TpChannel
subclasses.

13 files changed, 108 insertions, 33 deletions

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 480e5afe9..528e94503 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -3772,6 +3772,8 @@ TP_CHANNEL_FEATURE_CORE
 TP_CHANNEL_FEATURE_CONTACTS
 tp_channel_borrow_connection
 tp_channel_borrow_immutable_properties
+tp_channel_get_connection
+tp_channel_dup_immutable_properties
 tp_channel_get_channel_type
 tp_channel_get_channel_type_id
 tp_channel_get_handle
diff --git a/examples/client/stream-tubes/accepter.c b/examples/client/stream-tubes/accepter.c
index 79e8eff80..fd974ab24 100644
--- a/examples/client/stream-tubes/accepter.c
+++ b/examples/client/stream-tubes/accepter.c
@@ -58,7 +58,6 @@ _tube_accepted (GObject *tube,
   g_debug ("Received: %s", buf);
 
   g_object_unref (tube_conn);
-  g_object_unref (tube);
 }
 
 static void
@@ -82,7 +81,6 @@ _handle_channels (TpSimpleHandler *handler,
     TpHandleChannelsContext *context,
     gpointer user_data)
 {
-  TpStreamTubeChannel *tube;
   gboolean delay = FALSE;
   GList *l;
 
@@ -90,22 +88,13 @@ _handle_channels (TpSimpleHandler *handler,
 
   for (l = channels; l != NULL; l = l->next)
     {
-      TpChannel *channel = l->data;
-      GHashTable *props = tp_channel_borrow_immutable_properties (channel);
+      TpStreamTubeChannel *tube = l->data;
 
-      if (tp_channel_get_channel_type_id (channel) !=
-          TP_IFACE_QUARK_CHANNEL_TYPE_STREAM_TUBE)
-        continue;
-
-      if (tp_strdiff (
-            tp_asv_get_string (props, TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SERVICE),
-            "ExampleService"))
+      if (!TP_IS_STREAM_TUBE_CHANNEL (tube))
         continue;
 
       g_debug ("Accepting tube");
 
-      tube = g_object_ref (channel);
-
       g_signal_connect (tube, "invalidated",
           G_CALLBACK (tube_invalidated_cb), NULL);
 
diff --git a/telepathy-glib/call-channel.c b/telepathy-glib/call-channel.c
index 2473f510a..59dd90ba7 100644
--- a/telepathy-glib/call-channel.c
+++ b/telepathy-glib/call-channel.c
@@ -130,7 +130,7 @@ _tp_call_content_new (TpCallChannel *self,
       "dbus-daemon", tp_proxy_get_dbus_daemon (self),
       "dbus-connection", tp_proxy_get_dbus_connection (self),
       "object-path", object_path,
-      "connection", tp_channel_borrow_connection ((TpChannel *) self),
+      "connection", tp_channel_get_connection ((TpChannel *) self),
       "channel", self,
       NULL);
 }
@@ -544,7 +544,7 @@ call_members_changed_cb (TpChannel *channel,
   DEBUG ("Call members: %d changed, %d removed",
       g_hash_table_size (updates), removed->len);
 
-  connection = tp_channel_borrow_connection (channel);
+  connection = tp_channel_get_connection (channel);
   updates_contacts = _tp_call_members_convert_table (connection,
       updates, identifiers);
   removed_contacts = _tp_call_members_convert_array (connection,
@@ -582,7 +582,7 @@ got_all_properties_cb (TpProxy *proxy,
       return;
     }
 
-  connection = tp_channel_borrow_connection ((TpChannel *) self);
+  connection = tp_channel_get_connection ((TpChannel *) self);
   g_assert (tp_connection_has_immortal_handles (connection));
 
   self->priv->properties_retrieved = TRUE;
@@ -701,7 +701,7 @@ static void
 tp_call_channel_constructed (GObject *obj)
 {
   TpCallChannel *self = (TpCallChannel *) obj;
-  GHashTable *properties = tp_channel_borrow_immutable_properties (
+  GHashTable *properties = _tp_channel_get_immutable_properties (
       (TpChannel *) self);
 
   G_OBJECT_CLASS (tp_call_channel_parent_class)->constructed (obj);
diff --git a/telepathy-glib/channel-internal.h b/telepathy-glib/channel-internal.h
index 17d6f8816..77cf215ae 100644
--- a/telepathy-glib/channel-internal.h
+++ b/telepathy-glib/channel-internal.h
@@ -117,6 +117,7 @@ void _tp_channel_continue_introspection (TpChannel *self);
 void _tp_channel_abort_introspection (TpChannel *self,
     const gchar *debug,
     const GError *error);
+GHashTable *_tp_channel_get_immutable_properties (TpChannel *self);
 
 /* channel-group.c internals */
 
diff --git a/telepathy-glib/channel.c b/telepathy-glib/channel.c
index f70b9d56a..58918304f 100644
--- a/telepathy-glib/channel.c
+++ b/telepathy-glib/channel.c
@@ -32,6 +32,7 @@
 #include <telepathy-glib/util-internal.h>
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
+#include "telepathy-glib/dbus-internal.h"
 #include "telepathy-glib/debug-internal.h"
 #include "telepathy-glib/proxy-internal.h"
 #include "telepathy-glib/simple-client-factory-internal.h"
@@ -394,6 +395,8 @@ tp_channel_is_ready (TpChannel *self)
  *
  * Returns: (transfer none): the value of #TpChannel:connection
  * Since: 0.7.12
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_channel_get_connection() instead.
  */
 TpConnection *
 tp_channel_borrow_connection (TpChannel *self)
@@ -403,6 +406,23 @@ tp_channel_borrow_connection (TpChannel *self)
   return self->priv->connection;
 }
 
+/**
+ * tp_channel_get_connection:
+ * @self: a channel
+ *
+ * Returns the connection for this channel. The returned pointer is only valid
+ * while this channel is valid - reference it with g_object_ref() if needed.
+ *
+ * Returns: (transfer none): the value of #TpChannel:connection
+ * Since: 0.UNRELEASED
+ */
+TpConnection *
+tp_channel_get_connection (TpChannel *self)
+{
+  g_return_val_if_fail (TP_IS_CHANNEL (self), NULL);
+
+  return self->priv->connection;
+}
 
 /**
  * tp_channel_borrow_immutable_properties:
@@ -427,6 +447,8 @@ tp_channel_borrow_connection (TpChannel *self)
  *  where the keys are strings,
  *  D-Bus interface name + "." + property name, and the values are #GValue
  *  instances
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_channel_dup_immutable_properties() instead.
  */
 GHashTable *
 tp_channel_borrow_immutable_properties (TpChannel *self)
@@ -436,6 +458,44 @@ tp_channel_borrow_immutable_properties (TpChannel *self)
   return self->priv->channel_properties;
 }
 
+GHashTable *
+_tp_channel_get_immutable_properties (TpChannel *self)
+{
+  g_return_val_if_fail (TP_IS_CHANNEL (self), NULL);
+
+  return self->priv->channel_properties;
+}
+
+/**
+ * tp_channel_dup_immutable_properties:
+ * @self: a channel
+ *
+ * Returns the immutable D-Bus properties of this channel, in a variant of type
+ * %G_VARIANT_TYPE_VARDICT where the keys are strings,
+ * D-Bus interface name + "." + property name. Use g_variant_lookup() or
+ * g_variant_lookup_value() for convenient access to the values.
+ *
+ * If the #TpChannel:channel-properties property was not set during
+ * construction (e.g. by calling tp_channel_new_from_properties()), a
+ * reasonable but possibly incomplete version will be made up from the values
+ * of individual properties; reading this property repeatedly may yield
+ * progressively more complete values until the %TP_CHANNEL_FEATURE_CORE
+ * feature is prepared.
+ *
+ * This function should be used only by #TpChannel subclasses, otherwise it is
+ * recommended to use individual property getters instead.
+ *
+ * Returns: (transfer full): a dictionary where the keys are strings,
+ *  D-Bus interface name + "." + property name.
+ * Since: 0.UNRELEASED
+ */
+GVariant *
+tp_channel_dup_immutable_properties (TpChannel *self)
+{
+  g_return_val_if_fail (TP_IS_CHANNEL (self), NULL);
+
+  return _tp_asv_to_vardict (self->priv->channel_properties);
+}
 
 static void
 tp_channel_get_property (GObject *object,
diff --git a/telepathy-glib/channel.h b/telepathy-glib/channel.h
index 85b023716..8baa9e158 100644
--- a/telepathy-glib/channel.h
+++ b/telepathy-glib/channel.h
@@ -107,8 +107,17 @@ gboolean tp_channel_is_ready (TpChannel *self);
 
 void tp_channel_init_known_interfaces (void);
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR(tp_channel_get_connection)
 TpConnection *tp_channel_borrow_connection (TpChannel *self);
+_TP_DEPRECATED_IN_0_20_FOR(tp_channel_dup_immutable_properties)
 GHashTable *tp_channel_borrow_immutable_properties (TpChannel *self);
+#endif
+
+_TP_AVAILABLE_IN_0_20
+TpConnection *tp_channel_get_connection (TpChannel *self);
+_TP_AVAILABLE_IN_0_20
+GVariant *tp_channel_dup_immutable_properties (TpChannel *self);
 
 void tp_channel_leave_async (TpChannel *self,
     TpChannelGroupChangeReason reason,
diff --git a/telepathy-glib/contact-search.c b/telepathy-glib/contact-search.c
index 3c87f2343..2db77a0f4 100644
--- a/telepathy-glib/contact-search.c
+++ b/telepathy-glib/contact-search.c
@@ -30,6 +30,7 @@
 #include <telepathy-glib/util.h>
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
+#include "telepathy-glib/channel-internal.h"
 #include "telepathy-glib/debug-internal.h"
 
 #include "_gen/telepathy-interfaces.h"
@@ -224,7 +225,7 @@ _create_search_channel_cb (GObject *source_object,
       goto out;
     }
 
-  properties = tp_channel_borrow_immutable_properties (self->priv->channel);
+  properties = _tp_channel_get_immutable_properties (self->priv->channel);
 
   self->priv->keys = tp_asv_get_strv (properties,
       TP_PROP_CHANNEL_TYPE_CONTACT_SEARCH_AVAILABLE_SEARCH_KEYS);
diff --git a/telepathy-glib/dbus-tube-channel.c b/telepathy-glib/dbus-tube-channel.c
index 8cd552d9e..c8156abde 100644
--- a/telepathy-glib/dbus-tube-channel.c
+++ b/telepathy-glib/dbus-tube-channel.c
@@ -95,6 +95,7 @@
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
 #include "telepathy-glib/automatic-client-factory-internal.h"
+#include "telepathy-glib/channel-internal.h"
 #include "telepathy-glib/debug-internal.h"
 
 #include <stdio.h>
@@ -276,7 +277,7 @@ tp_dbus_tube_channel_constructed (GObject *obj)
       return;
     }
 
-  props = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  props = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   if (tp_asv_get_string (props, TP_PROP_CHANNEL_TYPE_DBUS_TUBE_SERVICE_NAME)
       == NULL)
@@ -488,7 +489,7 @@ tp_dbus_tube_channel_get_service_name (TpDBusTubeChannel *self)
 {
   GHashTable *props;
 
-  props = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  props = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   return tp_asv_get_string (props, TP_PROP_CHANNEL_TYPE_DBUS_TUBE_SERVICE_NAME);
 }
diff --git a/telepathy-glib/file-transfer-channel.c b/telepathy-glib/file-transfer-channel.c
index fcf0c6b1d..8e94e39b4 100644
--- a/telepathy-glib/file-transfer-channel.c
+++ b/telepathy-glib/file-transfer-channel.c
@@ -109,6 +109,7 @@
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
 #include "telepathy-glib/automatic-client-factory-internal.h"
+#include "telepathy-glib/channel-internal.h"
 #include "telepathy-glib/debug-internal.h"
 
 #include <stdio.h>
@@ -530,7 +531,7 @@ tp_file_transfer_channel_constructed (GObject *obj)
 
   G_OBJECT_CLASS (tp_file_transfer_channel_parent_class)->constructed (obj);
 
-  properties = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  properties = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   self->priv->mime_type = tp_asv_get_string (properties,
     TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_TYPE);
diff --git a/telepathy-glib/room-list.c b/telepathy-glib/room-list.c
index 5c1574a6b..372946780 100644
--- a/telepathy-glib/room-list.c
+++ b/telepathy-glib/room-list.c
@@ -51,6 +51,7 @@
 #include <telepathy-glib/util-internal.h>
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
+#include "telepathy-glib/channel-internal.h"
 #include "telepathy-glib/debug-internal.h"
 
 #include <stdio.h>
@@ -458,7 +459,7 @@ create_channel_cb (GObject *source_object,
       goto out;
     }
 
-  properties = tp_channel_borrow_immutable_properties (self->priv->channel);
+  properties = _tp_channel_get_immutable_properties (self->priv->channel);
 
   server = tp_asv_get_string (properties,
       TP_PROP_CHANNEL_TYPE_ROOM_LIST_SERVER);
diff --git a/telepathy-glib/stream-tube-channel.c b/telepathy-glib/stream-tube-channel.c
index 452e02c5b..171fcdbdf 100644
--- a/telepathy-glib/stream-tube-channel.c
+++ b/telepathy-glib/stream-tube-channel.c
@@ -61,6 +61,7 @@
 #include <telepathy-glib/util.h>
 
 #define DEBUG_FLAG TP_DEBUG_CHANNEL
+#include "telepathy-glib/channel-internal.h"
 #include "telepathy-glib/debug-internal.h"
 #include "telepathy-glib/automatic-client-factory-internal.h"
 
@@ -350,7 +351,7 @@ tp_stream_tube_channel_constructed (GObject *obj)
       return;
     }
 
-  props = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  props = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   if (tp_asv_get_string (props, TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SERVICE)
       == NULL)
@@ -603,7 +604,7 @@ new_local_connection_identified (TpStreamTubeChannel *self,
   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   initiator_handle = tp_channel_get_initiator_handle (TP_CHANNEL (self));
 
-  connection = tp_channel_borrow_connection (TP_CHANNEL (self));
+  connection = tp_channel_get_connection (TP_CHANNEL (self));
   features = tp_simple_client_factory_dup_contact_features (
       tp_proxy_get_factory (connection), connection);
 
@@ -842,7 +843,7 @@ tp_stream_tube_channel_accept_async (TpStreamTubeChannel *self,
   self->priv->result = g_simple_async_result_new (G_OBJECT (self), callback,
       user_data, tp_stream_tube_channel_accept_async);
 
-  properties = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  properties = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
   supported_sockets = tp_asv_get_boxed (properties,
       TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SUPPORTED_SOCKET_TYPES,
       TP_HASH_TYPE_SUPPORTED_SOCKET_MAP);
@@ -1075,7 +1076,7 @@ connection_identified (TpStreamTubeChannel *self,
       TpConnection *connection;
       GArray *features;
 
-      connection = tp_channel_borrow_connection (TP_CHANNEL (self));
+      connection = tp_channel_get_connection (TP_CHANNEL (self));
       features = tp_simple_client_factory_dup_contact_features (
           tp_proxy_get_factory (connection), connection);
 
@@ -1411,7 +1412,7 @@ tp_stream_tube_channel_offer_async (TpStreamTubeChannel *self,
   self->priv->result = g_simple_async_result_new (G_OBJECT (self), callback,
       user_data, tp_stream_tube_channel_offer_async);
 
-  properties = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  properties = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
   supported_sockets = tp_asv_get_boxed (properties,
       TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SUPPORTED_SOCKET_TYPES,
       TP_HASH_TYPE_SUPPORTED_SOCKET_MAP);
@@ -1530,7 +1531,7 @@ tp_stream_tube_channel_get_service (TpStreamTubeChannel *self)
 {
   GHashTable *props;
 
-  props = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  props = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   return tp_asv_get_string (props, TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SERVICE);
 }
diff --git a/telepathy-glib/text-channel.c b/telepathy-glib/text-channel.c
index 0f8ca6c3f..b4930f160 100644
--- a/telepathy-glib/text-channel.c
+++ b/telepathy-glib/text-channel.c
@@ -193,7 +193,7 @@ get_sender (TpTextChannel *self,
 
   sender_id = tp_asv_get_string (header, "message-sender-id");
 
-  conn = tp_channel_borrow_connection ((TpChannel *) self);
+  conn = tp_channel_get_connection ((TpChannel *) self);
   *contact = tp_connection_dup_contact_if_possible (conn, handle, sender_id);
 
   if (*contact == NULL)
@@ -230,7 +230,7 @@ prepare_sender_async (TpTextChannel *self,
     {
       TpConnection *conn;
 
-      conn = tp_channel_borrow_connection ((TpChannel *) self);
+      conn = tp_channel_get_connection ((TpChannel *) self);
 
       DEBUG ("Failed to get our self contact, please fix CM (%s)",
           tp_proxy_get_object_path (conn));
@@ -372,7 +372,7 @@ chat_state_changed_cb (TpTextChannel *self,
    * TP_CHANNEL_FEATURE_CONTACTS has been prepared, we should already have its
    * TpContact. If the TpContact does not exist, telling its chat state is
    * useless anyway. */
-  conn = tp_channel_borrow_connection ((TpChannel *) self);
+  conn = tp_channel_get_connection ((TpChannel *) self);
   contact = tp_connection_dup_contact_if_possible (conn, handle, NULL);
   if (contact == NULL)
     return;
@@ -441,7 +441,7 @@ tp_text_channel_constructed (GObject *obj)
   g_signal_connect (self, "chat-state-changed",
       G_CALLBACK (chat_state_changed_cb), NULL);
 
-  props = tp_channel_borrow_immutable_properties (TP_CHANNEL (self));
+  props = _tp_channel_get_immutable_properties (TP_CHANNEL (self));
 
   self->priv->supported_content_types = (GStrv) tp_asv_get_strv (props,
       TP_PROP_CHANNEL_INTERFACE_MESSAGES_SUPPORTED_CONTENT_TYPES);
diff --git a/tests/lib/simple-channel-dispatch-operation.c b/tests/lib/simple-channel-dispatch-operation.c
index df7f491b4..6a809f624 100644
--- a/tests/lib/simple-channel-dispatch-operation.c
+++ b/tests/lib/simple-channel-dispatch-operation.c
@@ -149,13 +149,22 @@ tp_tests_simple_channel_dispatch_operation_get_property (GObject *object,
         for (i = 0; i < self->priv->channels->len; i++)
           {
             TpChannel *channel = g_ptr_array_index (self->priv->channels, i);
+            GValue props_value = G_VALUE_INIT;
+            GVariant *props_variant;
+
+            /* Yay, double conversion! But this is for tests corner case */
+            props_variant = tp_channel_dup_immutable_properties (channel);
+            dbus_g_value_parse_g_variant (props_variant, &props_value);
 
             g_ptr_array_add (arr,
                 tp_value_array_build (2,
                   DBUS_TYPE_G_OBJECT_PATH, tp_proxy_get_object_path (channel),
                   TP_HASH_TYPE_STRING_VARIANT_MAP,
-                    tp_channel_borrow_immutable_properties (channel),
+                      g_value_get_boxed (&props_value),
                   G_TYPE_INVALID));
+
+            g_variant_unref (props_variant);
+            g_value_unset (&props_value);
           }
 
         g_value_take_boxed (value, arr);