[Bug 35321] Implement 3rd party message send/receive API

bugzilla-daemon at freedesktop.org bugzilla-daemon at freedesktop.org
Tue Mar 15 10:22:44 CET 2011


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

--- Comment #3 from Olli Salli <ollisal at gmail.com> 2011-03-15 02:22:43 PDT ---
Comments on the API:

First of all, the API must allow selecting just a single contact to communicate
with. This is for convenience, but also for efficiency purposes: for a
single-contact API, we can register an observer filter with the TargetID key
for that contact. I imagine most uses for this API (except, if you want to
write some simple text logger, say) is for communicating with a single contact
at a time, so making the API reflect that we can prevent being woken up when
unrelated text channels appear.

Note that this API is necessarily somewhat inefficient though: it will be
invoked for the same contact ID being communicated with on ALL accounts, as we
can't declare a client filter to only catch communication on a single account.
We just need to filter the other accounts out client-side (note that we can't
signal them: the same contact ID can mean a different person on different
accounts).

The "I really want to write a simple text logger" usecase we could support by
allowing passing a NULL ContactPtr / empty contact identifier to the create()
method. This comes with the limitation that you can't send messages as you have
no recipient though. That is, the contact parameter should be removed from the
send methods and signals, as it'll be passed to the create() method already.
Following that, the simple text logger usecase looks even more distinct: maybe
a separate class for that, which we add later - so this API would always
require a valid contact passed to it? Then you don't need to worry about how to
signal the recipient in the signals either, because it'll be the one you
passed.

There should be a public accessor for the contact ID the object is
communicating with (NOT a ContactPtr - these are only temporary from this API's
POV, as they're specific to a Connection, not valid between different
Connections to an Account).

The send(Tp::Message) overload doesn't make sense here. Tp::Message is
exclusively for signaling sent and received messages by Tp::TextChannel (and
consequently, us) - not for passing in messages to send. You can't construct
anything else than text part only -message using its public API anyway (why it
allows even that is beyond me, though).

For sending simple text part only -messages, you'll use the QString textPart
overloads. For sending multi-part complex messages, you use the MessagePartList
overload. Though, we should really wrap MessagePart with one of our friendly
variant map wrappers for that (can be just an API/ABI placeholder empty class
for now). Currently it's a bit hostile to use, especially in a "simple" API
like this.

Now on to naming. So, this'll be a single-contact API. ContactMessenger?

One point I tried to make earlier is that while you don't need to worry about
designing and implementing other things than "send, but don't present the UI"
from http://www.mail-archive.com/telepathy@lists.freedesktop.org/msg04261.html,
you need to make the method naming / parameters cater for adding those later,
as they're all very useful usecases.

presentUIForSending is I think a good name for one of the usecases, and doesn't
easily conflict with the others two, which are more problematic: Would send()
(the current one), sendAndPresentUI() and presentUIForSending() be a triple
that make sense? I think that's cleaner than Will's original proposal of having
a bool parameter to send() which tells whether the UI should be presented or
not. That could be made better by using an enum { PresentUI, DontPresentUI }
and including a parameter which defaults to DontPresentUI, though - please
consider which of these look better, and if it's the bool or enum variant, add
that parameter as a placeholder to send() for now.

Will's proposal from the observer bug to include the actual TextChannel the
events happen on is a good one IMO. Doing that, one can take the channel up for
further observation, e.g. for observing remote chat state changes on the
channel. If we don't signal the Channel, a Client wanting to do such a thing
would need to go the full way of implementing AbstractClientObserver
themselves. We can signal it at no cost, since we've already had to build it to
get the signals in the first place. If it's the last argument of the signal,
you can also totally ignore it in applications if desired due to Qt's extra
signal argument ignore rule. You can also use the actual channel the event
happened at to get the Contact object, if needed.

We can implement the observer the same way as you implemented the Handler for
the R&H API: creating a private ClientRegistrar with a fake account factory
returning just the account this ContactMessenger was constructed for. The
factory needs to be altered a bit though, because we can't register an observer
filter just for a single Account - we'll be invoked for text channels for all
Accounts which coincidentally have an equal target ID (but can be a different
contact!). We'll just need to ignore these client-side, without failing or
warning at the factory (so change it to return a non-ready Account proxy for
the signaled object path, and in the observeChannels implementation ignore
channels for which the Account proxy is not the expected one?).

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



More information about the telepathy-bugs mailing list