Dispatching channels
====================

.. contents::

Incoming 1-1 text chats
-----------------------

_`dis1`: Incoming 1-1 text chat
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet receives a message from Romeo that starts a new channel. Her desired
UI resembles that of Empathy and of the Nokia internet tablets:

* an icon flashes in the system tray, altering her to the incoming message
  in an unobtrusive way

* when she clicks on the icon, a chat window opens

* all incoming and outgoing messages are logged for later searching

Current implementation, _`dis1impl1`::

    NewChannel (Text, CONTACT, handle("romeo@montague.verona.fict"),
        suppress_handler=FALSE)

    Mission Control runs filters, which include the blinking "new message"
    icon in the system tray

    When the tray icon is clicked, Mission Control continues processing
    filters and eventually dispatches to the channel handler

Problems:

* We want a logger (which might be in a separate process) to be told to
  handle incoming text channels. This may require that:

  - the logger is a filter; or
  - multiple channel handlers are supported (we launch the UI and the logger
    simultaneously); or
  - the UI starts the logger (good if the UI uses the logger, e.g. is just
    a view onto the logging database); or
  - the logger starts the UI (we won't do this, it's a layering violation)

  If there is a logger, only it should be acknowledging messages (there
  will be problems if both the logger and the UI try to ack messages).
  This is conceptually rather odd if the logger is a filter.

* The logger should be started immediately, without waiting for the
  new conversation to be accepted

* As currently implemented, if MC crashes, filters are forgotten and the
  "new message" notification is skipped in future - the chat window
  pops up straight away, possibly stealing focus (bad!)

* As currently implemented, if Empathy crashes and is restarted,
  its filter will end up registered twice, so the user has to click the
  incoming message icon twice

Alternative implementation, _`dis1impl2`:

* The UI and the logger are both channel handlers, or the UI is a channel
  handler and the logger is a filter

* There is no filter, except possibly the logger

* The blinking notification icon is provided by the UI, guaranteeing
  that it always appears and that focus is never stolen

Problems with this alternative implementation:

* The chat UI may take a while to start, particularly on slow embedded
  devices; we don't really want to pay this "cost" for conversations that the
  user is going to reject anyway. This could be solved by making the primary
  UI a very small launcher which just blinks the notification icon, then
  executes the real handler as a subprocess, via exec(2) or via dlopen(3) if
  needed

Proposed implementation:

* The logger is an Client and a Client.Observer

* The tray icon is a Client and a Client.Approver

* The chat UI is a Client and a Client.ChannelHandler

_`dis2`: Incoming 1-1 text message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet receives a message from Romeo after a pause in their conversation.

Current implementation: it arrives in the Text channel

Problems:

* If Juliet's chat UI has crashed, the message is (as currently implemented)
  lost forever

* If the chat UI is not currently visible, as currently implemented it
  cannot necessarily use the same mechanism to notify the user that would
  be used for a new channel, because it doesn't "own" the notification
  mechanism for the new-channel case (this would be fixed by dis1impl2_)
  (call this _`dis2problem2`)

Alternative implementation, _`dis2impl2`:

* When a ChannelHandler that was handling a channel closes, the channel
  dispatcher forcibly closes that channel

Problems:

* Incoming messages might be lost (there is a race)

Alternative implementation, _`dis2impl3`:

* When a ChannelHandler that was handling a channel closes, the channel
  dispatcher re-dispatches that channel (to the same or a different handler)

_`dis3`: Incoming 1-1 text message with window closed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After a pause in a conversation with Romeo, Juliet closes the IM window
or tab. She then receives another message from Romeo, resuming the
conversation.

Current implementation in Empathy, _`dis3impl2`:

