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@collabora.co.uk>

1 files changed, 7 insertions, 3 deletions

diff --git a/telepathy-glib/simple-client-factory.c b/telepathy-glib/simple-client-factory.c
index 71b8e6b64..900fdfb1d 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);