telepathy-glib: TpProxy: Deprecate _borrow_ functions and replace them by _get_
Xavier Claessens
xclaesse at kemper.freedesktop.org
Wed Sep 5 07:29:34 PDT 2012
Module: telepathy-glib
Branch: master
Commit: fad8f1f85525c1bf698240af6e6bad0cd3636a57
URL: http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=fad8f1f85525c1bf698240af6e6bad0cd3636a57
Author: Xavier Claessens <xavier.claessens at collabora.co.uk>
Date: Wed Sep 5 11:15:00 2012 +0200
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
---
docs/reference/telepathy-glib-sections.txt | 1 +
telepathy-glib/proxy-signals.c | 2 +-
telepathy-glib/proxy-subclass.h | 7 +++++
telepathy-glib/proxy.c | 35 ++++++++++++++++++++++++---
tools/glib-client-gen.py | 4 +++
5 files changed, 44 insertions(+), 5 deletions(-)
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 8f4eb54..480e5af 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 013faf4..2af1e38 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 0602738..1340def 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 27f6340..870c4c7 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 6b2b97f..f8465a6 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;')
More information about the telepathy-commits
mailing list