diff options
author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-11-09 18:18:16 +0000 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-11-09 18:18:19 +0000 |
commit | 0d0940ae1b135732af43fc39d074255b78ead09e (patch) | |
tree | 6400c1b67caf67d84b90ba0d387c8dae50992a94 /doc | |
parent | a8f7f603bc1be3fd5ce66f01ec1ebf2b296f1a90 (diff) | |
parent | c43c2366423ec68afc46ec3d18c2f1ca72fa7db1 (diff) |
Merge branch 'pruning'
Reviewed-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/clientcaps.txt | 49 | ||||
-rw-r--r-- | doc/cmcaps.txt | 182 | ||||
-rw-r--r-- | doc/dispatch.txt | 994 | ||||
-rw-r--r-- | doc/open-issues.txt | 47 | ||||
-rw-r--r-- | doc/request.txt | 1433 | ||||
-rw-r--r-- | doc/templates/oldspec.html | 11 |
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> |