* The Text channel is closed (depending on protocol, this may be visible to
  the remote user, e.g. MSN's "Juliet has closed the window")

* As a result, the new message is indistinguishable from a new channel (dis1_)

Problems:

* Not associated with the previous chat session, although this could be fixed
  with "conversation thread IDs"

* Zdra doesn't think the Chat UI should Close() text channels, although
  in ``Message-ID: <1209127037.6294.41.camel@zdra-laptop>`` he doesn't
  provide any rationale or use cases. (Zdra, could you explain please?)

Alternative implementation, _`dis3impl3`:

* the same as dis3impl1_, but use the same notification icon as for a
  new channel (dis1_), and only pop up the main chat UI window if accepted

* in practice this would give basically the same UI as for dis3impl2_, but
  without actually closing the channel

Problems:

* if it is desirable to tell the remote user that the window has been closed,
  the CM can't know

* dis2problem2_ also applies here

Incorrect implementation, _`dis3impl1`:

* The Text channel is not closed

* The new message causes the chat window to pop up, possibly stealing focus

Problems:

* Focus stealing is likely

_`dis4`: Incoming 1-1 text chat thread
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

While talking to Romeo in one IM window or tab, Juliet receives a message
from him in a separate "thread" of conversation.

Current implementation: impossible on protocols where 1-1 chats are not
just a special case of ad-hoc chatrooms, since we guarantee uniqueness
per (handle type, handle, channel type) for all handle types except NONE

Proposed implementation:

* The new thread is announced as a separate ChannelBundle (channels in each
  bundle have a ThreadID property)

* The new thread is dispatched to observers, approvers and the handler
  separately

_`dis5`: Incoming 1-1 text chat thread related to a VoIP call
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo over VoIP; there is no text channel open between
them. Romeo sends Juliet a text chat message (e.g. to send her a URI instead of
having to spell it out verbally), which should appear in the same
UI as the VoIP call if possible.

Current implementation: impossible, we have no representation for related
channels

Sub-cases exist, some of which are more problematic:

_`dis5a`: Juliet's VoIP UI also supports Text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Proposed implementation:

* The new Text channel is announced with the same bundle ID as the old
  VoIP channel; observers are invoked

* The channel dispatcher notices that Juliet's UI (which is the
  handler for this bundle) supports Text channels, and tells it to handle
  the new Text channel too. Approvers are not invoked

_`dis5b`: Juliet's VoIP UI does not support Text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Proposed implementation:

* The new Text channel is announced with the same bundle ID as the old
  VoIP channel; observers are invoked

* The channel dispatcher notices that Juliet's UI (which is the
  handler for this bundle) does not support Text channels, and falls back
  to splitting the channel bundle: the new channel goes to approvers and to
  a channel handler

_`dis5c`: "the same UI" is not unique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Suppose Juliet has two channel handlers:

* Empathy: supports text and VoIP, currently in use for VoIP
* TChat: supports text and file transfers

Suppose that Romeo sends Juliet a file transfer offer, then a Text message.
Juliet's channel dispatcher sees the following:

* initially, there is a VoIP channel C1 in a bundle B, handled by Empathy
* next, there is a FT channel C2 in a bundle B. Empathy cannot handle it,
  so according to `dis5b`_, only TChat is offered to approvers.
  Juliet accepts the file transfer and it is handled by TChat
* now the Text channel, C3, appears. What happens to it? Is it handled by
  Empathy or by TChat without running approvers, or are they both offered to
  approvers?

_`dis5d`: not a channel handler
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Suppose that Juliet's UI got the channel via use-case req1_. No approver
or handler was ever invoked, so how does Juliet's channel dispatcher
know that that UI should get subsequent channels?

(The same issue exists in the proposed API if an approver calls Claim().)

.. _req1: request.html#req1

_`dis6`: Incoming 1-1 text chat thread related to a collaborative app
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mercutio is collaborating on a document with Romeo using AbiWord and Tubes;
there is no text channel open between them. Romeo sends Mercutio some review
comments, which should appear in a chat UI embedded inside AbiWord.

Current implementation: impossible, we have no representation for related
channels

Proposed implementation: the same as dis5_, with the same problems

Invitations to named chatrooms
------------------------------

