doc/request.txt: remove uncontroversial cases

1 files changed, 0 insertions, 1217 deletions

diff --git a/doc/request.txt b/doc/request.txt
index f3292716..ee98658f 100644
--- a/doc/request.txt
+++ b/doc/request.txt
@@ -3,232 +3,6 @@ Use cases for 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)
-
-Proposed implementation::
-
-    if a channel with TargetHandleType == CONTACT and TargetHandle == juliet
-    is being handled by the chat UI:
-        foreground its window or tab (no interaction with the
-            ChannelDispatcher)
-        stop here
-        (note: this check is optional, the process below can cope with
-        the case where the chat UI is already handling the desired channel)
-
-    chat UI calls ChannelDispatcher.EnsureChannel(
-        account,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': juliet
-        },
-        timestamp,
-        its_own_bus_name
-    )
-    chat UI connects to signals and calls ChannelRequest.Proceed()
-
-    ChannelDispatcher calls AddRequest on chat UI, chat UI ignores it
-        as the request is already known to it
-
-    try:
-        ChannelDispatcher tells AccountManager to put account online
-        ChannelDispatcher calls EnsureChannel ({...same arguments...})
-    on success, with Yours = TRUE:
-        channel observers run (if and only if NewChannels emitted)
-        ChannelRequest emits Succeeded, chat UI ignores its arguments
-        channel approvers do not run
-        CD calls HandleChannels on chat UI
-        chat UI handles channel
-    on success, with Yours = FALSE:
-        if we're already handling this channel:
-            foreground it
-        else:
-            chat UI isn't allowed to handle the channel (someone else is)
-            CR emits Failed and CD calls RemoveFailedRequest
-                with error o.fd.T.E.NotYours
-            FIXME: could perhaps try calling CreateChannel to get a new thread?
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on chat UI, and
-            ChannelRequest emits Failed
-        chat UI displays failure
-
-_`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.
-
-:New vs. existing:
-    Existing channel preferred, new channel acceptable
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is CONTACT, TargetHandle is romeo
-
-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
-
-Things smcv considered to be problems:
-
-* It's rather bizarre that Mission Control re-dispatches an existing channel
-  as though it was new (proposed solution: a Present() method instead)
-
-  * Resolution: Rob does not consider this to be a problem, overruled
-
-* 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 (proposed solution: do so)
-
-  * Resolution: Rob does not consider this to be a problem, overruled
-
-Proposed implementation::
-
-    address book calls ChannelDispatcher.EnsureChannel(
-        account,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': romeo,
-        },
-        timestamp,
-        ''
-    )
-    address book connects to signals and calls ChannelRequest.Proceed
-
-    ChannelDispatcher calls AddRequest on chat UI, which makes a new tab
-    (if it is not already handling such a channel)
-
-    [+]
-
-    try:
-        ChannelDispatcher tells AccountManager to put account online
-        ChannelDispatcher calls EnsureChannel ({...same arguments...})
-    on creation of new channel:
-        channel observers run
-        ChannelRequest emits Succeeded, address book ignores its arguments
-        channel approvers do not run
-        CD calls HandleChannels on chat UI
-        chat UI handles channel
-    on return of existing channel:
-        (this is req2a)
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on chat UI (1)
-        ChannelRequest emits Failed (2)
-        chat UI displays failure in response to (1)
-        address book displays failure in response to (2)
-
-_`req2a`: already-approved channel returned by repeated request
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-After use-case req2_ has happened, Juliet loses the chat window somewhere
-on her desktop (but it is still open). She wants to continue to talk to Romeo,
-and chooses his entry in her address book again.
-
-Proposed implementation::
-
-    initially the same as for req2 (until [+])
-
-    ChannelDispatcher tells AccountManager to put account online
-    ChannelDispatcher calls EnsureChannel ({...same arguments...})
-    CM returns existing channel
-    ChannelRequest emits Succeeded, address book ignores its arguments
-    channel observers and approvers do not run
-    CD calls HandleChannels on handler of existing channel
-    handler of existing channel brings channel to foreground
-
-_`req2b`: unapproved channel returned by redundant request
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Juliet is about to open a text conversation with Romeo as per req2_, when
-Romeo sends her a message as in dis1_. Instead of responding to the
-"new message" notification, she continues to select "Chat with Romeo" in her
-address book.
-
-The intended result is that there is exactly one Text channel talking to
-Romeo.
-
-.. _dis1: dispatch.html#dis1
-
-Proposed implementation::
-
-    New channel comes in:
-        CM emits Requests.NewChannels([(channel_path,
-            {
-                '...ChannelType': '...Text',
-                '...TargetHandleType': CONTACT,
-                '...TargetHandle': 1234,
-                '...TargetID': 'romeo@montague.example.com',
-                '...Requested': FALSE,
-                ...
-            },
-            )])
-
-        In response, CD calls ObserveChannels on all matching Observers,
-        including org.freedesktop.Telepathy.Client.EmpathyLogger
-
-        CD creates a ChannelDispatchOperation [cdo1]
-
-        CD calls AddDispatchOperation on all matching Approvers, including
-        org.freedesktop.Telepathy.Client.EmpathyTrayIcon
-
-        Empathy tray icon flashes
-
-    Juliet tells address book to open a channel to Romeo:
-
-        address book calls ChannelDispatcher.EnsureChannel(
-            account,
-            {
-                '...ChannelType': '...Text',
-                '...TargetHandleType': CONTACT,
-                '...TargetHandle': romeo,
-            },
-            timestamp,
-            ''
-        ) (this returns cr1, say)
-        address book calls ChannelRequest.Proceed() on cr1
-
-        ChannelDispatcher calls AddRequest on chat UI, which makes a new tab
-
-        ChannelDispatcher tells AccountManager to put account online (no-op)
-        ChannelDispatcher calls EnsureChannel ({...same arguments...})
-        CM returns existing channel
-
-        ChannelRequest cr1 emits Succeeded, address book ignores its arguments
-
-        CD considers the request for an existing channel to have constituted
-        approval of the CDO, so ChannelDispatchOperation cdo1 emits Closed
-
-        (At or before this point, the CD must wait for all the Observers to
-        return from ObserveChannels if they have not already done so)
-
-        CD SHOULD give the request's preferred handler precedence over the
-         CDO's in choosing the chat UI
-        CD calls HandleChannels on chat UI (service-activating it if needed)
-
 _`req3`: collaborative app
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -411,949 +185,6 @@ Proposed implementation: Juliet's client continues to use the same channel
 
 Problems remaining: how do we ensure that?
 
-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.
-
-:New vs. existing:
-    New channel required (same reasoning as req1_)
-:Definition of channel identity:
-    ???
-
-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
-
-Resolved problems:
-
-* 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.
-
-  (For instance: Empathy users sometimes incorrectly double-click on the
-  Call button, resulting in two calls.)
-
-  Resolution: UIs are responsible for not doing this. For instance, Empathy
-  should disable (make insensitive) the Call button just before requesting
-  a streamed media channel, and re-enable it when the request has either
-  failed or succeeded.
-
-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
-
-Proposed implementation: (FIXME: requires InitialAudio, InitialVideo in spec)
-
-::
-
-    if a streamed media call with Juliet is being handled by the call UI:
-        foreground its window or tab (no interaction with the
-        ChannelDispatcher)
-    else:
-        call UI calls ChannelDispatcher.CreateChannel(
-            account,
-            {
-                '...ChannelType': '...StreamedMedia',
-                '...TargetHandleType': CONTACT,
-                '...TargetHandle': juliet,
-                '...InitialAudioStream': TRUE,
-                '...InitialVideoStream': TRUE,
-            },
-            timestamp,
-            its_own_bus_name
-        )
-        call UI calls ChannelRequest.Proceed()
-
-        ChannelDispatcher calls AddRequest on call UI, call UI ignores it
-            as the request is already known to it
-
-        try:
-            ChannelDispatcher tells AccountManager to put account online
-            ChannelDispatcher calls CreateChannel ({...same arguments...})
-        on success:
-            channel observers run
-            ChannelRequest emits Succeeded, call UI ignores its arguments
-            channel approvers do not run
-            CD calls HandleChannels on call UI
-            call UI handles channel
-        on failure:
-            ChannelDispatcher calls RemoveFailedRequest on call UI, and
-                ChannelRequest emits Failed
-            call UI displays failure
-
-_`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.
-
-:New vs. existing:
-    Existing channel preferred? New channel acceptable
-:Definition of channel identity:
-    ???
-
-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)
-
-Proposed implementation: (FIXME: needs same extra API as req4_ and req2_
-combined)
-
-::
-
-    address book calls ChannelDispatcher.StartRequest
-    address book calls ChannelRequest.EnsureChannelByAccount(
-        account,
-        {
-            '...ChannelType': '...StreamedMedia',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': juliet
-            '...InitialAudioStream': TRUE,
-            '...InitialVideoStream': FALSE,
-        },
-        timestamp,
-        ''
-    )
-
-    ChannelDispatcher calls AddRequest on call UI, call UI makes a new tab
-
-    try:
-        ChannelDispatcher tells AccountManager to put account online
-        ChannelDispatcher calls EnsureChannel ({...same arguments...})
-    on creation of new channel:
-        channel observers run
-        ChannelRequest emits Succeeded, address book ignores its arguments
-        channel approvers do not run
-        CD calls HandleChannels on call UI
-        call UI handles channel
-    on return of existing channel:
-        ChannelRequest emits Succeeded, address book ignores its arguments
-        channel observers and approvers do not run
-        CD calls HandleChannels on handler of existing channel
-        handler of existing channel brings channel to foreground
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on call UI (1)
-        ChannelRequest emits Failed (2)
-        call UI displays failure in response to (1)
-        address book displays failure in response to (2)
-
-
-_`req6`: collaborative app
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo is collaborating on a document with Mercutio, and wants to have a call
-embedded in his AbiWord instance, separate from any other call with Mercutio
-that may be ongoing.
-
-Current implementation: same as req5_
-
-Problems: same as req5_
-
-Proposed implementation: same as req5_, but ask for a new channel in a
-bundle (like in req3_)
-
-_`req29`: Recovering from disconnection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo is talking to Juliet using VoIP, but is disconnected due to network
-instability. After reconnecting, he wants to keep using the same window to
-talk to Juliet.
-
-A solution for this use case should ideally work correctly (and result in
-a single channel) if there is a "mid-air collision" with Juliet doing the
-same thing, or with Juliet recovering from Romeo's disconnection as per
-req30_.
-
-(Recovering from a connection manager crash is equivalent to this.)
-
-Current implementation: same as req4_
-
-Problems:
-
-* the two conversations are unrelated (Juliet cannot distinguish
-  between this case and req4_)
-
-* if Juliet calls Romeo at the same time that Romeo calls Juliet, a
-  collision occurs and both calls probably fail with error BUSY
-
-Proposed implementation: same as req4_, revisit later if the problems are
-felt to be serious
-
-_`req30`: Recovering from other's disconnection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Juliet is talking to Romeo using VoIP when Romeo is disconnected
-due to network instability. After reconnecting, Juliet
-wants to keep using the same window to talk to Romeo.
-
-A solution for this use case should ideally work correctly (and result in
-a single channel) if there is a "mid-air collision" with Romeo doing the
-same thing, or with Romeo recovering from disconnection as per req29_.
-
-(Recovering from a connection manager crash is equivalent to this.)
-
-Current implementation: same as req4_
-
-Problems:
-
-* the two conversations are unrelated (Romeo cannot distinguish
-  between this case and req4_)
-
-* if Juliet calls Romeo at the same time that Romeo calls Juliet, a
-  collision occurs and both calls probably fail with error BUSY
-
-Proposed implementation: same as req4_, revisit later if the problems are
-felt to be serious
-
-Joining a named 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.
-
-:New vs. existing:
-    ???
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is ROOM, TargetHandle is #capulet
-
-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 addressed by proposed implementation:
-
-* Tybalt doesn't get a chance to choose his nickname before joining
-
-Proposed implementation: some new interface for this functionality is
-created, like Chan.I.Chatroom.
-
-::
-
-    if a channel with TargetHandleType == ROOM and TargetID == '#capulet'
-    is being handled by the chatroom UI:
-        foreground its window or tab (no interaction with the
-        ChannelDispatcher)
-    else:
-        chatroom UI calls ChannelDispatcher.StartRequest
-        chatroom UI calls ChannelRequest.CreateChannelByAccount(
-            account,
-            {
-                '...ChannelType': '...Text',
-                '...TargetHandleType': ROOM,
-                '...TargetID': '#capulet'
-                '...Channel.Interface.Chatroom.Nickname':
-                    'The Prince of Cats'
-            },
-            timestamp,
-            my_own_bus_name
-        )
-
-        ChannelDispatcher calls AddRequest on chatroom UI, which ignores it
-            as the request is already known to it
-
-        try:
-            ChannelDispatcher tells AccountManager to put account online
-            ChannelDispatcher calls CreateChannel ({...same arguments...})
-        on success:
-            channel observers run
-            ChannelRequest emits Succeeded, chatroom UI ignores its arguments
-            channel approvers do not run
-            CD calls HandleChannels on chatroom UI
-            chatroom UI handles channel
-        on failure:
-            ChannelDispatcher calls RemoveFailedRequest on chatroom UI, and
-                ChannelRequest emits Failed
-            chatroom UI displays failure
-
-Proplems remaining:
-
-* How do threads work? By analogy with 1-1 messaging, they should be
-  separate channels - is this really what we want?
-
-  Resolution: solve later, https://bugs.freedesktop.org/show_bug.cgi?id=16544
-
-_`req8`: joining chatroom from elsewhere
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Benvolio chooses to rejoin a recently-used chatroom from (hypothetical
-functionality of) the GNOME Places menu.
-
-:New vs. existing:
-    ???
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is ROOM, TargetHandle is #capulet
-
-Proposed implementation: ::
-
-    Places menu calls ChannelDispatcher.StartRequest
-    Places menu calls ChannelRequest.EnsureChannelByAccount(
-        account,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': ROOM,
-            '...TargetHandle': '#capulet'
-        },
-        timestamp,
-        ''
-    )
-
-    ChannelDispatcher calls AddRequest on chatroom UI, which makes a new tab
-    (if it is not already handling such a channel)
-
-    try:
-        ChannelDispatcher tells AccountManager to put account online
-        ChannelDispatcher calls EnsureChannel ({...same arguments...})
-    on creation of new channel:
-        channel observers run
-        ChannelRequest emits Succeeded, Places menu ignores its arguments
-        channel approvers do not run
-        CD calls HandleChannels on chatroom UI
-        chatroom UI handles channel
-    on return of existing channel:
-        ChannelRequest emits Succeeded, Places menu ignores its arguments
-        channel observers and approvers do not run
-        CD calls HandleChannels on handler of existing channel
-        handler of existing channel brings channel to foreground
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on chatroom UI (1)
-        ChannelRequest emits Failed (2)
-        chatroom UI displays failure in response to (1)
-        Places menu displays failure in response to (2)
-
-Listing named chatrooms
------------------------
-
-_`req9`: listing chatrooms on "home" server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo wants to list all the chatrooms on the server or service that hosts his
-account.
-
-:New vs. existing:
-    New (parallel) channel preferred, but might not be possible
-:Definition of channel identity:
-    None - the returned channel probably looks like one from req10_
-
-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
-
-Implementation problems not affecting design:
-
-* 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
-
-Proposed implementation: a straightforward port of the current API. In the
-returned channel, the Channel.Type.RoomList.Server property will be the
-actual server name, rather than empty
-
-_`req10`: listing chatrooms on "foreign" server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo wants to list all the chatrooms on the server ``capulet.example.com``
-that hosts Juliet's account.
-
-:New vs. existing:
-    New (parallel) channel preferred, but might not be possible
-:Definition of channel identity:
-    ChannelType is RoomList, RoomList.Server is capulet.example.com
-
-Current implementation: impossible
-
-Proposed implementation: in the request, set the Channel.Type.RoomList.Server
-property to the desired DNS name
-
-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
-
-Proposed implementation _`req11impl1`:
-
-* Everyone who cares about contact lists requests them with EnsureChannel
-
-* There is never a channel handler for contact lists
-
-* Are contact lists Requested or not? We just don't know
-
-Problems with req11impl1_:
-
-* If there is no channel handler, we need to make sure the channel
-  dispatcher won't treat this as an error, or panic and
-  try to close the channel
-
-_`req12`: creating a user-defined contact group
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Current implementation::
-
-    RequestChannel (ContactList, GROUP, handle("Colleagues"),
-        suppress_handler=FALSE)
-
-Proposed implementation: a straightforward port to EnsureChannel
-
-Ad-hoc chatrooms
-----------------
-
-This section refers to protocols like MSN, where what appears to be a 1-1
-conversation is actually just an unnamed chatroom into which other users
-can be invited.
-
-_`req13`: Chat from chat UI (MSN)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-(The same as req1_, but Romeo and Juliet are using a "fully correct" MSN
-implementation like telepathy-butterfly, or some similar protocol.)
-
-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.
-
-Proposed implementation: a channel with TargetHandleType == CONTACT and
-TargetHandle == juliet will definitely not already exist. Otherwise, exactly
-the same as req1_
-
-_`req31`: Recovering from disconnection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo is talking to Juliet using text chat, but is disconnected due to network
-instability. After reconnecting, he wants to keep using the same window to
-talk to Juliet.
-
-A solution for this use case should work correctly (and result in
-a single channel) if there is a "mid-air collision" with Juliet doing the
-same thing, with Juliet sending messages to Romeo while he is still
-offline (on store-and-forward protocols like XMPP), or with Juliet
-recovering from Romeo's disconnection as per req33_ (on protocols that
-do not allow offline messages).
-
-(Recovering from a connection manager crash is equivalent to this.)
-
-Current implementation: same as req13_
-
-Problems:
-
-* the two conversations are unrelated (Juliet cannot distinguish
-  between this case and req13_)
-
-* A mid-air collision is highly likely to result in two parallel
-  conversations with the same members (if this is even allowed by the
-  protocol)
-
-* the interaction with offline messages is quite scary
-
-Proposed implementation:
-
-* Ask other MSN implementors (Youness?) how they cope with the race
-  condition, and implement this in our MSN CMs
-
-_`req32`: Resuming a conversation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo chooses a past conversation with Juliet in a log browser and wants
-to resume it. (The definition of threading in XMPP expects that this is
-possible.)
-
-This is basically req31_ but for a different reason; I expect that the
-solution can be similar.
-
-Current implementation: same as req13_
-
-Problems: Juliet cannot distinguish between this case and req13_
-
-Resolution: not a serious problem
-
-_`req33`: Recovering from other's disconnection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Juliet is talking to Romeo using text chat when Romeo is disconnected
-due to network instability. The protocol is one that does not
-allow offline messages to be sent, like IRC. After reconnecting, Juliet
-wants to keep using the same window to talk to Romeo.
-
-A solution for this use case should work correctly (and result in
-a single channel) if there is a "mid-air collision" with Romeo doing the
-same thing, or with Romeo recovering from disconnection as per req31_.
-
-(Recovering from a connection manager crash is equivalent to this.)
-
-Proposed implementation: basically the same as req31_
-
-_`req14`: Ad-hoc chatroom from chat UI
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo wants to talk to both Mercutio and Benvolio in an ad-hoc chatroom.
-He selects them both from a contact list, or types in both their usernames.
-
-Problems:
-
-* Determining whether we already have an appropriate channel is race-prone
-  and inconvenient
-
-Proposed implementation: ignore this and only support req15_
-
-_`req15`: Ad-hoc chatroom preferred
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo wants to talk to both Mercutio and Benvolio in an ad-hoc chatroom.
-He selects Mercutio from a contact list, or types in Mercutio's username,
-then invites Benvolio to the chatroom too.
-
-Proposed implementation:
-
-* Request the channel to Mercutio in the same way as req1_/req13_
-
-* Add Benvolio using the Group interface in the obvious way
-
-(Rationale for not faking true 1-1 channels: once Benvolio has been added,
-we must have an ad-hoc chatroom with TargetHandleType = NONE. Since UIs will
-need to be able to cope with such channels anyway, we might as well start off
-with one.)
-
-_`req16`: Chat from address book (MSN)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-(The same as req2_, but Romeo and Juliet are using a "fully correct" MSN
-implementation like telepathy-butterfly, or some similar protocol.)
-
-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.
-
-Proposed implementation: the same as req2_
-
-_`req17`: Ad-hoc chatroom from address book
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The same as req14_ but from an address book.
-
-Proposed implementation: ignore this and only support the equivalent of req15_
-
-_`req18`: Ad-hoc chatroom embedded in collaboraborative 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.
-
-Possible implementation: the same as req3_
-
-_`req19`: Upgrading a 1-1 chat to a named or ad-hoc chatroom
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Same as http://www.xmpp.org/extensions/xep-0045.html §7.6. XMPP does this
-by using thread IDs.
-
-Current implementation: can't be done
-
-Proposed implementation: request a chatroom channel with the same (thread
-ID and) bundle ID as the 1-1 chat, or something (use of two channels is
-unavoidable here, because they have a distinct identity)
-
-Resolution: defer the threads spec til later,
-https://bugs.freedesktop.org/show_bug.cgi?id=16544
-
-File transfers
---------------
-
-_`req20`: Sending a file in the context of a conversation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo is talking to Juliet using a text or VoIP UI, and wishes to
-send Juliet a file in the context of that conversation.
-
-_`req20a`: Romeo's Text or VoIP UI also supports file transfers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Proposed implementation::
-
-    Let bundle_id be the value of the Bundle property of the existing
-    Text or StreamedMedia channel.
-
-    Romeo's UI calls ChannelDispatcher.StartRequest
-    Romeo's UI calls ChannelRequest.CreateChannelByAccount(
-        account,
-        {
-            '...ChannelType': '...FileTransfer',
-            '...TargetHandleType': CONTACT,
-            '...TargetID': 'juliet@capulet.example.com'
-            '...Bundle': bundle_id,
-            '...Channel.Type.FileTransfer.ContentType': 'image/png',
-            ...
-        },
-        timestamp,
-        my_own_bus_name
-    )
-
-    ChannelDispatcher calls AddRequest on Romeo's UI, which ignores it as
-        the request is already known to it
-
-    try:
-        ChannelDispatcher calls CreateChannel ({same dictionary as above})
-    on success:
-        channel observers run
-        ChannelRequest emits Succeeded
-        channel approvers do not run
-        CD calls HandleChannels on Romeo's UI which handles the transfer
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on Romeo's UI, and
-            ChannelRequest emits Failed
-        Romeo's UI displays failure
-
-_`req20b`: Romeo's Text or VoIP UI does not support file transfers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Proposed implementation::
-
-    Let bundle_id be the value of the Bundle property of the existing
-    Text or StreamedMedia channel.
-
-    Romeo's UI calls ChannelDispatcher.StartRequest
-    Romeo's UI calls ChannelRequest.CreateChannelByAccount(
-        account,
-        {
-            '...ChannelType': '...FileTransfer',
-            '...TargetHandleType': CONTACT,
-            '...TargetID': 'juliet@capulet.example.com'
-            '...Bundle': bundle_id,
-            '...Channel.Type.FileTransfer.ContentType': 'image/png',
-            ...
-        },
-        timestamp,
-        ''
-    )
-
-    ChannelDispatcher calls AddRequest on file transfer UI
-
-    try:
-        ChannelDispatcher calls CreateChannel ({same dictionary as above})
-    on success:
-        channel observers run
-        ChannelRequest emits Succeeded
-        channel approvers do not run
-        CD calls HandleChannels on file transfer UI, which handles the transfer
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on file transfer UI
-        ChannelRequest emits Failed => Romeo's UI displays failure
-
-_`req21`: Sending a file from a file manager
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo right-clicks on a file in his file manager, chooses a "Send to User"
-option and chooses to send it to Juliet.
-
-Proposed implementation: if the file manager is the channel handler, this is
-the same as req20a_, but with no bundle ID; otherwise it's the same as req20b_
-but with no bundle ID
-
-_`req22`: Sending a file automatically in a collaborative application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While collaborating on a document with Mercutio, Romeo inserts an embedded
-image into the document. The collaborative application could usefully choose
-to represent this by a file transfer.
-
-Proposed implementation: don't do this, use Tubes instead
-
-Tubes
------
-
-_`req23`: 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 addressed by proposed implementation:
-
-* 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:
-
-* Associate each Activity with a ChannelBundle using XMPP threading
-
-_`req24`: Existing UDP/TCP client/server protocol, serving one client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Tybalt asks Juliet to help him fix a problem with his computer. He offers
-her a VNC connection to his computer so she can interact with his desktop.
-
-Proposed implementation:
-
-* The TCP tube is a channel; much like req1_ or req2_
-
-_`req25`: Existing UDP/TCP client/server protocol, serving many clients
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo offers Mercutio and Benvolio access to an OpenArena server running
-on his local computer.
-
-Proposed implementation:
-
-* The UDP tube is a channel; much like req1_ or req2_
-
-Failures and other exceptional cases
-------------------------------------
-
-_`req34`: failing to send a text message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo opens a text channel to Juliet to send a message, but Juliet's server
-is down and Romeo's server signals failure. (This is mostly applicable to
-decentralized protocols like XMPP and SIP.)
-
-Current implementation::
-
-    the message is sent
-    SendError (and soon DeliveryReporting) report the failure
-    the channel remains open
-
-Proposed implementation: keep the current implementation
-
-_`req35`: failing to make a call
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo makes a VoIP call to Juliet, but Juliet's server crashes and failure
-is signalled.
-
-Current implementation::
-
-    Juliet is removed from the Group interface, with an error for the reason
-    the StreamedMedia channel closes
-
-Proposed implementation: keep the current implementation?
-
-_`req36`: Cancelling outgoing call
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Juliet starts a VoIP call to Tybalt, but then thinks better of it and
-cancels the call.
-
-Current implementation (NMC 4.x)::
-
-    UI calls mission_control_cancel_channel_request()
-
-    if dispatching of the channel has already begun:
-        cancellation succeeds
-    else:
-        cancellation fails
-        the UI is asked to handle the channel
-
-Problems:
-
-* In NMC 4.x the UI cannot distinguish between the channel that it no longer
-  cares about and should close/refuse (this use case), and a channel requested
-  by another process but handled by it (req5_)
-
-Proposed implementation: the cancelling client calls Cancel on the channel
-request. There are in fact several cases.
-
-_`req36a`: channel creation method has not yet been called
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-CD should refrain from calling it
-
-_`req36b`: channel creation method has been called
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-CD should remember the cancellation, and when the channel creation method
-returns, immediately close the channel with Close()
-
-_`req36c`: channel has been created, handler has not been notified
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-CD should close the channel with Close()
-
-_`req36d`: handler has been notified but has not returned
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-FIXME: is it still safe for the CD to close the channel? This raises a race
-condition - the handler will look for details of the channel and find that
-it's gone - but that can happen anyway (because the remote peer could close
-the channel). Perhaps the CD should follow up with a method call to say
-"it's OK that you just failed to handle that channel - it went away", but
-probably that's crack.
-
-_`req36e`: handler has accepted the channel
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-It's too late, and Cancel should fail (indeed, the channel-request object
-should no longer exist)
-
-_`req37`: Requesting a channel takes time
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Romeo makes a VoIP call to Juliet from a Maemo device at a time when he has no
-connectivity. Mission Control (the ChannelDispatcher implementation) on Maemo
-is able to request that the device obtains some sort of connection when
-needed, so it does so. However, Romeo is not near a wireless LAN access
-point, and it takes a couple of minutes for him to walk towards one.
-
-Naive implementation: the request is a method call, the request being
-satisfied is a response
-
-Problems addressed by proposed implementation: the D-Bus method call will
-time out after around 25 seconds unless special action is taken
-
-Proposed implementation: req4_
-
-_`req38`: Going behind the channel dispatcher's back
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A new channel is needed in one of the following cases:
-
-* _`req38a`: A monolithic Telepathy client on a resource-constrained
-  platform interacts directly with the Requests interface to request a
-  channel. There is no channel dispatcher.
-
-* _`req38b`: telepathy-inspector requests a channel which it will handle
-  internally. The channel dispatcher may or may not be installed; if
-  installed, it should not launch any UI for this channel.
-
-Proposed implementation:
-
-* The client calls CreateChannel or EnsureChannel on the CM directly
-
-* In case req38b_ the channel dispatcher (if present) runs observers in
-  response to the NewChannel signal, but does not run approvers or a channel
-  handler because the channel was Requested
-
-* In case req38a_ the client ignores the NewChannel signal because
-  the channel was Requested (which incoming channels are not);
-  in case req38b_ telepathy-inspector logs the event but does not pop up
-  a window in any case
-
-* CreateChannel or EnsureChannel returns the channel to the client, and it
-  handles it
-
 _`req39`: message-sending UI that doesn't want to know about receiving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1381,53 +212,5 @@ another one to open with the same pending messages
 
 * Possible infinite-loop situations in Mission Control need investigating
 
