[Bug 28044] TpConnection should have API to get/upgrade a single TpContact

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=28044

--- Comment #1 from Simon McVittie <simon.mcvittie at collabora.co.uk> 2010-05-10 02:42:41 PDT ---
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

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.