_`dis7`: Incoming named-chatroom invitation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo is invited to a named chatroom by Mercutio.

Current implementation::

    NewChannel (Text, ROOM, handle("The Capulets' ball"),
        suppress_handler=FALSE)

    Mission Control runs filters, which include a notification
    icon in the system tray

    When the tray icon is clicked, Mission Control continues processing
    filters and eventually dispatches to the channel handler

    The channel handler moves Romeo from local-pending to members.

Problems and variations: same as dis1_

_`dis14`, _`dis28`: Forcibly joining a chatroom
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Benvolio connects to an irssi-proxy, bip or other IRC bouncer running on some
colo box somewhere. The proxy informs his client that he is already in
#telepathy and #farsight.

Current implementation: same as dis7_, but Benvolio is already in the members
set for those channels.

Problems:

* Empathy's filter (notification icon) considers these channels to be incoming
  and waits for the first received message before blinking the status icon,
  which means Benvolio thinks his proxy instance has lost its connection
  to those channels

Issues to bear in mind:

* These Text channels are neither incoming nor outgoing - they are in
  a third state, "automatically created". In the current version of
  tp-spec-smcv-requests they would have state Channel_Direction_Automatic,
  the same as contact groups and contact lists.

Incoming VoIP calls
-------------------

_`dis8`: Incoming VoIP call
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo receives a VoIP call from Juliet. He answers.

Current implementation: similar to dis1_, but the channel has type
StreamedMedia, handle type NONE and handle 0; all the UI components must
investigate the channel's Group interface to find out who's calling.

Problems:

* The Group interface is unnecessarily complex just to find out who's calling

Proposed implementation:

* The channel has properties ...Channel.InitiatorHandle,
  ...Channel.InitiatorID which indicate Juliet's handle and ID
  (JID, SIP URI, etc.) immediately

_`dis9`: Missed incoming VoIP call
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo receives a VoIP call from Juliet. He does not answer, and Juliet
eventually gives up and cancels the call.

Current implementation: as for dis8_

Problems:

