[telepathy-spec/master] Re-draft ContactCapabilities to include client feature flags
Simon McVittie
simon.mcvittie at collabora.co.uk
Sun Aug 16 07:57:53 PDT 2009
---
spec/Channel_Interface_Tube.xml | 2 +-
spec/Channel_Type_File_Transfer.xml | 2 +-
spec/Channel_Type_Streamed_Media_Future.xml | 7 +-
spec/Client_Handler.xml | 29 +++
spec/Connection_Interface_Contact_Capabilities.xml | 214 +++++++++++++++++---
spec/Connection_Interface_Contacts.xml | 8 +-
6 files changed, 228 insertions(+), 34 deletions(-)
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 4550673..45f7510 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -44,7 +44,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
even if no client has indicated via
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2">UpdateCapabilities</tp:dbus-ref>
that such a tube is supported. They SHOULD also allow clients to offer tubes with any
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index 61e1bba..c53444d 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -80,7 +80,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Connection managers SHOULD NOT advertise support for file transfer to
other contacts unless it has been indicated by a call to
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2">UpdateCapabilities</tp:dbus-ref>.
</p>
<tp:rationale>
<p>People would send us files, and it would always fail. That would be silly.</p>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 07a181e..6f0ec3b 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -90,7 +90,7 @@
</tp:rationale>
<p>Connection managers that support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT2</tp:dbus-ref>
interface SHOULD represent the capabilities of receiving audio
and/or video calls by including a channel class in
a contact's capabilities with ChannelType = StreamedMedia
@@ -106,8 +106,9 @@
</tp:rationale>
<p>Clients that are willing to receive audio and/or video calls
- SHOULD include the following filters if calling <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
+ SHOULD include the following among their channel classes if
+ calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2">UpdateCapabilities</tp:dbus-ref>
(clients of a <tp:dbus-ref
namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
SHOULD instead arrange for the ChannelDispatcher to do this,
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index d366862..de9eeac 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -109,6 +109,35 @@
</tp:docstring>
</property>
+ <property name="Capabilities" tp:name-for-bindings="Capabilities"
+ type="as" tp:type="Client_Capability[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The set of additional capabilities supported by this handler.
+ This describes things like support for streamed media codecs and
+ NAT traversal mechanisms: see the Contact Capabilities
+ interface for more details.</p>
+
+ <p>For handlers that have a <code>.client</code> file, the
+ channel dispatcher may discover this property from the
+ <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code>
+ group; for each capability, that group contains a key
+ whose name is the capability, with value <code>true</code>.
+ Keys with other values SHOULD NOT appear in this group.</p>
+
+ <p>For instance, the <code>.client</code> file for a streamed media
+ handler that supports ICE-UDP NAT traversal, Speex audio,
+ and Theora and H264 video might contain this group:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler.Capabilities]
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
+</pre>
+ </tp:docstring>
+ </property>
+
<method name="HandleChannels" tp:name-for-bindings="Handle_Channels">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Called by the channel dispatcher when this client should handle these
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
index 042b24b..9fb323c 100644
--- a/spec/Connection_Interface_Contact_Capabilities.xml
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -18,7 +18,7 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT"
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2"
tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:added version="0.17.16">(as a draft)</tp:added>
@@ -38,38 +38,167 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>This interface also enables user interfaces to notify the connection
manager what capabilities to advertise for the user to other contacts.
This is done by using the
- <tp:member-ref>SetSelfCapabilities</tp:member-ref> method, and deals
- with channel property values pertaining to them which are implemented
- by available client processes.</p>
+ <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p>
+ <tp:rationale>
+ <p>XMPP is a major user of this interface: XMPP contacts will not,
+ in general, be callable using VoIP unless they advertise suitable
+ Jingle capabilities.</p>
+
+ <p>Many other protocols also have some concept of capability flags,
+ which this interface exposes in a protocol-independent way.</p>
+ </tp:rationale>
</tp:docstring>
- <method name="SetSelfCapabilities"
- tp:name-for-bindings="Set_Self_Capabilities">
- <arg direction="in" name="caps" type="aa{sv}"
+ <tp:simple-type name="Client_Capability" type="s"
+ array-name="Client_Capability_List">
+ <tp:docstring>
+ A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
+ and an identifier for a capability defined by that interface. The
+ capability identifier SHOULD be in lower case. If an interface
+ references an external specification which is case-insensitive (such
+ as MIME), then names from that specification MUST be normalized to
+ lower-case before providing them to this Telepathy API, so that
+ implementations can safely rely on simple byte-by-byte comparison.
+
+ <tp:rationale>
+ These aren't D-Bus core Properties, and we want them to look visibly
+ different.
+ </tp:rationale>
+
+ <p>An initial set of client capabilities is defined here: when this
+ interface leaves draft status, these capabilities should be defined
+ by the MediaSignalling interface.</p>
+
+ <dl>
+
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p</dt>
+ <dd>
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>gtalk-p2p</code>.</p>
+ </dd>
+
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp</dt>
+ <dd>
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>ice-udp</code>.</p>
+ </dd>
+
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-8.5</dt>
+ <dd>
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-8.5</code>.</p>
+ </dd>
+
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-2009</dt>
+ <dd>
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-2009</code>.</p>
+ </dd>
+
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/<em>SUBTYPE</em></dt>
+ <dt>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/<em>SUBTYPE</em></dt>
+ <dd>
+ <p>The client supports media streaming with the audio or video codec
+ whose MIME type is audio/<em>SUBTYPE</em> or
+ video/<em>SUBTYPE</em> (the subtype MUST appear in lower
+ case when used with this interface). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on StreamedMedia channels.</p>
+ </tp:rationale>
+
+ <p>[FIXME: should we say the next paragraph, for completeness?]</p>
+
+ <p>Clients supporting video MUST advertise support for at least
+ one video codec, while clients supporting audio MUST advertise
+ support for at least one audio codec.</p>
+
+ <p>For example, a client could advertise support for
+ Speex, Theora and H264 by having three
+ Feature flags,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>.
+ .</p>
+ </dd>
+
+ </dl>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="Client_Capabilities"
+ array-name="Client_Capabilities_List">
+ <tp:docstring>
+ A structure representing the capabilities of a single client.
+ </tp:docstring>
+
+ <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name">
+ <tp:docstring>
+ For implementations of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client</tp:dbus-ref>
+ interface, the well-known bus name name of the client; for any other
+ process, any other reversed domain name that uniquely identifies it.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Channel_Classes" type="aa{sv}"
tp:type="String_Variant_Map[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- An array of channel classes to replace to the list of what the
- connection can handle. If you include optional properties, they
- may not get advertised. The given properties are matched to the
- mandatory properties.
+ An array of channel classes that can be handled by this client.
+ This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ property.
</tp:docstring>
- </arg>
+ </tp:member>
+
+ <tp:member name="Capabilities" type="as" tp:type="Client_Capability[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of client capabilities supported by this client, to be
+ used by the connection manager to determine what capabilities to
+ advertise. This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Used by user interfaces to indicate which channel classes they are
- able to handle on this connection. It replaces the previous advertised
- channel classes by the set given as parameter.</p>
+ <p>Alter the connection's advertised capabilities to include
+ the intersection of the given clients' capabilities with what the
+ connection manager is able to implement.</p>
- <p>If a channel class is unknown by the connection manager, it is just
- ignored. No error are returned in this case, and other known channel
- class are added.</p>
+ <p>On connections managed by the ChannelDispatcher, processes other
+ than the ChannelDispatcher SHOULD NOT call this method, and the
+ ChannelDispatcher SHOULD use this method to advertise the
+ capabilities of all the registered <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>
+ implementations.On connections not managed by the ChannelDispatcher,
+ clients MAY use this method directly, to indicate the channels they
+ will handle and the extra capabilities they have.</p>
- <p>Upon a successful invocation of this method, the
- <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
- will only be emitted for the user's own
- handle (as returned by GetSelfHandle) by the connection manager if, in
- the given protocol, the given capabilities are distinct from the
- previous state.</p>
+ <p>Upon a successful invocation of this method, the connection manager
+ will only emit the
+ <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
+ for the user's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">SelfHandle</tp:dbus-ref>
+ if, in the underlying protocol, the new capabilities are distinct
+ from the previous state.</p>
<tp:rationale>
<p>The connection manager will essentially intersect the provided
@@ -79,10 +208,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
channel) will almost certainly not be advertised.</p>
</tp:rationale>
+ <p>This method MAY be called on a newly-created connection while it
+ is still in the DISCONNECTED state, to request that when the
+ connection connects, it will do so with the appropriate
+ capabilities. Doing so MUST NOT fail.</p>
</tp:docstring>
+
+ <arg direction="in" name="Client_Capabilities" type="a(saa{sv}as)"
+ tp:type="Client_Capabilities[]">
+ <tp:docstring>
+ <p>The capabilities of one or more clients.</p>
+
+ <p>For each client in the given list, any capabilities previously
+ advertised for the same client name are discarded, then replaced by
+ the capabilities indicated.</p>
+
+ <p>As a result, if a client becomes unavailable, this method SHOULD
+ be called with a <tp:type>Client_Capabilities</tp:type> structure
+ containing its name, an empty list of channel classes, and an
+ empty list of capabilities. When this is done, the connection
+ manager SHOULD free all memory associated with that client name.</p>
+
+ <tp:rationale>
+ <p>This method takes a list of clients so that
+ when the channel dispatcher first calls it (with a list of all
+ the Handlers that are initially available), the changes can be
+ made atomically, with only one transmission of updated
+ capabilities to the network. Afterwards, the channel dispatcher
+ will call this method with a single-element list every time
+ a Handler becomes available or unavailable.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST ignore any channel classes and client
+ capabilities for which there is no representation in the protocol
+ or no support in the connection manager.</p>
+ </tp:docstring>
+ </arg>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 1033e04..867a4d7 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -76,11 +76,11 @@
are not known; present in the result as an empty array if the
contact is known to have no capabilities at all.</dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps
- (type a{ua(a{sv}as)},
- <tp:type>Contact_Capabilities_Map</tp:type>)</dt>
+ <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2/capabilities
+ (type a(a{sv}as),
+ <tp:type>Requestable_Channel_Class</tp:type>[])</dt>
<dd>The same structs that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">GetContactCapabilities</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT2">GetContactCapabilities</tp:dbus-ref>
Omitted from the result if the contact's capabilities
are not known; present in the result as an empty array if the
contact is known to have no capabilities at all.</dd>
--
1.5.6.5
More information about the telepathy-commits
mailing list