[Telepathy] The future of Capabilities

[Simon McVittie]

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

On Tue, 08 Jul 2008 at 17:03:49 +0100, Simon McVittie wrote:
> (1) The capabilities of our connection
> 
> This is requested by <http://bugs.freedesktop.org/show_bug.cgi?id=15418> and
> solves the following problem: as implementor of a UI like Empathy, how
> do you tell what sorts of channel you can reasonably request (i.e. what
> sorts of channel you should show UI for requesting)?
...
> I'll write a follow-up email with an attempt to list
> use-cases for these.

See http://people.freedesktop.org/~smcv/telepathy-spec-usecases/cmcaps.html
or the source text below (for easier quoting and discussion).

Regards,
    Simon

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:
-----BEGIN PGP SIGNATURE-----

iD8DBQFIdg4NWSc8zVUw7HYRArhMAJ9lr/yAyrXdRxeMZDVieQe44qjcuQCeMZ2b
on+dUJrqgm+nOw/Du0YDjqo=
=2zgV
-----END PGP SIGNATURE-----