[Telepathy-commits] [telepathy-glib/master] Warn against using handle-holding D-Bus APIs directly

[Simon McVittie]

---
 telepathy-glib/connection-handles.c |   11 +++++++++++
 telepathy-glib/contact.c            |   11 +++++++++++
 2 files changed, 22 insertions(+), 0 deletions(-)

diff --git a/telepathy-glib/connection-handles.c b/telepathy-glib/connection-handles.c
index 575ee06..3d8647a 100644
--- a/telepathy-glib/connection-handles.c
+++ b/telepathy-glib/connection-handles.c
@@ -268,6 +268,17 @@ _tp_connection_clean_up_handle_refs (TpConnection *self)
  * Release the reference to the handles in @handles that was obtained by
  * calling tp_connection_hold_handles() or tp_connection_request_handles().
  *
+ * This function might release any references held by calling
+ * tp_cli_connection_call_request_handles(),
+ * tp_cli_connection_run_request_handles(),
+ * tp_cli_connection_call_hold_handles(),
+ * tp_cli_connection_run_hold_handles(),
+ * tp_cli_connection_interface_contacts_call_get_contact_attributes() or
+ * tp_cli_connection_interface_contacts_run_get_contact_attributes() directly.
+ * Those functions should be avoided in favour of using #TpContact,
+ * tp_connection_hold_handles(), tp_connection_request_handles() and
+ * tp_connection_get_contact_attributes().
+ *
  * If @self has already become invalid, this function does nothing.
  */
 void
diff --git a/telepathy-glib/contact.c b/telepathy-glib/contact.c
index 3fb2d4d..f896ada 100644
--- a/telepathy-glib/contact.c
+++ b/telepathy-glib/contact.c
@@ -47,6 +47,17 @@
  * Contact objects are instantiated using
  * tp_connection_get_contacts_by_handle() or
  * tp_connection_get_contacts_by_id().
+ *
+ * Note that releasing a #TpContact object might release handle references
+ * held by calling tp_cli_connection_call_request_handles(),
+ * tp_cli_connection_run_request_handles(),
+ * tp_cli_connection_call_hold_handles(),
+ * tp_cli_connection_run_hold_handles(),
+ * tp_cli_connection_interface_contacts_call_get_contact_attributes() or
+ * tp_cli_connection_interface_contacts_run_get_contact_attributes() directly.
+ * Those functions should be avoided in favour of using #TpContact,
+ * tp_connection_hold_handles(), tp_connection_request_handles() and
+ * tp_connection_get_contact_attributes().
  */
 
 struct _TpContactClass {
-- 
1.5.6.5