* Information can be lost, depending on timing
  (https://bugs.freedesktop.org/show_bug.cgi?id=14606)

Proposed implementation:

* The channel has properties ...Channel.InitiatorHandle,
  ...Channel.InitiatorID which indicate Juliet's handle and ID
  (JID, SIP URI, etc.) immediately

_`dis10`: Incoming VoIP call related to some other channel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo over text chat. Romeo decides that he can't bear
to not hear her voice, and starts a VoIP call. Juliet wants controls for the
VoIP call to appear in the same UI that she's already using.

Current implementation: the call is indistinguishable from dis8_

Problems: Juliet can't get the UI she wants

Proposed implementation: the reverse of dis5_, with the same issues

Contact lists
-------------

_`dis11`: A contact list is found during login
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo logs on to an IM service. As part of the connection process,
contact list channels for the various predefined CONTACT_LIST handles,
e.g. subscribe, are created automatically by the connection manager,
as specified by the Telepathy API.

Current implementation::

    NewChannel (ContactList, LIST, handle("subscribe"),
        suppress_handler=FALSE)

    Mission Control dispatches to the channel handler

Problems:

* Can we register more than one channel handler for contact lists? Every
  process with a contact-list UI might be interested in them - or not, since
  best practice is to request the contact lists that you want to use

* On Maemo devices, the address-book synchronization process is currently
  a handler for contact lists - this excludes the possibility of a third-party
  process that does the same thing

Best-practice solution:

* Clients SHOULD NOT be channel handlers for contact lists; clients SHOULD
  explicitly request any contact list channels that they want to use

* Perhaps clients interested in contact lists should be observers instead?

_`dis12`: A user-defined contact group is found during login
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo logs on to an IM service. As part of the connection process,
contact list channels are created automatically by the connection manager
for all the GROUP handles he has previously defined, as specified by the
Telepathy API.

Current implementation::

    NewChannel (ContactList, GROUP, handle("Montagues"),
        suppress_handler=FALSE)

    Mission Control dispatches to the channel handler

Problems:

* Can we register more than one channel handler for groups? Every process
  with a contact-list UI might be interested in them

Possible solution: in processes with a contact-list UI, use the
AccountManager API to find active connections, then use
NewChannel/ListChannels to find any (ContactList, GROUP) channels

_`dis13`: A user-defined contact group is created
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo is connected to the same XMPP account using his PC and his N800.
He uses the PC to create a contact group, "My true love", and adds Juliet
to it. On the N800 he expects the new group to appear automatically.

Current implementation::

    NewChannel (ContactList, GROUP, handle("My true love"),
        suppress_handler=FALSE)

    Mission Control dispatches to the channel handler

Problems: same as dis12_

Possible solution: same as dis12_

Invitations to ad-hoc chatrooms
-------------------------------

_`dis15`: Invitation to an ad-hoc chatroom with one user
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet receives a message from Romeo using MSN,
in which "1-1" conversations are actually ad-hoc chatrooms with exactly
two members. She would like this to be indistinguishable from Romeo sending
her a message over XMPP, in which 1-1 conversations are really 1-1.

Current implementation::

    NewChannel (Text, NONE, 0, suppress_handler=FALSE)

    The channel is passed through filters, etc.

Problems:

* Same as dis8_ and dis1_ combined

* It's unclear whether Juliet should be in member or local-pending state
  in the new channel

_`dis16`: Invitation to an ad-hoc chatroom with multiple users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo receives an invitation to join an ad-hoc chatroom currently
containing Mercutio and Benvolio.

Current implementation::

    NewChannel (Text, NONE, 0, suppress_handler=FALSE)

    The channel is passed through filters, etc.

Problems:

* Same as dis15_, but the desired state (member vs local pending) might be
  different

_`dis17`: Upgrading a 1-1 chat to a named or ad-hoc chatroom
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mercutio is talking to Benvolio in a 1-1 chat. Benvolio upgrades the
chat to a chatroom in order to invite Romeo to join in.

Current implementation: none

File transfers
--------------

_`dis18`: Receiving a file in the context of a conversation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo using a text or VoIP UI when he sends her
a file in the context of that conversation. If it implements file transfer
functionality, the text or VoIP UI should handle the file transfer; otherwise,
the channel dispatcher should fall back to launching a standalone file
transfer handler.

Proposed implementation and problems: same as dis5_

_`dis19`: Receiving a file unexpectedly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is not interacting with Romeo when he sends her a file. Some
appropriate UI needs to be launched to indicate that the file has been
offered.

Proposed implementation: same as dis1_

_`dis20`: Receiving a file in a collaborative application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

File transfers might be a useful model for collaborative applications
to use to transfer snapshots of state, or to transfer related files
(e.g. in a word processor, you could receive an inline image that is
embedded in the document).

Proposed implementation: same as dis6_

Additional problems: if the file transfer is part of the word processor's
IPC mechanism, then it *really* wants to get the file transfer, rather than
having another process get it as a result of a situation like dis5c_

Tubes
-----

_`dis21`: Invited to One Laptop per Child Activities, as of early 2008
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An OLPC Activity instance encapsulates an instance of an application,
zero or more D-Bus tubes and zero or more stream tubes to transfer messages
or state between participants, and a text chatroom to discuss the activity.

In the "1.0" protocol used in early 2008, each Activity instance is backed
by an XMPP or Clique_ MUC (chatroom).

Current implementation: we assume that the channels (Tubes, ROOM, foo)
and (Text, ROOM, foo) correspond 1:1. Activity discovery is done out-of-band
using OLPC-specific extensions, although we'd like to make some of it
more standard (mainly invitations).

Problems:

* we don't want Tubes channels in their current form, since dispatching them
  is likely to be a bit of a nightmare if we can't rely on OLPC assumptions;
  we want one channel per Tube instead

* in a less constrained environment, two different collaborative applications
  could conceivably share a MUC (the OLPC UI can't cause this to happen, but
  would likely get incredibly confused if it did)

.. _Clique: http://telepathy.freedesktop.org/xmpp/clique.html

Proposed implementation:

* Each Tube is its own channel

* OLPC Activities map 1:1 to conversation threads

* For compatibility with older OLPC code, we place each activity thread
  in a new chatroom

* For compatibility with older OLPC code, the Tubes channel type still exists
  in a deprecated state

_`dis22`: Invited to be a client in an existing UDP/TCP client/server protocol
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(Use-cases req24, req25)

Tybalt asks Juliet to help him fix a problem with his computer, and offers
her a VNC connection to his computer so she can interact with his desktop.

- or -

Romeo offers Mercutio and Benvolio access to an OpenArena server running
on his local computer.

Proposed implementation:

* Each TCP/UDP Tube is its own channel, with a thread ID associated with it

Failures and other exceptional cases
------------------------------------

_`dis23`: Client-side blocking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rosalind has blocked messages and calls from Romeo. However, her IM service
does not support server-side blocking, so her client must implement blocking
on the client side.

(A similar approach can be used to implement other privacy models, such as
"only allow messages from contacts on my publish list".)

Current implementation: a filter in Mission Control 4.x

Proposed implementation: a filter (dlopen()ed or hard-coded) in Mission
Control 5.x - we do not propose to allow this sort of thing over D-Bus

Miscellaneous
-------------

_`dis24`: multiple notification mechanisms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(From Frederic Peters on the mailing list)

Frederic wants to see IM messages appear as some sort of overlay when Totem
is running full-screen.

Problems:

* Having Totem, mplayer, OpenArena and every other full-screen app know about
  Telepathy messages, gnome-power-manager low-battery warnings and every other
  source of notifications doesn't really scale. Can't we solve this at the
  level of the fd.o Desktop Notification spec instead?

Proposed implementation:

* any application that really wants to know about Telepathy channels can be
  an Approver

_`dis29`: multiple notification mechanisms (2)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Telepathy gnome-panel applet needs to be able to indicate incoming calls or
channels. The Empathy contact list window should also be able to indicate
incoming calls or channels, e.g. by highlighting the contact.

Proposed implementation: they're both Approvers

_`dis25`: brightness on portable devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(From the Nokia Internet Tablets, but also generally applicable)

Naba's Internet tablet dims the screen when not in use. When a message
or call comes in, the screen backlight should come up to normal brightness.

Current implementation: a filter in Mission Control 4.x?

Problems: is this really just a special case of dis24_?

Proposed implementation: either a filter in Mission Control 5.x, or the
device-state service (which handles the backlight) can be made an Observer

_`dis26`: multiple channel handers available - 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo has both Kopette and Empathy installed on his system and both clients are
able to handle text channels. Romeo wants to be able to choose between kopette
and empathy just like he can choose between epiphany and firefox to handle http
urls (see gnome-default-applications-properties).

Problems:

* There is no way currently to choose between channel handlers, Mission Control
  4.x only accepts one chandler.

Proposed implementation:

* Approvers can select which one to use from among several possible channel
  handlers

_`dis27`: multiple channel handers available - 2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo has both Empathy and Elisa installed. When elisa is running fullscreen he
wants it to handle outgoing and incoming calls, otherwise he wants empathy to
handle them.

Problems:

* There is no way currently to choose between channel handlers, Mission Control
  4.x only accepts one chandler.
* Empathy's filter will get the media channel before elisa's chandler, so the
  status icon will blink and Romeo won't see it because elisa is running
  fullscreen.

Proposed implementation:

* elisa is an Approver which claims incoming channels using Claim(). The
  Empathy status icon blinks momentarily, but this is not visible, and because
  there is no user action, Empathy never approves anything

..
  vim:set sw=4 sts=4 et:
