TpProxy: 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

5 files changed, 44 insertions, 5 deletions

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 8f4eb54f5..480e5afe9 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -3737,6 +3737,7 @@ tp_cli_dbus_properties_run_set
 tp_proxy_add_interface_by_id
 tp_proxy_add_interfaces
 tp_proxy_borrow_interface_by_id
+tp_proxy_get_interface_by_id
 tp_proxy_invalidate
 TpProxyInterfaceAddedCb
 tp_proxy_or_subclass_hook_on_interface_add
diff --git a/telepathy-glib/proxy-signals.c b/telepathy-glib/proxy-signals.c
index 013faf410..2af1e3854 100644
--- a/telepathy-glib/proxy-signals.c
+++ b/telepathy-glib/proxy-signals.c
@@ -370,7 +370,7 @@ tp_proxy_signal_connection_v0_new (TpProxy *self,
                                    GError **error)
 {
   TpProxySignalConnection *sc;
-  DBusGProxy *iface_proxy = tp_proxy_borrow_interface_by_id (self,
+  DBusGProxy *iface_proxy = tp_proxy_get_interface_by_id (self,
       iface, error);
 
   if (iface_proxy == NULL)
diff --git a/telepathy-glib/proxy-subclass.h b/telepathy-glib/proxy-subclass.h
index 060273869..1340def96 100644
--- a/telepathy-glib/proxy-subclass.h
+++ b/telepathy-glib/proxy-subclass.h
@@ -63,8 +63,15 @@ typedef void (*TpProxyInterfaceAddedCb) (TpProxy *self,
 void tp_proxy_or_subclass_hook_on_interface_add (GType proxy_or_subclass,
     TpProxyInterfaceAddedCb callback);
 
+#ifndef TP_DISABLE_DEPRECATED
+_TP_DEPRECATED_IN_0_20_FOR(tp_proxy_get_interface_by_id)
 DBusGProxy *tp_proxy_borrow_interface_by_id (TpProxy *self, GQuark iface,
     GError **error);
+#endif
+
+_TP_AVAILABLE_IN_0_20
+DBusGProxy *tp_proxy_get_interface_by_id (TpProxy *self, GQuark iface,
+    GError **error);
 
 DBusGProxy *tp_proxy_add_interface_by_id (TpProxy *self, GQuark iface);
 void tp_proxy_add_interfaces (TpProxy *self, const gchar * const *interfaces);
diff --git a/telepathy-glib/proxy.c b/telepathy-glib/proxy.c
index 27f634087..870c4c713 100644
--- a/telepathy-glib/proxy.c
+++ b/telepathy-glib/proxy.c
@@ -446,12 +446,39 @@ static void tp_proxy_iface_destroyed_cb (DBusGProxy *dgproxy, TpProxy *self);
  * The reference is only valid as long as @self is.
  *
  * Since: 0.7.1
+ * Deprecated: Since 0.UNRELEASED. New code should use
+ *  tp_proxy_get_interface_by_id() instead.
  */
 DBusGProxy *
 tp_proxy_borrow_interface_by_id (TpProxy *self,
                                  GQuark iface,
                                  GError **error)
 {
+  return tp_proxy_get_interface_by_id (self, iface, error);
+}
+
+/**
+ * tp_proxy_get_interface_by_id: (skip)
+ * @self: the TpProxy
+ * @iface: quark representing the interface required
+ * @error: used to raise an error in the #TP_DBUS_ERRORS domain if @iface
+ *         is invalid, @self has been invalidated or @self does not implement
+ *         @iface
+ *
+ * <!-- -->
+ *
+ * Returns: a borrowed reference to a #DBusGProxy
+ * for which the bus name and object path are the same as for @self, but the
+ * interface is as given (or %NULL if an @error is raised).
+ * The reference is only valid as long as @self is.
+ *
+ * Since: 0.UNRELEASED
+ */
+DBusGProxy *
+tp_proxy_get_interface_by_id (TpProxy *self,
+                              GQuark iface,
+                              GError **error)
+{
   gpointer dgproxy;
 
   if (self->invalidated != NULL)
@@ -663,7 +690,7 @@ tp_proxy_iface_destroyed_cb (DBusGProxy *dgproxy,
  * Declare that this proxy supports a given interface.
  *
  * To use methods and signals of that interface, either call
- * tp_proxy_borrow_interface_by_id() to get the #DBusGProxy, or use the
+ * tp_proxy_get_interface_by_id() to get the #DBusGProxy, or use the
  * tp_cli_* wrapper functions (strongly recommended).
  *
  * If the interface is the proxy's "main interface", or has already been
@@ -671,7 +698,7 @@ tp_proxy_iface_destroyed_cb (DBusGProxy *dgproxy,
  *
  * Returns: either %NULL or a borrowed #DBusGProxy corresponding to @iface,
  * depending on implementation details. To reliably borrow the #DBusGProxy, use
- * tp_proxy_borrow_interface_by_id(). (This method should probably have
+ * tp_proxy_get_interface_by_id(). (This method should probably have
  * returned void; sorry.)
  *
  * Since: 0.7.1
@@ -695,7 +722,7 @@ tp_proxy_add_interface_by_id (TpProxy *self,
       /* we don't want to actually create it just yet - dbus-glib will
        * helpfully wake us up on every signal, if we do. So we set a
        * dummy value (self), and replace it with the real value in
-       * tp_proxy_borrow_interface_by_id */
+       * tp_proxy_get_interface_by_id */
       g_datalist_id_set_data_full (&self->priv->interfaces, iface,
           self, NULL);
     }
@@ -1368,7 +1395,7 @@ tp_proxy_class_init (TpProxyClass *klass)
    * Emitted when this proxy has gained an interface. It is not guaranteed
    * to be emitted immediately, but will be emitted before the interface is
    * first used (at the latest: before it's returned from
-   * tp_proxy_borrow_interface_by_id(), any signal is connected, or any
+   * tp_proxy_get_interface_by_id(), any signal is connected, or any
    * method is called).
    *
    * The intended use is to call dbus_g_proxy_add_signals(). This signal
diff --git a/tools/glib-client-gen.py b/tools/glib-client-gen.py
index 6b2b97f1d..f8465a62b 100644
--- a/tools/glib-client-gen.py
+++ b/tools/glib-client-gen.py
@@ -783,9 +783,11 @@ class Generator(object):
         self.b('  g_return_val_if_fail (callback != NULL || '
                'weak_object == NULL, NULL);')
         self.b('')
+        self.b('  G_GNUC_BEGIN_IGNORE_DEPRECATIONS')
         self.b('  iface = tp_proxy_borrow_interface_by_id (')
         self.b('      (TpProxy *) proxy,')
         self.b('      interface, &error);')
+        self.b('  G_GNUC_END_IGNORE_DEPRECATIONS')
         self.b('')
         self.b('  if (iface == NULL)')
         self.b('    {')
@@ -1064,8 +1066,10 @@ class Generator(object):
         self.b('  g_return_val_if_fail (%s (proxy), FALSE);'
                % self.proxy_assert)
         self.b('')
+        self.b('  G_GNUC_BEGIN_IGNORE_DEPRECATIONS')
         self.b('  iface = tp_proxy_borrow_interface_by_id')
         self.b('       ((TpProxy *) proxy, interface, error);')
+        self.b('  G_GNUC_END_IGNORE_DEPRECATIONS')
         self.b('')
         self.b('  if (iface == NULL)')
         self.b('    return FALSE;')