[next] telepathy-glib: TpSimpleClientFactory: document " connection must be ours"

[Simon McVittie]

Module: telepathy-glib
Branch: next
Commit: 844041a378c457974e2b464b6081bc75f7ef23c2
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=844041a378c457974e2b464b6081bc75f7ef23c2

Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date:   Fri Sep  6 12:03:39 2013 +0100

TpSimpleClientFactory: document "connection must be ours"

tp_simple_client_factory_ensure_channel and
tp_simple_client_factory_ensure_contact already enforced that via a check,
but didn't document it.

tp_simple_client_factory_upgrade_contacts_async didn't previously
either document or enforce it, and strictly speaking there's no reason
why it shouldn't work, so I'm using a warning instead of a
critical-and-return - but it probably indicates an error, so I think
it should warn.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=54061
Reviewed-by: Guillaume Desmottes <guillaume.desmottes at collabora.co.uk>

---

 telepathy-glib/simple-client-factory.c |   10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/telepathy-glib/simple-client-factory.c b/telepathy-glib/simple-client-factory.c
index 71b8e6b..900fdfb 100644
--- a/telepathy-glib/simple-client-factory.c
+++ b/telepathy-glib/simple-client-factory.c
@@ -695,7 +695,7 @@ tp_simple_client_factory_add_connection_features_varargs (
 /**
  * tp_simple_client_factory_ensure_channel:
  * @self: a #TpSimpleClientFactory object
- * @connection: a #TpConnection
+ * @connection: a #TpConnection whose #TpProxy:factory is this object
  * @object_path: the object path of a channel on @connection
  * @immutable_properties: (transfer none) (element-type utf8 GObject.Value):
  *  the immutable properties of the channel
@@ -828,7 +828,7 @@ tp_simple_client_factory_add_channel_features_varargs (
 /**
  * tp_simple_client_factory_ensure_contact:
  * @self: a #TpSimpleClientFactory object
- * @connection: a #TpConnection
+ * @connection: a #TpConnection whose #TpProxy:factory is this object
  * @handle: a #TpHandle
  * @identifier: a string representing the contact's identifier
  *
@@ -904,7 +904,7 @@ upgrade_contacts_cb (GObject *source,
 /**
  * tp_simple_client_factory_upgrade_contacts_async:
  * @self: a #TpSimpleClientFactory object
- * @connection: a #TpConnection
+ * @connection: a #TpConnection whose #TpProxy:factory is this object
  * @n_contacts: The number of contacts in @contacts (must be at least 1)
  * @contacts: (array length=n_contacts): An array of #TpContact objects
  *  associated with @self
@@ -929,6 +929,10 @@ tp_simple_client_factory_upgrade_contacts_async (
   GSimpleAsyncResult *result;
   GArray *features;
 
+  /* no real reason this shouldn't work, but it's really confusing
+   * and probably indicates an error */
+  g_warn_if_fail (tp_proxy_get_factory (connection) == self);
+
   result = g_simple_async_result_new ((GObject *) self, callback, user_data,
       tp_simple_client_factory_upgrade_contacts_async);