Merge branch 'pruning'

Reviewed-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

6 files changed, 0 insertions, 2716 deletions

diff --git a/doc/clientcaps.txt b/doc/clientcaps.txt
deleted file mode 100644
index 48c647e5..00000000
--- a/doc/clientcaps.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-Use cases for client capabilities
-=================================
-
-.. contents::
-
-Issues
-------
-
-* We need a way for special-purpose apps to be a low priority handler for
-  more general channels - a Tubes-capable AbiWord probably shouldn't handle
-  Text or VoIP channels unless no general-purpose UI is available (and
-  perhaps not even then)
-
-Empathy
--------
-
-... or other general-purpose IM client. (This is a hypothetical future
-version of Empathy - it doesn't do everything listed here yet)
-
-* ChannelType = Text, TargetHandleType = CONTACT
-* ChannelType = StreamedMedia, TargetHandleType = NONE
-* ChannelType = FileTransfer, TargetHandleType = CONTACT
-
-AbiWord
--------
-
-... or other collaborative app. (Again, this is a hypothetical future
-version - it doesn't do everything listed here yet, and perhaps never will)
-
-* ChannelType = DBusTube, Service = com.abisource.AbiCollab (or something)
-* ChannelType = Text, TargetHandleType = CONTACT, low priority
-* ChannelType = StreamedMedia, TargetHandleType = NONE, low priority
-* ChannelType = FileTransfer, TargetHandleType = CONTACT, low priority
-* ChannelType = FileTransfer, ContentType = 'text/abiword' ?
-
-OpenArena
----------
-
-Hypothetically...
-
-* ChannelType = PacketTube, service = _openarena._udp (or something)
-
-OLPC activity
--------------
-
-Similar to AbiWord
-
-..
-  vim:set sw=4 sts=4 et:
diff --git a/doc/cmcaps.txt b/doc/cmcaps.txt
deleted file mode 100644
index 441ff266..00000000
--- a/doc/cmcaps.txt
+++ /dev/null
@@ -1,182 +0,0 @@
-Use cases for connection manager capabilities
-=============================================
-
-.. contents::
-
-Connection manager capabilities indicate what sorts of channel a connection
-manager could conceivably satisfy a request for. This is closely related to
-`channel requesting`_, and can be used by clients to decide what UI to
-present.
-
-.. _channel requesting: request.html
-
-For instance, Empathy's Chat -> New Conversation menu can use this mechanism
-to decide what connection managers could conceivably have what features.
-
-Fundamentally, it is a Connection that has or lacks a particular feature.
-However, it would be useful for some part of Mission Control (account manager?
-channel dispatcher?) to cache "expected" capabilities for unconnected
-accounts, or perhaps even be able to guess what capabilities an account will
-have before it has ever become connected.
-
-The current proposal is:
-
-* "Classes" of requestable channel are identified by (ChannelType,
-  TargetHandleType) pairs
-
-* If TargetHandleType is not NONE then either TargetHandle or TargetID is
-  always mandatory, and TargetHandle (if given) is nonzero
-
-* If TargetHandleType is NONE then TargetHandle and TargetID are forbidden
-
-* Other parameters can exist, and can be mandatory or optional; clients MUST
-  NOT send parameters that aren't explicitly allowed
-
-Problems with this proposal:
-
-* How do we say that not all "valid" values for a parameter are allowed?
-  For instance we might only support a couple of MIME types for file transfer
-
-  * Tentative resolution: we don't, but the request will fail without
-    side-effects
-
-* Can there potentially be more than one "class" per pair? Representing this
-  in a UI is likely to be hard
-
-  * Tentative resolution: yes, but we'll try to avoid it?
-
-* Would it be useful to indicate what interfaces will/might be supported
-  by channels of a given class?
-
-Optional parameters which could hypothetically apply to all channels
---------------------------------------------------------------------
-
-* ...Channel.Bundle
-* ...Channel.Interface.Thread.ThreadID
-* ...Channel.Interface.TLS.Secure
-
-1-1 text chat
--------------
-
-:ChannelType:
-    ...Channel.Type.Text
-:TargetHandleType:
-    CONTACT
-:Mandatory parameters other than TargetHandle:
-    none
-:Optional parameters not already mentioned:
-    none
-
-Chatroom
---------
-
-:ChannelType:
-    ...Channel.Type.Text
-:TargetHandleType:
-    ROOM
-:Mandatory parameters other than TargetHandle:
-    none
-:Optional parameters not already mentioned:
-    ...Ch.I.Chatroom.Nickname
-
-1-1 VoIP
---------
-
-:ChannelType:
-    ...Channel.Type.StreamedMedia
-:TargetHandleType:
-    NONE (or CONTACT)
-:Mandatory parameters other than TargetHandle:
-    none
-:Optional parameters not already mentioned:
-    none
-
-Mingle
-------
-
-:ChannelType:
-    ...Channel.Type.StreamedMedia
-:TargetHandleType:
-    ROOM
-:Mandatory parameters other than TargetHandle:
-    none
-:Optional parameters not already mentioned:
-    none
-
-RoomList
---------
-
-:ChannelType:
-    ...Channel.Type.Text
-:TargetHandleType:
-    NONE
-:Mandatory parameters:
-    none
-:Optional parameters not already mentioned:
-    none
-
-FileTransfer
-------------
-
-:ChannelType:
-    ...Channel.Type.FileTransfer
-:TargetHandleType:
-    CONTACT
-:Mandatory parameters other than TargetHandle:
-    Varies per connection manager!
-
-    * SuggestedFilename: mandatory in XMPP XEP-0096 and probably others
-
-      * maybe we should make this always mandatory?
-
-    * Size: mandatory in XMPP XEP-0096
-
-      * we plan to make this always mandatory in requests, for reliable
-        detection of truncated transfers
-
-    * other protocols?
-
-:Optional parameters not already mentioned:
-    * RandomAccess=True? (XEP-0096 byte ranges)
-    * Description (XEP-0096)
-    * ContentType? (can always avoid making this mandatory by defaulting to
-      'application/octet-stream')
-    * ContentMD5
-    * app-defined metadata? (not possible in all, or possibly any, protocols)
-
-D-Bus, Stream, Packet Tube
---------------------------
-
-Attempt 1
-~~~~~~~~~
-
-:ChannelType:
-    ...Channel.Type.DBusTube, Ch.T.StreamTube, Ch.T.PacketTube?
-    (with ...Channel.Interface.Tube)
-:TargetHandleType:
-    CONTACT or ROOM
-:Mandatory parameters other than TargetHandle:
-    Service
-    AvailableSocketTypes (the request fails if the channel's available
-    (socket, access control type) pairs have empty intersection with
-    these)
-:Optional parameters not already mentioned:
-    TubeParameters (omitted and empty a{sv} are interchangeable)
-
-Attempt 2
-~~~~~~~~~
-
-:ChannelType:
-    e.g. ...Channel.Type.DBusTube.com.abisource.AbiCollab,
-    ...Channel.Type.StreamTube.vnc, ...Channel.Type.PacketTube.openarena
-    (with ...Channel.Interface.Tube and possibly also
-    ...Channel.Interface.DBusTube etc.)
-:TargetHandleType:
-    CONTACT or ROOM
-:Mandatory parameters other than TargetHandle:
-    AvailableSocketTypes as in attempt 1
-:Optional parameters not already mentioned:
-    as in attempt 1
-
-..
-  vim:set sw=4 sts=4 et:
diff --git a/doc/dispatch.txt b/doc/dispatch.txt
deleted file mode 100644
index b580015e..00000000
--- a/doc/dispatch.txt
+++ /dev/null
@@ -1,994 +0,0 @@
-Use cases for 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 addressed by proposed implementation:
-
-* 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. It must be
-  service-activatable to avoid missing any messages.
-
-* The tray icon is a Client and a Client.Approver
-
-* The chat UI is a Client and a Client.Handler (selected in an
-  implementation-specific way)
-
-* Clients should not wait for the first message in an incoming channel -
-  if a connection manager creates channels before a message arrives, clients
-  should assume it has a valid reason to do so? ("`psychic mode`_")
-
-Dispatch process::
-
-    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
-
-    CD calls AddDispatchOperation on all matching Approvers, including
-    org.freedesktop.Telepathy.Client.EmpathyTrayIcon
-
-    Empathy tray icon flashes
-
-    Juliet clicks on tray icon and chooses Accept
-
-    Empathy tray icon calls
-    HandleWith('org.freedesktop.Telepathy.Client.EmpathyChat')
-
-    ChannelDispatchOperation 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 calls HandleChannels on Empathy chat process (service-activating it
-    if needed)
-
-_`dis2a`: Incoming 1-1 text message with lost window
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Juliet receives a message from Romeo after a pause in their conversation.
-
-Current implementation, _`dis2impl1`: it arrives in the Text channel
-
-Potential problem: 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
-
-Proposed solution: if the the chat UI is in the same process
-as the notification mechanism, all is good - it can prod the notifier
-directly. If it's not, then it can use a D-Bus API outside the scope of this
-spec to do the same. (Avoiding premature generalization and assuming clients
-to be competent)
-
-_`dis2b`: Incoming 1-1 text message with crashed handler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Juliet receives a message from Romeo after her chat UI has crashed.
-
-Current implementation: it arrives in the Text channel, which nothing is
-handling, and is lost
-
-Proposed implementation: when a ChannelHandler that was handling a channel
-falls off the bus, the channel dispatcher closes the channel. If the channel
-is of type Text, it restarts when the new message arrives.
-
-_`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.
-
-Incorrect implementation, _`dis3impl1`:
-
-* The Text channel is not closed
-
-* The new message causes the chat window to pop up, possibly stealing focus
-
-Problems with dis3impl1_:
-
-* Focus stealing is likely
-
-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 with dis3impl2_:
-
-* Not associated with the previous chat session, although this could be fixed
-  with "conversation thread IDs" as in req27_
-
-.. _req27: request.html#req27
-
-* 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 with dis3impl3_:
-
-* if it is desirable to tell the remote user that the window has been closed,
-  the CM can't know
-
-Proposed implementation: keep dis3impl2_, and later use conversation
-thread IDs as per req27_ to solve the problem above
-
-_`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
-
-Problems:
-
-* How do we ensure that approvers are not invoked in this case, but are
-  invoked in case dis10_?
-
-_`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().)
-
-Proposed solution: you're not allowed to handle a channel yourself unless
-either you're a channel handler, or you're bypassing the channel dispatcher
-completely
-
-.. _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_
-
-Proposed implementation::
-
-    CM emits Requests.NewChannels([(channel_path,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': ROOM,
-            '...TargetHandle': 123,
-            '...TargetID': 'ball@conference.capulet.example.com',
-            '...Requested': FALSE,
-            '...InitiatorHandle': 6543,
-            '...InitiatorID': 'mercutio@example.com',
-            ...
-        },
-        )])
-
-    In response, CD calls ObserveChannels on all matching Observers, including
-    org.freedesktop.Telepathy.Client.EmpathyLogger
-
-    CD creates a ChannelDispatchOperation
-
-    CD calls AddDispatchOperation on all matching Approvers, including
-    org.freedesktop.Telepathy.Client.EmpathyTrayIcon
-
-    Empathy tray icon flashes
-
-    Romeo clicks on tray icon and chooses "Join room"
-
-    Empathy tray icon calls
-    HandleWith('org.freedesktop.Telepathy.Client.EmpathyChatroom')
-
-    ChannelDispatchOperation 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 calls HandleChannels on Empathy chat process (service-activating it
-    if needed)
-
-_`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". I don't think it's very useful to
-  distinguish between this and incoming, though.
-
-Proposed implementation:
-
-* The channels have Requested=FALSE, just like incoming channels
-
-* Clients should not wait for the first message in an incoming channel -
-  this would break chatroom invitations in any case
-
-* If a connection manager creates channels before a message arrives, clients
-  should assume it has a valid reason to do so? ("`psychic mode`_")
-
-.. _psychic mode: http://meanwhile.sourceforge.net/faq/#psychic
-
-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::
-
-    CM emits Requests.NewChannels([(channel_path,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': 6,
-            '...TargetID': 'juliet@capulet.example.com',
-            '...Requested': FALSE,
-            # and perhaps...
-            '...InitiatorHandle': 6,
-            '...InitiatorID': 'juliet@capulet.example.com',
-            ...
-        },
-        )])
-
-    In response, CD calls ObserveChannels on all matching Observers, including
-    org.freedesktop.Telepathy.Client.EmpathyLogger
-
-    CD creates a ChannelDispatchOperation
-
-    CD calls AddDispatchOperation on all matching Approvers, including
-    org.freedesktop.Telepathy.Client.EmpathyTrayIcon
-
-    Empathy tray icon flashes
-
-    Romeo clicks on tray icon and chooses Answer
-
-    Empathy tray icon calls
-    HandleWith('org.freedesktop.Telepathy.Client.EmpathyVoIP')
-
-    ChannelDispatchOperation 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 calls HandleChannels on Empathy VoIP process (service-activating it
-    if needed)
-
-_`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:
-
-* As for dis8_. The properties ...Channel.InitiatorHandle,
-  ...Channel.InitiatorID indicate Juliet's handle and ID
-  (JID, SIP URI, etc.) immediately. TargetHandle and TargetID also indicate
-  the same information, although there are backwards-compatibility issues.
-
-::
-
-    CM emits Requests.NewChannels([(channel_path,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': 6,
-            '...TargetID': 'juliet@capulet.example.com',
-            '...Requested': FALSE,
-            # and perhaps...
-            '...InitiatorHandle': 6,
-            '...InitiatorID': 'juliet@capulet.example.com',
-            ...
-        },
-        )])
-
-    In response, CD calls ObserveChannels on all matching Observers, including
-    org.freedesktop.Telepathy.Client.EmpathyLogger
-
-    CD creates a ChannelDispatchOperation
-
-    CD calls AddDispatchOperation on all matching Approvers, including
-    org.freedesktop.Telepathy.Client.EmpathyTrayIcon
-
-    Empathy tray icon flashes
-
-    Time passes, Juliet gives up and hangs up the call
-
-    CM emits ChannelClosed(channel_path)
-
-    ChannelDispatchOperation emits Closed
-
-Problems remaining:
-
-* Perhaps the ChannelDispatchOperation should emit a different signal,
-  which indicates that the channel was closed by Juliet rather than
-  by Romeo? This would require the CD to watch the Channel's Group
-  interface etc., not just Connection.Interface.Requests; or perhaps
-  the ChannelClosed signal should contain a D-Bus error code?
-
-_`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
-
-Problems with proposed implementation:
-
-* How do we ensure that approvers are invoked here, if they're not
-  in case dis5a_?
-
-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
-
-* Client authors would prefer to wait for all contact lists to arrive (or
-  definitely not arrive), then query for all those contacts' aliases, avatars
-  etc. in one big transaction, and only then display them - but that's
-  impossible if the client is being passive, because it can't know whether
-  the 'publish' channel hasn't arrived yet, or will never arrive because the
-  CM doesn't support it
-
-Proposed implementation:
-
-* Clients SHOULD NOT rely on being channel handlers for contact lists;
-  clients SHOULD explicitly request any contact list channels that they want
-  to use
-
-* Clients interested in contact lists should be Observers and observe them,
-  instead of relying on being a channel handler
-
-* In the long term, we should switch to a Connection.Interface.Roster
-
-_`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 addressed by proposed implementation:
-
-* Can we register more than one channel handler for groups? Every process
-  with a contact-list UI might be interested in them
-
-Proposed implementation _`dis12impl1`:
-
-* Each contact list UI is an Observer for groups
-
-* There is no channel handler for groups
-
-Problems remaining:
-
-* Clients can't know when we've finished creating groups (see dis11_),
-  but it is desirable for clients not to display anything until all groups
-  and all contact lists have arrived
-
-* We'd have to avoid making the channel dispatcher panic and close the
-  "unhandled" group
-
-* In the long term, we should switch to a Connection.Interface.Roster
-
-_`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). This is much like 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_.
-
-Proposed implementation: Don't do this.
-
-_`dis31`: unified download manager
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-An applet displays all file transfers made using Telepathy, Firefox, etc.
-
-Proposed implementation: it's an Observer for all file transfers
-
-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_)
-
-.. _req24: request.html#req24
-.. _req25: request.html#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 handlers 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:
-
-* The channel dispatcher prioritizes channel handlers in an
-  implementation-dependent way
-
-* Approvers can select which one to use from among several possible channel
-  handlers, for incoming channels only
-
-Problems remaining:
-
-* Should outgoing channels go through approvers, just to have a way to
-  influence the choice of handler?
-
-* What about automatic or unknown-directionality channels?
-
-_`dis27`: multiple channel handlers 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
-
-_`dis30`: monolithic client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A monolithic Telepathy client on a resource-constrained platform responds
-to new channels without the help of a channel dispatcher implementation.
-
-Current implementation: the client sets suppress_handler=TRUE on all its
-channel requests, and ignores NewChannel signals that have
-suppress_handler=TRUE
-
-Proposed implementation: a straightforward port of the current implementation
-
-_`dis32`: Channel Dispatcher crash recovery
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The channel dispatcher crashes. Some other component (probably a UI) notices
-and restarts it. The channel dispatcher must reconcile its internal state
-with what's actually going on.
-
-It is likely that the channel dispatcher and the account manager are in
-fact the same process (Mission Control and Decibel are both implemented
-like this), so we must be able to cope with a simultaneous CD and AM crash.
-
-Current implementation: Nokia's Mission Control 4 calls Disconnect on all
-connections, causing reality to reflect its internal state. Obviously, this
-isn't ideal (and can cause messages to be lost).
-
-Proposed implementation: The channel dispatcher discovers existing
-connections and channels, causing its internal state to reflect reality.
-
-More specifically:
-
-* before it calls Connect on each new connection, the account manager saves
-  the association between connections and accounts to a cache
-
-* during startup, the account manager discovers existing connections, and
-  reads that cache to find out which ones correspond to an account that it
-  manages
-
-* the channel dispatcher discovers from the account manager which connections
-  it should manage
-
-* the CD lists the channels on each connection (call this set *E*)
-
-* the CD also discovers all clients (by looking for o.fd.T.Client.* bus names)
-  and lists the channels that each client is handling (call this set *H*)
-
-* the CD now knows what everyone is handling
-
-* now the CD can dispatch every unhandled channel (the set *E* \ *H*) as if
-  newly created
-
-_`dis33`: One channel (of many) is closed while in Dispatcher
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The NewChannels signal carries 2 or more channels.  One or more of these
-channels, but not all of them, emit Closed before the CD has a chance to invoke
-some or all of the Clients.
-
-Current implementation: Nokia's Mission Control 4 supports dispatching of only
-one channel at a time, and if that channel is closed, the operation is aborted
-(i.e., clients don't even see the channel).
-
-Proposed implementation: the CD behaves as if nothing happened, and happily
-dispatches the channels (including the dead ones) to the clients.
-
-Problems addressed:
-
-* in case the channels are the result of a ChannelRequest, the request can
-  still be listed among the "Satisfied_Request" argument of the HandleChannels.
-  This means that the client can map the channels to the request it made, it
-  can see the properties of all the channels that were created (they are passed
-  in HandleChannels' arguments) and in any case it will have to cope with the
-  fact that a channel is no longer there.
-
-* ChannelDispatcher code is simpler.
-
-..
-  vim:set sw=4 sts=4 et:
diff --git a/doc/open-issues.txt b/doc/open-issues.txt
deleted file mode 100644
index de09a008..00000000
--- a/doc/open-issues.txt
+++ /dev/null
@@ -1,47 +0,0 @@
-Open issues in this branch
-==========================
-
-Major
------
-
-File transfers might need more than one non-passive handler - anyone can
-stop the file transfer (although only one component can know where the
-bytes are coming from/going to)
-
-Contact lists and groups can easily have multiple non-passive handlers -
-is it OK to use observers for this?
-
-dis2_: what happens when a Text channel-handler crashes?
-
-.. _dis2: dispatch.html#dis2
-
-req22_, dis20_: increased importance of getting FTs handled by
-collaborative app if they are part of the collab protocol
-
-.. _dis20: dispatch.html#dis20
-.. _req22: request.html#req22
-
-req36_: cancelling an outgoing call (needs writing)
-
-.. _req36: request.html#req36
-
-Minor/corner-case
------------------
-
-Text channels could conceivably have multiple sources of messages, and even
-multiple sinks of messages, but there are coordination problems:
-
-* no handler should ack messages until all handlers have bound to signals
-
-* exactly one handler should ack each message
-
-dis12_: how do we know when all groups have arrived?
-
-.. _dis12: dispatch.html#dis12
-
-dis14_: forcibly joining chatrooms, psychic mode
-
-.. _dis14: dispatch.html#dis14
-
-..
-  vim:set sw=4 sts=4 et:
diff --git a/doc/request.txt b/doc/request.txt
deleted file mode 100644
index f3292716..00000000
--- a/doc/request.txt
+++ /dev/null
@@ -1,1433 +0,0 @@
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-:New vs. existing:
-    New channel required [#]_
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is CONTACT, TargetHandle is
-    mercutio, Bundle is the same as the AbiWord Tube channel
-
-.. [#] If the collaborative app already has a suitable channel, it is expected
-    to work this out without the channel dispatcher's help.
-    Stealing a channel from another UI is likely to fail (e.g. in the Text
-    interface, they'll both try to acknowledge messages) so we should
-    forbid this for sanity's sake
-
-Current implementation: impossible, even in protocols supporting
-conversation threads, because the spec can't represent them
-
-Proposed implementation::
-
-    let bundle_id = ...Bundle property of AbiWord Tube channel
-
-    if a channel with TargetHandleType == CONTACT, TargetHandle == mercutio
-    and Bundle == bundle_id is being handled by AbiWord:
-        nothing to do, we already have a Text channel: stop
-
-    AbiWord calls ChannelDispatcher.CreateChannel(
-        account,
-        {
-            '...ChannelType': '...Text',
-            '...TargetHandleType': CONTACT,
-            '...TargetHandle': mercutio,
-            '...Bundle': bundle_id,
-        },
-        timestamp,
-        abiword_client_bus_name
-    )
-    AbiWord calls ChannelRequest.Proceed()
-
-    ChannelDispatcher calls AddRequest on AbiWord, AbiWord 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 AbiWord
-        AbiWord handles channel
-    on failure:
-        ChannelDispatcher calls RemoveFailedRequest on AbiWord, and
-            ChannelRequest emits Failed
-        AbiWord displays failure
-        if the error is the EEXIST equivalent, the message might be
-            "Already talking to Mercutio in another app, and multiple threads
-            are not possible in this protocol"
-
-(Fallback behaviour if the CM is pre-Requests: the request is made with
-suppress_handler = TRUE.)
-
-_`req26`: 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 req28_ (on protocols that
-do not allow offline messages).
-
-(Recovering from a connection manager crash is equivalent to this.)
-
-:New vs. existing:
-    ???
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is CONTACT, TargetHandle is juliet,
-    ThreadID is the same as before
-
-Current implementation: same as req1_
-
-Problems addressed by proposed implementation:
-
-* the two conversations are unrelated (Juliet cannot distinguish
-  between this case and req1_)
-
-Proposed implementation (with a new Chan.I.Thread)::
-
-    Romeo's chat UI (or incoming message database) automatically saves the
-    ...Channel.Interface.Thread.ThreadID property of the old channel
-
-    Disconnect/reconnect occurs
-
-    Same as req1, except that ThreadID is included in the request
-
-Problems remaining:
-
-* What should the CM do if the desired thread ID cannot be used for some
-  reason?
-
-* There is a potential race, req26b_
-
-Resolution: defer the threads spec til later,
-https://bugs.freedesktop.org/show_bug.cgi?id=16544
-
-_`req26b`: potential race
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The same as req26_, but before Romeo's client can open the replacement
-channel, Juliet sends him a message, thus opening a new channel. (This
-is really a dispatching problem, but is closely related...)
-
-The desired behaviour is that the same handler receives the channel.
-
-Imagine that Romeo has both Kopete and Empathy installed, and Empathy
-is the default, but Romeo is using Kopete to talk to Juliet.
-
-Naive implementation: either the race is won by the request for a
-replacement channel (and Kopete gets it) or it's won by Juliet's message
-creating a new channel (and Empathy gets it).
-
-Too-clever implementation: in principle, there's nothing to stop the
-channel dispatcher remembering that a channel handler has lost a channel,
-and using that as input to its handler-choosing heuristic
-
-_`req27`: 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.)
-
-:New vs. existing:
-    Existing channel preferred, new channel acceptable
-:Definition of channel identity:
-    ChannelType is Text, TargetHandleType is CONTACT, TargetHandle is juliet,
-    ThreadID is the same as before
-
-Current implementation: same as req2_
-
-Problems addressed by proposed implementation: Juliet cannot distinguish
-between this case and req2_
-
-Proposed implementation: same as req26_, except that it resembles
-req2_ instead of req1_ (i.e. no SUPPRESS_HANDLER flag)
-
-Problems remaining: same as req26_ (including a potential race, like req26b_)
-
-Resolution: defer the threads spec til later,
-https://bugs.freedesktop.org/show_bug.cgi?id=16544
-
-_`req28`: 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 Romeo reconnects, Juliet
-wants to keep using the same window to talk to him.
-
-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 req26_.
-
-(Recovering from Romeo's connection manager crash is equivalent to this.)
-
-Current implementation: Juliet's text channel does not close, but
-she cannot send messages. When Romeo reconnects, because of 1-1 chat
-uniqueness, Juliet's client continues to use the same channel and there
-is no disconnection.
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A UI (perhaps an address book) allows sending one-off messages to contacts,
-without entering into a dialogue. If the contact replies, this should be
-dispatched as usual.
-
-The UI can't close the channel in a race-free way, and if a message comes
-in on the same channel, at that point (only) it needs dispatching to a
-handler.
-
-Similarly, imagine a text channel where sending messages is very slow:
-we want to be able to close the channel handler (UI) without closing the
-channel, and have the channel be re-dispatched only when a message comes in.
-
-Possible solution: for Text channels, somehow arrange for the channel to
-be re-dispatched to a "silent" handler; when an incoming message arrives,
-the "silent" handler exits (or somehow submits the channel for re-dispatching)
-and the CD will re-dispatch to a UI.
-
-Possible solution: closing a Text channel that has pending messages causes
-another one to open with the same pending messages
-
-* This is in spec 0.17.9 and Gabble implements it
-
-* 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:
diff --git a/doc/templates/oldspec.html b/doc/templates/oldspec.html
deleted file mode 100644
index 5fc9ae0a..00000000
--- a/doc/templates/oldspec.html
+++ /dev/null
@@ -1,11 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <meta http-equiv="refresh" content="0; URL=spec/index.html" />
-    <title>Telepathy D-Bus Interface Specification</title>
-  </head>
-  <body>
-    <h1 class="topbox">Telepathy D-Bus Interface Specification</h1>
-    <p><a href="spec/index.html">The Telepathy specification has moved.</a></p>
-  </body>
-</html>