Bug 28044

Summary:	TpConnection should have API to get/upgrade a single TpContact
Product:	Telepathy	Reporter:	Xavier Claessens <xclaesse>
Component:	tp-glib	Assignee:	Telepathy bugs list <telepathy-bugs>
Status:	RESOLVED DUPLICATE	QA Contact:	Telepathy bugs list <telepathy-bugs>
Severity:	normal
Priority:	medium
Version:	unspecified
Hardware:	Other
OS:	All
Whiteboard:
i915 platform:		i915 features:

Description Xavier Claessens 2010-05-09 14:47:22 UTC

I think it is very common to get/upgrade only one TpContact. In that case current API is a pain because callback returns a global GError, plus a hashtable/array of GError per contact... in the case of a single contact that can be simplified.

Also we could make use GAsync API for those, since it's the prefered way now.

So I suggest deprecate current API:
tp_connection_get_contacts_by_handle
tp_connection_get_contacts_by_id
tp_connection_upgrade_contacts

and instroduce:
tp_connection_get_contacts_by_handle_async/finish
tp_connection_get_contact_by_handle_async/finish
tp_connection_get_contacts_by_id_async/finish
tp_connection_get_contact_by_id_async/finish
tp_connection_upgrade_contacts_async/finish
tp_connection_upgrade_contact_async/finish

Comment 1 Simon McVittie 2010-05-10 02:42:41 UTC

Plural GAsyncResult-style methods for TpContact are Bug #27687. I think it would be reasonable to add singular API at the same time.

The current API probably shouldn't be deprecated until the replacement exists in a stable branch (0.12); there's nothing actually wrong with it, it just pre-dates GAsyncResult.

The rationale for only having plural methods so far is that they're much more efficient in terms of D-Bus round-trips (ask Senko or Rob for the figures on how much they speeded up joining #ubuntu on a 770 by replacing InspectHandle with InspectHandles!); whenever someone does a batch operation on an entire Channel, or the entire contact list, we definitely want them to be using the plural API. It would be OK to have singular methods as well, as long as their documentation has a prominent reference like:

"tp_connection_upgrade_contact_async:
...
When dealing with multiple contacts, tp_connection_upgrade_contacts_async() is much more efficient than calling this method repeatedly."

This becomes particularly important if the singular upgrade method moves onto TpContact (which it probably should).

As far as requirements go:

* requesting by ID should probably automatically wait for the connection's CONNECTED feature if necessary, and be documented to do so (and need a call to Connect(), to complete)

* requesting by handle is incorrect before CONNECTED, and should fail or even g_critical (handles are meaningless before connected, so if you claim to have a suitable handle before the connection goes CONNECTED, you're very confused)

* upgrading doesn't need a check, because you can't make a TpContact until it's valid to do so

Comment 2 Xavier Claessens 2010-05-10 05:14:47 UTC

Right, let's close this bug dup of bug #27687

*** This bug has been marked as a duplicate of bug 27687 ***

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.