-General issues
---------------
-
-Selecting a channel handler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We can solve this later. For now, it's implementation-dependent which
-handler is used if several are possible - the channel dispatcher can use
-any reasonable algorithm to choose one.
-
-Selecting new or existing channels
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We assume that creating a channel has visible side-effects, and that this
-is undesirable in some cases.
-
-When requesting a single channel, there are four possibilities:
-
-* A: Only a new channel is acceptable
-
-* B: Creating a new channel is preferable, but returning an existing channel
-  would be OK too
-
-* C: Returning an existing channel is preferable, but creating a new channel
-  would be OK too
-
-* D: Only an existing channel is acceptable - creating a new channel is to be
-  avoided
-
-When requesting a bundle of channels, everything gets more complicated - if
-we're failing a request because the client wanted all new channels but got
-one existing channel, we don't want the CM to create *any* new channels.
-
-Proposed implementation:
-
-* invent an error "already exists", or just use NotAvailable
-
-* case A: CreateChannel
-
-* case B: we've concluded that this is weird. Who'd want this?
-
-* case C: EnsureChannel
-
-* case D: we could define a QueryChannels if there is demand
-
-* don't implement atomic requests for several channels simultaneously unless
-  we *really* need them
-
 ..
   vim:set sw=4 sts=4 et: