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

1 files changed, 31 insertions, 4 deletions

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