[telepathy-glib/master] Update spec to 0.17.27
Simon McVittie
simon.mcvittie at collabora.co.uk
Sun Aug 16 07:28:38 PDT 2009
---
spec/Channel_Dispatcher.xml | 2 +-
spec/Channel_Interface_Call_State.xml | 4 +-
spec/Channel_Interface_Media_Signalling.xml | 78 +++++++++
spec/Channel_Interface_Media_Signalling_Future.xml | 164 --------------------
spec/Channel_Interface_Tube.xml | 2 +-
spec/Channel_Type_Contact_Search.xml | 32 +++-
spec/Channel_Type_File_Transfer.xml | 2 +-
spec/Channel_Type_Streamed_Media.xml | 25 +++
spec/Channel_Type_Streamed_Media_Future.xml | 65 ++++++++-
spec/Client_Approver.xml | 9 +-
spec/Client_Handler.xml | 65 ++++++++
spec/Connection.xml | 50 +++++--
spec/Connection_Interface_Aliasing.xml | 12 ++
spec/Connection_Interface_Avatars.xml | 15 ++
spec/Connection_Interface_Capabilities.xml | 23 ++-
spec/Connection_Interface_Contact_Capabilities.xml | 143 +++++++++++++----
spec/Connection_Interface_Contacts.xml | 64 --------
spec/Connection_Interface_Location.xml | 60 ++++----
spec/Connection_Interface_Simple_Presence.xml | 12 ++-
spec/Connection_Manager.xml | 7 +-
spec/Debug.xml | 5 +-
spec/Makefile.am | 1 -
spec/Media_Stream_Handler.xml | 51 ++++++-
spec/all.xml | 3 +-
spec/errors.xml | 80 +++++++++-
telepathy-glib/connection.xml | 1 +
26 files changed, 635 insertions(+), 340 deletions(-)
delete mode 100644 spec/Channel_Interface_Media_Signalling_Future.xml
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index d312a6d..06f0458 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -74,7 +74,7 @@
All observers are notified simultaneously.</p></dd>
<dt><tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>p
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>
<dd>
<p>Approvers notify the user that new channels have been created,
and also select which channel handler will be used for the channel,
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
index eec6a4b..78a123f 100644
--- a/spec/Channel_Interface_Call_State.xml
+++ b/spec/Channel_Interface_Call_State.xml
@@ -25,7 +25,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
progress or call states. The presence of this interface is no guarantee
that call states will actually be signalled (for instance, SIP
implementations are not guaranteed to generate status 180 Ringing, so a
- call can be accepted without the Ringing flag ever having been set).</p>
+ call can be accepted without the Ringing flag ever having been set;
+ similarly, Jingle implementations are not guaranteed to send
+ <code><ringing/></code>).</p>
<p>To notify the other participant in the call that they are on hold,
see <tp:dbus-ref
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 5c29316..004df5b 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -152,6 +152,84 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:property>
+ <tp:handler-capability-token name="gtalk-p2p">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="ice-udp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="wlm-8.5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="wlm-2009">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="video/h264" is-family="yes">
+ <tp:docstring>
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 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>For example, a client could advertise support for
+ Speex, Theora and H264 by having three
+ handler capability tokens,
+ <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>,
+ in its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.</p>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
deleted file mode 100644
index bbb8b87..0000000
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ /dev/null
@@ -1,164 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Interface_Media_Signalling_Future"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright © 2009 Nokia Corporation </tp:copyright>
- <tp:license xmlns="http://www.w3.org/1999/xhtml">
- <p>This library is free software; you can redistribute it and/or
- modify it under the terms of the GNU Lesser General Public
- License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.</p>
-
- <p>This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.</p>
-
- <p>You should have received a copy of the GNU Lesser General Public
- 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.Channel.Interface.MediaSignalling.FUTURE">
- <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface contains functionality which we intend to incorporate
- into the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.Interface.MediaSignalling</tp:dbus-ref>
- interface in future. It should be considered to be conceptually part
- of the core MediaSignalling interface, but without API or ABI
- guarantees.</p>
-
- <tp:rationale>
- <p>The rationale is the same as for <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.FUTURE</tp:dbus-ref>.</p>
- </tp:rationale>
- </tp:docstring>
-
- <property name="ICETransportAvailable"
- tp:name-for-bindings="ICE_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>True if this channel supports the use of the ICE-UDP transport
- (<a href="http://xmpp.org/extensions/xep-0176.html">XEP-0176</a>,
- <a href="http://tools.ietf.org/html/draft-ietf-mmusic-ice">ICE RFC
- draft)</a>. Various other transports have boolean properties
- that work in the same way as this one, so this description covers
- all such transports.</p>
-
- <p>This property is immutable (cannot change), and therefore SHOULD
- appear wherever immutable properties are reported, e.g. <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
- signals.</p>
-
- <p>Connection managers capable of signalling streamed media calls to
- contacts SHOULD include the properties representing all supported
- transports in the allowed properties list of the channel class
- in <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
- that advertises support for streamed media channels.</p>
-
- <p>Similarly, connection managers that support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref>
- interface SHOULD include all supported transports in the allowed
- properties list of the channel class that advertises a contact's
- ability to receive streamed media calls.</p>
-
- <p>Clients SHOULD NOT pass ICETransportAvailable and similar
- properties to <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
- or similar functions. If they do, the connection manager MUST
- accept and ignore any such property that is in the allowed properties
- list.</p>
-
- <tp:rationale>
- <p>There is currently no way for clients to influence the choice
- of transport: in general, a client making a call can't know the
- capabilities of the streaming implementation, or even which
- streaming implementation will be used (channels will often be
- requested by an address book or similar application that will not
- handle the channel itself).</p>
-
- <p>If a mechanism for transport negotiation is added, it should be
- something that happens after the request, but before calling
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Media.SessionHandler.Ready</tp:dbus-ref>,
- so that it is the streaming implementation that chooses the
- transport, rather than the requesting client.</p>
- </tp:rationale>
-
- <p>Clients that are able to receive calls with particular transports
- MUST include the following filters if calling <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</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,
- by including the filters in their <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
- properties):</p>
-
- <ul>
- <li>{ ChannelType = StreamedMedia, ICETransportAvailable = true }
- if the ICE transport is supported</li>
- <li>{ ChannelType = StreamedMedia, RawUDPTransportAvailable = true }
- if the raw UDP transport is supported</li>
- <li>... and so on, one filter per available transport.</li>
- </ul>
-
- <p>Connection managers MAY use this information to adjust the
- transports for which they advertise support to other contacts.</p>
-
- <tp:rationale>
- <p>In particular, in XMPP, the connection manager will not be
- callable unless a client has told it to advertise support for
- at least one transport.</p>
- </tp:rationale>
- </tp:docstring>
- </property>
-
- <property name="RawUDPTransportAvailable"
- tp:name-for-bindings="Raw_UDP_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for raw UDP streaming as described by <a
- href="http://xmpp.org/extensions/xep-0177.html">XEP-0177</a>.</p>
- </tp:docstring>
- </property>
-
- <property name="GTalkP2PTransportAvailable"
- tp:name-for-bindings="GTalk_P2P_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the variant of ICE used by the Google Talk peer-to-peer
- connectivity establishment mechanism (as implemented in libjingle
- 0.3).</p>
- </tp:docstring>
- </property>
-
- <property name="WLM85TransportAvailable"
- tp:name-for-bindings="WLM_8_5_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the transport implemented by Windows Live Messenger 8.5 or
- later (which resembles ICE draft 6).</p>
- </tp:docstring>
- </property>
-
- <property name="WLM2009TransportAvailable"
- tp:name-for-bindings="WLM_2009_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the transport implemented by Windows Live Messenger 2009
- or later (which resembles ICE draft 19).</p>
- </tp:docstring>
- </property>
-
- </interface>
-</node>
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_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index b0e905f..5f5bd4b 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -18,9 +18,10 @@ 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.Channel.Type.ContactSearch.DRAFT"
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT2"
tp:causes-havoc='experimental'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:changed version="0.17.27">(draft 2)</tp:changed>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel type for searching server-stored user directories. A new
@@ -375,13 +376,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
- <signal name="SearchResultReceived"
- tp:name-for-bindings="Search_Result_Received">
- <arg name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>An integer handle for the contact, which will remain
- valid at least until this Channel closes</tp:docstring>
- </arg>
- <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:mapping name="Contact_Search_Result_Map">
+ <tp:docstring>A map from contact handle to search result.</tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of fields representing information about this
contact, in the same format used in the <tp:dbus-ref
@@ -402,9 +405,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
look it up.</p>
</tp:rationale>
</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="SearchResultReceived"
+ tp:name-for-bindings="Search_Result_Received">
+ <arg name="Result" type="a{ua(sasas)}" tp:type="Contact_Search_Result_Map">
+ <tp:docstring>A mapping from contact handle to an array of fields
+ representing information about this contact. Handles in this mapping
+ MUST remain valid until the Channel closes.</tp:docstring>
</arg>
<tp:docstring>
- Emitted when a search result is received from the server.
+ Emitted when a some search results are received from the server.
+ This signal can be fired arbitrarily many times so clients MUST NOT
+ assume they'll get only one signal.
</tp:docstring>
</signal>
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.xml b/spec/Channel_Type_Streamed_Media.xml
index db0b657..31ef965 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -549,6 +549,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
NATs.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="Immutable_Streams" value="32">
+ <tp:docstring>
+ Once streams have been requested for a channel to this handle (either
+ by calling <tp:member-ref>RequestStreams</tp:member-ref> on a channel
+ with no streams, or by specifying <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia.FUTURE">InitialAudio</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia.FUTURE">InitialAudio</tp:dbus-ref>
+ = <tt>True</tt> in the channel request), then they cannot be changed;
+ subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref> or
+ <tp:member-ref>RemoveStreams</tp:member-ref> will fail.
+
+ <tp:rationale>
+ For example, once an audio-only Google Talk call has started, it is
+ not possible to add a video stream; both audio and video must be
+ requested at the start of the call if video is desired. User
+ interfaces may use this pseudo-capability as a hint to display
+ separate "Audio call" and "Video call" buttons, rather than a
+ single "Call" button with the option to add and remove video once
+ the call has started for contacts without this flag.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
</tp:flags>
</interface>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 07a181e..8757d67 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,
@@ -147,5 +148,63 @@
</tp:docstring>
</property>
+ <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tt>True</tt>, once streams have been requested for this channel
+ (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or
+ <tp:member-ref>InitialVideo</tp:member-ref> when the channel is
+ requested, or by calling <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type.StreamedMedia'>RequestStreams</tp:dbus-ref>
+ on a channel with no streams), the channel's streams cannot be changed;
+ subsequent calls to <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type.StreamedMedia'>RequestStreams</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type.StreamedMedia'>RemoveStreams</tp:dbus-ref>
+ will fail.</p>
+
+ <p>If this property is missing, clients SHOULD assume that it is false,
+ and thus that the channel's streams can be changed once the call has
+ started.</p>
+
+ <p>If this property is present in all of the <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type'>StreamedMedia</tp:dbus-ref>
+ entries in a contact's capabilities, then user interfaces MAY choose
+ to show a separate "call" option for each class of call.</p>
+
+ <tp:rationale>
+ <p>On protocols like XMPP Jingle, it is possible to start an
+ audio-only call and then add a video stream, so the user interface
+ could be a single "call" button, which places an audio call, and an
+ "enable video" button in the call interface. However, on protocols
+ like Google Talk it is not possible to upgrade a call once it has
+ started; the user interface will thus need to adapt in order to
+ allow the user to place video calls.</p>
+ </tp:rationale>
+
+ <p>For incoming channels, this property MUST be included in the channel's immutable properties
+ (as announced in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>,
+ etc.). For outgoing calls, this property MAY be omitted from the
+ channel's immutable properties for calls without
+ <tp:member-ref>InitialAudio</tp:member-ref> or
+ <tp:member-ref>InitialVideo</tp:member-ref>, in which case its value
+ is undefined until <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type.StreamedMedia'>RequestStreams</tp:dbus-ref>
+ has been called at least once.</p>
+
+ <tp:rationale>
+ <p>The protocol mechanism used for the call might only be selected
+ when the CM knows what kind of call is desired. For example, if an
+ XMPP contact is signed in with Google Mail (with video support) and
+ Another client which supports modern Jingle (which supports
+ modifying the streams in a call) but only for audio calls, the
+ call's streams will be immutable if the UI requests Audio+Video,
+ but mutable if the UI just requests audio (a second audio stream
+ could be added, for instance).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
</interface>
</node>
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 8a920a1..dd26303 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -177,10 +177,11 @@
<arg name="Properties" type="a{sv}"
tp:type="Qualified_Property_Value_Map" direction="in">
<tp:docstring>
- <p>Properties of the channel dispatch operation. This MUST NOT
- include properties that could change, SHOULD include as many
- properties as possible given that constraint, and MUST include at
- least the <tp:dbus-ref
+ <p>Properties of the channel dispatch operation. The keys MUST be
+ fully qualified D-Bus property names. This MUST NOT include
+ properties that could change, SHOULD include as many properties as
+ possible given that constraint, and MUST include at least the
+ <tp:dbus-ref
namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref>
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index d366862..c6edf33 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -109,6 +109,71 @@
</tp:docstring>
</property>
+ <tp:simple-type name="Handler_Capability_Token" type="s"
+ array-name="Handler_Capability_Token_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>So far, all client capabilities are defined by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="Capabilities" tp:name-for-bindings="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]" 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>
+
+ <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref>
+ property, this property cannot change while the Handler owns its
+ Client bus name. However, the <code>.client</code> file, if any,
+ can change (due to upgrades or installation of pluggable codecs),
+ and the capabilities really supported by the handler might not
+ exactly match what is cached in the <code>.client</code> file.</p>
+
+ <tp:rationale>
+ <p>The client file is installed statically and is intended to list
+ codecs etc. that the handler guarantees it can support (e.g. by
+ having a hard dependency on them), whereas the running handler
+ process might be able to find additional codecs.</p>
+ </tp:rationale>
+ </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.xml b/spec/Connection.xml
index 2b03f96..2d04ce5 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -698,8 +698,18 @@ USA.</p>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error sending or receiving on the network socket.</p>
- <p>When disconnected for this reason, the equivalent D-Bus error is
- <code>org.freedesktop.Telepathy.Error.NetworkError</code>.</p>
+ <p>When the status changes from Connecting to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
+ or some more specific error.</p>
+
+ <p>When the status changes from Connected to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
+ or some more specific error.</p>
</tp:docstring>
</tp:enumvalue>
@@ -737,12 +747,17 @@ USA.</p>
<li>If the status change is from Connecting to Disconnected
and the 'register' parameter to RequestConnection was present
and true, the requested account could not be created on the
- server because it already exists.</li>
+ server because it already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
+ </li>
<li>If the status change is from Connecting to Disconnected
but the 'register' parameter is absent or false, the connection
manager could not connect to the specified account because
a connection to that account already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
<tp:rationale>
In some protocols, like XMPP (when connecting with the same
@@ -755,6 +770,8 @@ USA.</p>
the existing connection was automatically disconnected because
a new connection to the same account (perhaps from a different
client or location) was established.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
<tp:rationale>
In some protocols, like MSNP (when connecting twice with the
@@ -763,15 +780,6 @@ USA.</p>
</tp:rationale>
</li>
</ul>
-
- <p>When disconnected for this reason, the equivalent D-Bus error is
- <code>org.freedesktop.Telepathy.Error.NotYours</code>.
- </p>
-
- <tp:rationale>
- These three errors are distinct but very similar, and can be
- distinguished by other factors.
- </tp:rationale>
</tp:docstring>
</tp:enumvalue>
@@ -897,8 +905,12 @@ USA.</p>
<tp:docstring>
The name of a D-Bus error describing the error that occurred,
which may correspond to a
- <tp:type>Connection_Status_Reason</tp:type> or be a
- protocol-specific or connection-manager-specific error in a
+ <tp:type>Connection_Status_Reason</tp:type>, or may be a more
+ specific Telepathy error
+ (such as
+ <code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code>
+ for Connection_Status_Reason_Network_Error)
+ or a protocol-specific or connection-manager-specific error in a
suitable namespace.
<tp:rationale>
@@ -954,6 +966,16 @@ USA.</p>
</tp:docstring>
</signal>
+ <tp:contact-attribute name="contact-id" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
+ this is always present in the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
+ whether it was explicitly requested or not.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
index a599436..3c99b62 100644
--- a/spec/Connection_Interface_Aliasing.xml
+++ b/spec/Connection_Interface_Aliasing.xml
@@ -152,6 +152,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
+
+ <tp:contact-attribute name="alias" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetAliases</tp:member-ref>
+ (always present with some value, possibly the
+ same as Connection/contact-id, if information from the
+ Aliasing interface was requested)
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface on connections to support protocols where contacts have an
alias which they can change at will. Provides a method for the user to set
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index e6f7ac5..3b9290e 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -450,6 +450,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
+ <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+ (omitted from the result if the contact's avatar token is not known,
+ present as an empty string if the contact is known not to have
+ an avatar). Unlike in the
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+ method, the avatar tokens for the self handle aren't required to be
+ present. This attribute should not be used to determine whether or
+ not the Avatar needs to be set.
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for requesting avatars for contacts on a given connection,
receiving notification when avatars are changed, and publishing your own
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index 4e58d02..10d8102 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -56,12 +56,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
well-defined or consistent, and as far as we know it was never
implemented correctly. This usage is now deprecated.</tp:changed>
- <!-- FIXME: are the type-specific flags sufficient, in a world that has
- the Requests interface? It'd be nice if we could advertise capabilities
- that are not defined in terms of a channel type but rather in terms of
- a property or something, e.g. Channel.Interface.TLS.Secure for
- individually TLS'd channels. -->
-
<tp:flags name="Connection_Capability_Flags"
value-prefix="Connection_Capability_Flag" type="u">
<tp:flag suffix="Create" value="1">
@@ -160,6 +154,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
that the set is kept accurate - for example, a client may remove
capabilities or type specific capability flags when it exits
which are still provided by another client.</p>
+
+ <p>On connections managed by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>,
+ this method SHOULD NOT be used by clients other than the
+ ChannelDispatcher itself.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -231,6 +230,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
+ <tp:contact-attribute name="caps"
+ type="a(usuu)" tp:type="Contact_Capability">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetCapabilities</tp:member-ref>
+ (all of them will redundantly have the contact's handle as the
+ first member). 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.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
index 042b24b..d5ccebf 100644
--- a/spec/Connection_Interface_Contact_Capabilities.xml
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -18,10 +18,11 @@ 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>
+ <tp:changed version="0.17.27">(draft 2)</tp:changed>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Contact capabilities describe the channel classes which may be
@@ -38,38 +39,77 @@ 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:struct name="Handler_Capabilities"
+ array-name="Handler_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: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>
+ </tp:member>
- <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>
+ <tp:member name="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]">
+ <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>
- <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>
+ <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>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 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 +119,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="Handler_Capabilities" type="a(saa{sv}as)"
+ tp:type="Handler_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>Handler_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>
@@ -95,11 +170,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>The handle zero MUST NOT be included in the request.</p>
</tp:docstring>
</arg>
- <!-- There was a bug in dbus-glib that prevent to use the right type:
- Instead of a{ua(a{sv}as)}, we used a(ua{sv}as) as a workaround.
- See http://bugs.freedesktop.org/show_bug.cgi?id=17329
- Now there is a fix, so we don't use the workaround anymore.
- -->
<arg direction="out" type="a{ua(a{sv}as)}"
tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -161,6 +231,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
</tp:mapping>
+ <tp:contact-attribute name="capabilities"
+ type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetContactCapabilities</tp:member-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.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 1033e04..92c80c8 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -29,70 +29,6 @@
<p>Each contact attribute has an string identifier
(<tp:type>Contact_Attribute</tp:type>), which is namespaced
by the D-Bus interface which defines it.</p>
-
- <p>An initial set of contact attributes is defined here:</p>
-
- <dl>
- <dt>org.freedesktop.Telepathy.Connection/contact-id
- (type s)</dt>
- <dd>The same string that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
- (always present in the result)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias
- (type s)</dt>
- <dd>The same string that would be returned by <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">GetAliases</tp:dbus-ref>
- (always present with some value, possibly the
- same as Connection/contact-id, if information from the
- Aliasing interface was requested)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Avatars/token
- (type s, <tp:type>Avatar_Token</tp:type>)</dt>
- <dd>The same string that would be returned by <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
- (omitted from the result if the contact's avatar token is not known,
- present as an empty string if the contact is known not to have
- an avatar). Unlike in the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
- method, the avatar tokens for the self handle aren't required to be
- present. This attribute should not be used to determine whether or
- not the Avatar needs to be set.
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence
- (type (uss), <tp:type>Simple_Presence</tp:type>)</dt>
- <dd> The same struct that would be returned by
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
- (always present with some value if information from the
- SimplePresence interface was requested)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps
- (type a(usuu), <tp:type>Contact_Capability</tp:type>)</dt>
- <dd>The same structs that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Capabilities">GetCapabilities</tp:dbus-ref>
- (all of them will redundantly have the contact's handle as the
- first member). 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>
-
- <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps
- (type a{ua(a{sv}as)},
- <tp:type>Contact_Capabilities_Map</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>
- 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>
-
- <dt>org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT/location
- (type a{sv}, <tp:type>Location</tp:type>)</dt>
- <dd>The same struct used by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT">GetLocations</tp:dbus-ref>
- Omitted from the result if the contact's location
- is not known.</dd>
-
- </dl>
</tp:docstring>
<tp:simple-type name="Contact_Attribute" type="s">
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index 8821ec0..fdc622e 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -18,9 +18,8 @@ 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.Location.DRAFT"
- tp:causes-havoc='experimental'>
- <tp:added version="0.17.18">(as a draft)</tp:added>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Location">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -50,6 +49,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
possible.</p>
</tp:docstring>
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<tp:enum name="Location_Accuracy_Level" type="i">
<tp:docstring>
A location accuracy level. This should be kept in sync with
@@ -89,11 +90,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:enumvalue>
<tp:enumvalue suffix="Detailed" value="6">
<tp:docstring>
- The location's accuracy is given by the error, horizontal-error-m
- and/or vertical-error-m keys.
+ The location's accuracy is given by the accuracy key.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+ -->
<tp:mapping name="Location">
<tp:docstring>
@@ -137,6 +138,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
information about it</li>
</ul>
+ <p>Since the previous strings have data intended to be read by users,
+ the language used should be stated using:</p>
+
+ <ul>
+ <li>language - s: a specific language or locale of location
+ information in a format compatible to RFC 4646. Note that UTF-8
+ is the only allowed encoding, e.g. "en" or "fr-CA".</li>
+ </ul>
+
<p>Positions are represented by the following well-known keys:</p>
<ul>
@@ -164,6 +174,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
This is from XEP-0080
</tp:rationale>
</li>
+
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>):
an indication of accuracy, which SHOULD be omitted if it would be
Location_Accuracy_Level_None or
@@ -174,24 +187,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
with any future XEP-0080 terminology.
</tp:rationale>
</li>
- <li>error - d: horizontal position error in arc-minutes (1/60
- degree) if known
- <tp:rationale>
- This is from XEP-0080
- </tp:rationale>
- </li>
- <li>vertical-error-m - d: vertical position error in metres if
- known
- <tp:rationale>
- This exists as a struct field in GeoClue; the name is new
- in this specification.
- </tp:rationale>
- </li>
- <li>horizontal-error-m - d: horizontal position error in metres if
+ -->
+
+ <li>accuracy - d: horizontal position error in metres if
known
<tp:rationale>
- This exists as a struct field in GeoClue; the name is new
- in this specification.
+ This is from XEP-0080
</tp:rationale>
</li>
</ul>
@@ -211,12 +212,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
called "direction" in GeoClue
</tp:rationale>
</li>
- <li>climb - d: rate of change of 'alt' in metres per second
- <tp:rationale>
- This is a struct field in GeoClue; the name is new to this
- specification, but seems uncontroversial
- </tp:rationale>
- </li>
</ul>
<p>Other well-known keys:</p>
@@ -389,6 +384,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
set it to be as restrictive as possible (an empty whitelist, if
supported).</tp:docstring>
</property>
+
+ <tp:contact-attribute name="location"
+ type="a{sv}" tp:type="Location">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same mapping that would be returned by
+ <tp:member-ref>GetLocations</tp:member-ref> for this contact.
+ Omitted from the result if the contact's location
+ is not known.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 8446050..5c7ae97 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -395,7 +395,7 @@
This type isn't actually used by the SimplePresence interface, but
it's included here so it can be referenced by rich presence interfaces
such as <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">Location.DRAFT</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>.
</tp:docstring>
<tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
@@ -412,6 +412,16 @@
</tp:member>
</tp:struct>
+ <tp:contact-attribute name="presence"
+ type="(uss)" tp:type="Simple_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same struct that would be returned by
+ <tp:member-ref>GetPresences</tp:member-ref>
+ (always present with some value if information from the
+ SimplePresence interface was requested)</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface is for services which have a concept of presence which
can be published for yourself and monitored on your contacts.</p>
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index ad8f058..ad0f895 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -303,6 +303,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dt>stun-port (q)</dt>
<dd>The UDP port number on the stun-server to use for STUN. Only
significant if the stun-server is also supplied.</dd>
+
+ <dt>keepalive-interval (u)</dt>
+ <dd>The time in seconds between pings sent to the server to ensure
+ that the connection is still alive, or <tt>0</tt> to disable such
+ pings.</dd>
</dl>
<p>Every successful RequestConnection call will cause the emission of a
@@ -444,7 +449,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dt>b (boolean)</dt>
<dd>"true" (case-insensitively) or "1" means True, "false"
(case-insensitively) or "0" means False</dd>
- <dt>q, u, t (16-, 32-, 64-bit unsigned integer)</dt>
+ <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt>
<dd>ASCII decimal integer</dd>
<dt>n, i, x (16-, 32-, 64-bit signed integer)</dt>
<dd>ASCII decimal integer, optionally prefixed with "-"</dd>
diff --git a/spec/Debug.xml b/spec/Debug.xml
index a21d9db..70a82e9 100644
--- a/spec/Debug.xml
+++ b/spec/Debug.xml
@@ -17,9 +17,8 @@ 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.Debug.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.24"/>
+ <interface name="org.freedesktop.Telepathy.Debug">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for providing debug messages.</p>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index a8abd87..4937b53 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -17,7 +17,6 @@ EXTRA_DIST = \
Channel_Interface_Hold.xml \
Channel_Interface_HTML.xml \
Channel_Interface_Media_Signalling.xml \
- Channel_Interface_Media_Signalling_Future.xml \
Channel_Interface_Messages.xml \
Channel_Interface_Password.xml \
Channel_Interface_Transfer.xml \
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index d335e38..c9ae78f 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -265,12 +265,59 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enum name="Media_Stream_Error" type="u">
<tp:enumvalue suffix="Unknown" value="0">
<tp:docstring>
- An unknown error occured.
+ An unknown error occured.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="EOS" value="1">
<tp:docstring>
- The end of the stream was reached.
+ The end of the stream was reached.
+ </tp:docstring>
+ <tp:deprecated version="0.17.27">
+ This error has no use anywhere. In Farsight 1 times, it was used to
+ indicate a GStreamer EOS (when the end of a file is reached). But
+ since this is for live calls, it makes no sense.
+ </tp:deprecated>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no common codecs between the local side
+ and the other particpants in the call. The possible codecs are not
+ signalled here: the streaming implementation is assumed to report
+ them in an implementation-dependent way, e.g. Farsight should use
+ GstMissingElement.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connection_Failed" value="3">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ A network connection for the Media could not be established or was
+ lost.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Network_Error" value="4">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the networking stack
+ (other than the connection failure).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="No_Codecs" value="5">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no installed codecs for this media type.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_CM_Behavior" value="6">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ The CM is doing something wrong.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Media_Error" value="7">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the media processing stack.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
diff --git a/spec/all.xml b/spec/all.xml
index dd228e2..876d150 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.26</tp:version>
+<tp:version>0.17.27</tp:version>
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
@@ -106,7 +106,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_HTML.xml"/>
<xi:include href="Channel_Interface_Password.xml"/>
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
- <xi:include href="Channel_Interface_Media_Signalling_Future.xml"/>
<xi:include href="Channel_Interface_Messages.xml"/>
<xi:include href="Channel_Interface_Tube.xml"/>
</tp:section>
diff --git a/spec/errors.xml b/spec/errors.xml
index 7b1798d..f32acea 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -71,9 +71,13 @@
</tp:error>
<tp:error name="Not Yours">
- <tp:docstring>
- The requested channel or other resource already exists, and another
- client is responsible for it
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested channel or other resource already exists, and another
+ user interface in this session is responsible for it.</p>
+
+ <p>User interfaces SHOULD handle this error unobtrusively, since it
+ indicates that some other user interface is already processing the
+ channel.</p>
</tp:docstring>
</tp:error>
@@ -260,7 +264,9 @@
<tp:error name="Busy">
<tp:docstring>
Used to represent a user being removed from a channel because of a
- "busy" indication.
+ "busy" indication. This error SHOULD NOT be used to represent a server
+ or other infrastructure being too busy to process a request - for that,
+ see ServerBusy.
<tp:rationale>
This corresponds to Busy in the
@@ -325,6 +331,72 @@
</tp:docstring>
</tp:error>
+ <tp:error name="Already Connected">
+ <tp:docstring>
+ Raised when the user attempts to connect to an account but they are
+ already connected (perhaps from another client or computer), and the
+ protocol or account settings do not allow this.
+
+ <tp:rationale>
+ XMPP can have this behaviour if the user chooses the same resource
+ in both clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Replaced">
+ <tp:docstring>
+ Raised by an existing connection to an account if it is replaced by
+ a new connection (perhaps from another client or computer).
+
+ <tp:rationale>
+ In MSNP, when connecting twice with the same Passport, the new
+ connection "wins" and the old one is automatically disconnected.
+ XMPP can also have this behaviour if the user chooses the same
+ resource in two clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Registration Exists">
+ <tp:docstring>
+ Raised during in-band registration if the server indicates that the
+ requested account already exists.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Service Busy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Raised if a server or some other piece of infrastructure cannot process
+ the request, e.g. due to resource limitations. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ This is not the same error as Busy, which indicates that a
+ <em>user</em> is busy.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Resource Unavailable">
+ <tp:docstring>
+ Raised if a request cannot be satisfied because a process local to the
+ user has insufficient resources. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ For instance, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ might raise this error for some or all channel requests if it has
+ detected that there is not enough free memory.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
diff --git a/telepathy-glib/connection.xml b/telepathy-glib/connection.xml
index 79c9747..0350314 100644
--- a/telepathy-glib/connection.xml
+++ b/telepathy-glib/connection.xml
@@ -13,5 +13,6 @@
<xi:include href="../spec/Connection_Interface_Presence.xml"/>
<xi:include href="../spec/Connection_Interface_Contacts.xml"/>
<xi:include href="../spec/Connection_Interface_Requests.xml"/>
+<xi:include href="../spec/Connection_Interface_Location.xml"/>
</tp:spec>
--
1.5.6.5
More information about the telepathy-commits
mailing list