[Telepathy] Requestotron use-cases, part 1 (requests, not including Tubes or FT)

[Simon McVittie]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Here's a first round of use-cases for the improved RequestChannel API.
This part only covers requests (not incoming things needing dispatching)
and doesn't cover Tubes or file transfers (because they're hard and I'll
think about them later).

HTML at <http://people.collabora.co.uk/~smcv/request.html>, Darcs branch
at <http://monkey.collabora.co.uk/tp-spec-smcv-usecases> (it's written
in reStructuredText), current text later in this email for easy quoting.

Please reply with any comments or extra use cases for requested/outgoing
channels that are not Tubes or FT. I'll start a new thread for "simple"
incoming channels when I've written it up, and another for Tubes and FT
(which are considerably harder).

Regards,
    Simon

Requesting channels
===================

.. contents::

Outgoing 1-1 text chat
- ----------------------

_`req1`: Chat from chat UI
~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo has a chat or IM UI open already, and wants to use it to chat to Juliet.
He selects Juliet from a contact list or types in her username on some IM
service.

Current implementation::

    if a channel with GetHandle() -> (CONTACT, juliet) exists:
        foreground its window or tab
    else:
        RequestChannel (Text, CONTACT, juliet, suppress_handler=TRUE)

_`req2`: Chat from elsewhere
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet wants to talk to Romeo. She chooses his entry in an address book
or other list of people (not necessarily Telepathy-centric) and is presented
with a list of possible ways to talk to him. She decides to use text chat.

Current implementation::

    address book asks Mission Control for a channel with
        (Text, CONTACT, romeo)
    Mission Control calls RequestChannel (Text, CONTACT, romeo,
        suppress_handler=FALSE) on CM
    Mission Control dispatches the channel to the default/only handler

    if the channel is new:
        the channel handler creates a new window or tab
    else:
        the channel handler puts the existing window or tab in the foreground

Problems:

* It's rather bizarre that Mission Control re-dispatches an existing channel
  as though it was new

* It's very bizarre that the channel handler interprets HandleChannel on a
  channel it's already handling as "put it in the foreground". If we mean
  "put this in the foreground" we should say so.

_`req3`: collaborative app
~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo is collaborating on a document with Mercutio, and wants to have a chat
embedded in his AbiWord instance, separate from any other chat with Mercutio
that may be ongoing.

Current implementation: impossible, even in protocols supporting
conversation threads, because the spec can't represent them

Outgoing VoIP call
- ------------------

_`req4`: Call from call UI
~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo has a VoIP UI open already, and wants to use it to chat to Juliet.
He selects Juliet from a contact list or types in her username on some IM
service.

Theoretical implementation::

    if a channel containing handle juliet exists:
        foreground its window or tab
    else:
        RequestChannel (StreamedMedia, NONE, 0, suppress_handler=TRUE)
        RequestStreams (juliet, [AUDIO, VIDEO])

Problems:

* This is what the spec says we should do, but it doesn't actually work yet,
  at least in telepathy-gabble
  <https://bugs.freedesktop.org/show_bug.cgi?id=14602>
* Finding out whether a channel containing juliet's handle exists is
  needlessly laborious
* Unless the VoIP UI keeps a table of (handle => channel) (which can't
  necessarily be done - some protocols allow "parallel" calls), the following
  race condition::

    choose to call Juliet
    RequestChannel (StreamedMedia, NONE, 0, suppress_handler=TRUE) (request A)
    choose to call Juliet
    RequestChannel (StreamedMedia, NONE, 0, suppress_handler=TRUE) (request B)
    Request A returns /.../ChannelA
    Request B returns /.../ChannelB

  can result in unnecessarily opening two parallel calls to the same contact

Practical implementation::

    if a channel containing handle juliet exists:
        foreground its window or tab
    else:
        RequestChannel (StreamedMedia, NONE, 0, suppress_handler=TRUE)
        AddMembers ([juliet])
        RequestStreams (juliet, [AUDIO, VIDEO])

Problems:

* Same needlessly laborious processing as in the theoretical implementation
* Same race condition as in the theoretical implementation
* Juliet appears in the remote-pending set before any attempt has really
  been made to call her, which is misleading

Deprecated implementation::

    if a channel containing handle juliet exists:
        foreground its window or tab
    else:
        RequestChannel (StreamedMedia, CONTACT, juliet, suppress_handler=TRUE)
        RequestStreams (juliet, [AUDIO, VIDEO])

Problems:

* All the problems of the practical implementation
* Implementors might be misled into thinking that the semantics resemble
  text channels more closely than they really do

_`req5`: Call from elsewhere
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet wants to talk to Romeo. She chooses his entry in an address book
or other list of people (not necessarily Telepathy-centric) and is presented
with a list of possible ways to talk to him. She decides to use a VoIP call.

Current implementation::

    RequestChannel (StreamedMedia, NONE, 0, suppress_handler=FALSE)
    perhaps AddMembers ([romeo])
    RequestStreams (romeo, [AUDIO, VIDEO])

    The channel handler creates a new window or tab for the new channel

Problems:

* The requester has to keep interacting with the channel, it's not
  "fire and forget"
* Creates a new channel, which is unlikely to be what Juliet wanted

Deprecated (?) implementation::

    ask Mission Control for a channel (StreamedMedia, CONTACT, romeo)
    Mission Control does... something?

Problems:

* Mission Control doesn't know whether to use an existing channel to Romeo,
  or create a new one (using an existing channel is *probably* right)
* Looking for channels to talk to Romeo is hard (have to interact with lots of
  group interfaces)

_`req6`: collaborative app
~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo is collaborating on a document with Mercutio, and wants to have a chat
embedded in his AbiWord instance, separate from any other chat with Mercutio
that may be ongoing.

Current implementation: same as req5_

Problems: same as req5_

Joining a chatroom by request
- -----------------------------

_`req7`: joining chatroom from chatroom UI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tybalt starts an IRC-style chatroom client and wants to join a chatroom, either
by explicit request or because his client auto-joins his favourite rooms.

Current implementation::

    if a channel with GetHandle() -> (ROOM, chatroom_handle) exists:
        foreground its window or tab
    else:
        RequestChannel (Text, ROOM, chatroom_handle, suppress_handler=TRUE)

Problems:

* Tybalt doesn't get a chance to choose his nickname before joining

_`req8`: joining chatroom from elsewhere
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Benvolio chooses to rejoin a recently-used chatroom from (hypothetical
functionality of) the GNOME Places menu.

Current implementation::

    GNOME menu asks Mission Control for a channel with
        (Text, ROOM, chatroom_handle)
    Mission Control calls RequestChannel (Text, ROOM, chatroom_handle,
        suppress_handler=FALSE) on CM
    Mission Control dispatches the channel to the default/only handler

    if the channel is new:
        the channel handler creates a new window or tab
    else:
        the channel handler puts the existing window or tab in the foreground

Problems:

* As for req7_, Benvolio doesn't get a chance to choose his nickname before
  joining

* As for req2_, it's rather bizarre that Mission Control re-dispatches an
  existing channel as though it was new

* As for req2_, it's very bizarre that the channel handler interprets
  HandleChannel on a channel it's already handling as "put it in the
  foreground"

Listing chatrooms
- -----------------

_`req9`: listing chatrooms on "home" server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo wants to list all the chatrooms on the server or service that hosts his
account.

Current implementation::

    RequestChannel (RoomList, NONE, 0, suppress_handler=TRUE)

Notes:

* There doesn't seem to be any use case for suppress_handler=FALSE here,
  since a default handler for chatroom lists doesn't really make sense

Problems:

* Gabble implements this badly, by treating the room list as a singleton

* Some protocols (IRC!) are terrible, and on these, the room list actually
  *is* a singleton

_`req10`: listing chatrooms on "foreign" server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo wants to list all the chatrooms on the server that hosts Juliet's
account.

Current implementation: impossible

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

_`req11`: typical contact list UI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Current best-practice to get contact lists (should not use ListChannels
and NewChannel, cf my conversation with Zdra in #telepathy on 2008-04-25)::

    RequestChannel (ContactList, CONTACT_LIST, handle("subscribe"))
    RequestChannel (ContactList, CONTACT_LIST, handle("publish"))
    RequestChannel (ContactList, CONTACT_LIST, handle("hide"))
    RequestChannel (ContactList, CONTACT_LIST, handle("allow"))
    RequestChannel (ContactList, CONTACT_LIST, handle("deny"))

Current best-practice to get initial user-defined groups::

    ListChannels ()

(finding new groups will be part of the "incoming" use cases list)

Problems:

* Slightly unclear whether suppress_handler should be TRUE or FALSE -
  depends on "incoming" use cases

_`req12`: creating a user-defined contact group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Current implementation::

    RequestChannel (ContactList, GROUP, handle("Colleagues"),
        suppress_handler=FALSE)

..
  vim:set sw=4 sts=4 et:
-----BEGIN PGP SIGNATURE-----

iD8DBQFIEfrwWSc8zVUw7HYRAjt0AKDKsrjRIoR60qY80pOIppApxSTNwQCaAprv
JlZvE20N36VOBaGfXceWHF0=
=4mR2
-----END PGP SIGNATURE-----