[Telepathy-commits] [telepathy-glib/master] Update to spec 0.17.19 release
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Jan 28 08:46:29 PST 2009
---
spec/Channel_Interface_Group.xml | 124 +++++++++++---
spec/Channel_Interface_Media_Signalling.xml | 46 ++++--
spec/Channel_Interface_Media_Signalling_Future.xml | 189 ++++++++++++++++++++
spec/Channel_Type_Streamed_Media.xml | 12 +-
spec/Channel_Type_Streamed_Media_Future.xml | 166 +++++++++++++++++
spec/Connection.xml | 69 ++++----
spec/Makefile.am | 2 +
spec/all.xml | 4 +-
spec/errors.xml | 61 +++++++
9 files changed, 604 insertions(+), 69 deletions(-)
create mode 100644 spec/Channel_Interface_Media_Signalling_Future.xml
create mode 100644 spec/Channel_Type_Streamed_Media_Future.xml
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index de429b9..490258f 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -572,24 +572,71 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Offline" value="1">
- <tp:docstring>
- The change is due to a user going offline. Also used when
- user is already offline, but this wasn't known previously.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a user going offline. Also used when
+ user is already offline, but this wasn't known previously.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is offline, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Offline.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If a handle is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Offline</code>.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Kicked" value="2">
- <tp:docstring>
- The change is due to a kick operation.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Busy" value="3">
- <tp:docstring>
- The change is due to a busy indication.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a busy indication.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is busy, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Busy.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Busy</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Invited" value="4">
<tp:docstring>
- The change is due to an invitation.
+ The change is due to an invitation. This reason SHOULD only be used
+ when contacts are added to the remote-pending set (to indicate that
+ the contact has been invited) or to the members (to indicate that
+ the contact has accepted the invitation).
+
+ <tp:rationale>
+ Otherwise, what would it mean?
+ </tp:rationale>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Banned" value="5">
@@ -611,23 +658,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The change is because the requested contact does not exist.</p>
+ <p>For instance, if the user invites a nonexistent contact to a
+ chatroom or attempts to call a nonexistent contact, this could
+ be indicated by the CM adding that contact's handle to
+ remote-pending for reason None or Invited, then removing it for
+ reason Invalid_Contact. In the case of a 1-1 StreamedMedia
+ call, the CM SHOULD remove the self handle from the Group
+ in the same signal.</p>
+
<tp:rationale>
- <p>For instance, if the user invites a nonexistent contact to a
- chatroom or attempts to call a nonexistent contact, this could
- be indicated by the CM adding that contact's handle to
- remote-pending for reason None or Invited, then removing it for
- reason Invalid_Contact.</p>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
</tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="No_Answer" value="8">
- <tp:docstring>
- The change is because the requested contact did not respond.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact did not respond.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called did not respond, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason No_Answer.</p>
+
+ <tp:rationale>
+ Documenting existing practice.
+ </tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.NoAnswer</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Renamed" value="9">
- <tp:docstring>
- The change is because a contact's unique identifier changed.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because a contact's unique identifier changed.
There must be exactly one handle in the removed set and exactly
one handle in one of the added sets. The <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref>
@@ -635,13 +709,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref>
interface will have been emitted for the same handles,
- shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.
+ shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Permission_Denied" value="10">
- <tp:docstring>
- The change is because there was no permission to contact the
- requested handle.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because there was no permission to contact the
+ requested handle.</p>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Separated" value="11">
@@ -670,6 +749,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
the group with reason Separated. Application protocols in Tubes
should be prepared to cope with this situation.
</p>
+
+ <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be
+ removed from channels with this reason.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 05b618b..8249331 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -22,6 +22,41 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for signalling a channel containing synchronised media
+ sessions which can contain an arbitrary number of streams. The
+ presence of this interface on a Channel indicates that the connection
+ manager will not carry out the actual streaming for this channel,
+ and that the client handling the channel is responsible for doing
+ so; in most cases we recommend doing this by using the
+ telepathy-farsight library.</p>
+
+ <tp:rationale>
+ <p>Streaming audio and (particularly) video requires a high level of
+ integration with the UI, and having the connection manager act as
+ a proxy would be likely to introduce unacceptable latency. As a
+ result, audio/video streaming is offloaded into the client
+ where possible, as an exception to the general design of
+ Telepathy.</p>
+ </tp:rationale>
+
+ <p>The negotiation interface is based on the API of the
+ <a href="http://farsight.freedesktop.org/">Farsight</a> library.
+ This, in turn, is based upon the IETF MMusic ICE drafts, where
+ connections are established by signalling potential connection
+ candidates to the peer until a usable connection is found, and
+ codecs are negotiated with an SDP-style offer and answer. However,
+ the principles should be applicable to other media streaming methods
+ and the API re-used without difficulty.</p>
+
+ <p>Note that the naming conventions used in the MediaStreamHandler
+ and MediaSessionHandler interfaces are rather confusing; methods
+ have signal-like names and signals have method-like names, due to
+ the API being based rather too closely on that of Farsight. This
+ is for historical reasons and will be fixed in a future release
+ of the Telepathy specification.</p>
+ </tp:docstring>
+
<tp:simple-type name="Media_Session_Type" type="s">
<tp:docstring>The type of a media session. Currently, the only supported
value is "rtp".</tp:docstring>
@@ -105,17 +140,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:property>
- <tp:docstring>
- An interface for signalling a channel containing synchronised media
- sessions which can contain an arbitrary number of streams. The negotiation
- interface is based closely around the API of the Farsight library
- (http://farsight.sourceforge.net/). This in turn is based upon the IETF
- MMusic ICE drafts where connections are established by signalling potential
- connection candidates to the peer until a usable connection is found, and
- codecs are negotiated with an SDP-style offer and answer. However, the
- principles should be applicable to other media streaming methods and the
- API re-used without difficulty.
- </tp:docstring>
</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
new file mode 100644
index 0000000..e1d2d25
--- /dev/null
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -0,0 +1,189 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Media_Signalling_Future"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 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.Type.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 that are able to receive calls with particular NAT
+ traversal mechanisms MAY 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.DRAFT</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.DRAFT">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.
+ If a client has indicated support for any particular transports,
+ the connection manager SHOULD advertise support for
+ each transport that is supported by any client, and also
+ supported by the CM itself.</p>
+
+ <tp:rationale>
+ <p>This minimizes the possibility that a call will be started that
+ cannot in fact succeed, because the intersection of the contacts'
+ available transports is empty.</p>
+ </tp:rationale>
+
+ <p>If no client has mentioned any of the transports known to the
+ connection manager in a call to SetSelfCapabilities, the connection
+ manager SHOULD advertise support for every transport that it can
+ signal.</p>
+
+ <tp:rationale>
+ <p>This simplifies implementation on integrated platforms like Maemo,
+ where it can be assumed that client libraries will support all the
+ "standard" transports known to any connection manager, and
+ lowers the "barrier to entry" for new Telepathy clients.</p>
+ </tp:rationale>
+
+ <p>Clients making outgoing calls for which the same client that made
+ the request will handle the streaming MAY indicate their ability or
+ inability to handle particular transports by including
+ <code>ICETransportAvailable = true</code>,
+ <code>RawUDPTransportAvailable = false</code>, etc.
+ in the request properties parameter of their call to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
+ or similar functions. When they do so, the connection manager
+ SHOULD attempt to use a transport that the client has indicated
+ it is able to handle; if this is not possible, the connection
+ manager SHOULD raise an error instead of creating a channel.</p>
+
+ <tp:rationale>
+ <p>This enables such clients to restrict the CM to the subset of
+ transports supported by that particular client.</p>
+ </tp:rationale>
+
+ <p>Clients making outgoing calls for which they will not themselves
+ handle the streaming (e.g. an address book starting a call which
+ will be streamed by a separate call UI) SHOULD NOT include those
+ properties in the request.</p>
+
+ <tp:rationale>
+ <p>In general, such a client can't know the capabilities of the
+ streaming implementation, or even which streaming implementation
+ will be used.</p>
+ </tp:rationale>
+
+ <p>In the absence of any indication of supported transports from the
+ client, the connection manager SHOULD assume that the transports
+ indicated by calling SetSelfCapabilities are available. If
+ no transports were indicated as supported by calling
+ SetSelfCapabilities either, it SHOULD assume that any transport
+ that it can signal will be acceptable.</p>
+
+ <p>If this property, or any of the similar transport availability
+ properties, is passed to EnsureChannel (as opposed to CreateChannel),
+ the connection manager SHOULD ignore these properties when checking
+ whether it can return an existing channel as suitable; these
+ properties only become significant when the connection manager has
+ decided to create a new channel.</p>
+ </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="GoogleP2PTransportAvailable"
+ tp:name-for-bindings="Google_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="MSNTransportAvailable"
+ tp:name-for-bindings="MSN_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 MSN.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 599fe16..b89065b 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -208,6 +208,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
will be emitted with the
MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
with the flag cleared when the remote end has replied.</p>
+
+ <p>If streams of the requested types have already been requested
+ via this method or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>/<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialVideo</tp:dbus-ref>,
+ this method SHOULD return successfully.</p>
</tp:docstring>
<tp:changed version="0.17.2">
<p>It is valid to use a handle which is neither
@@ -373,7 +379,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>In the past, several other patterns have been used to place outgoing
calls; see
- <tt>http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels</tt>
+ <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a>
for the details.</p>
<p>In general this should be used in conjunction with the <tp:dbus-ref
@@ -391,7 +397,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The channel-type-specific capability flags used for
Channel.Type.StreamedMedia in the <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref>
- interface.
+ interface. See the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>
+ property for details of the mechanisms that will replace this.
</tp:docstring>
<tp:flag suffix="Audio" value="1">
<tp:docstring>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
new file mode 100644
index 0000000..2421ed6
--- /dev/null
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Streamed_Media_Future"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 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.Type.StreamedMedia.FUTURE">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <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.Type.StreamedMedia</tp:dbus-ref>
+ interface in future. It should be considered to be conceptually part
+ of the core StreamedMedia 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="InitialAudio" tp:name-for-bindings="Initial_Audio"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If set to true in a channel request that will create a new channel,
+ the connection manager should immediately attempt to establish an
+ audio stream to the remote contact, making it unnecessary for the
+ client to call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p>
+
+ <p>If this property, or InitialVideo, is passed to EnsureChannel
+ (as opposed to CreateChannel), the connection manager SHOULD ignore
+ these properties when checking whether it can return an existing
+ channel as suitable; these properties only become significant when
+ the connection manager has decided to create a new channel.</p>
+
+ <p>If true on a requested channel, this indicates that the audio
+ stream has already been requested and the client does not need to
+ call RequestStreams, although it MAY still do so.</p>
+
+ <p>If true on an unrequested (incoming) channel, this indicates that
+ the remote contact initially requested an audio stream; this does
+ not imply that that audio stream is still active (as indicated by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</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>
+
+ <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale>
+
+ <p>Connection managers capable of signalling audio calls to contacts
+ SHOULD include a channel class in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
+ = <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = Contact in the fixed properties dictionary, and InitialAudio
+ (and also InitialVideo, if applicable) in the allowed properties
+ list. Clients wishing to discover whether a connection manager
+ can signal audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all protocols support signalling video calls, and it would be
+ possible (although unlikely) to have a protocol where only video,
+ and not audio, could be signalled.</p>
+ </tp:rationale>
+
+ <p>Connection managers that support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</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
+ in the fixed properties dictionary, and InitialAudio and/or
+ InitialVideo in the allowed properties list. Clients wishing to
+ discover whether a particular contact is likely to be able to
+ receive audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all clients support video calls, and it would also be
+ possible (although unlikely) to have a client which could only
+ stream video, not audio.</p>
+ </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>
+ (clients of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</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.DRAFT">HandlerChannelFilter</tp:dbus-ref>
+ properties):</p>
+
+ <ul>
+ <li>{ ChannelType = StreamedMedia }</li>
+ <li>{ ChannelType = StreamedMedia, InitialAudio = true }
+ if receiving audio-only or audio+video calls is supported</li>
+ <li>{ ChannelType = StreamedMedia, InitialVideo = true }
+ if receiving video-only or audio+video calls is supported</li>
+ </ul>
+
+ <tp:rationale>
+ <p>Connection managers for protocols with capability discovery,
+ like XMPP, need this information to advertise the appropriate
+ capabilities for their protocol.</p>
+ </tp:rationale>
+
+ <p>If { ChannelType = StreamedMedia } is passed to
+ SetSelfCapabilities, but no more specific channel class for
+ audio or video has been passed to that method (in the presence
+ of a ChannelDispatcher, this would mean that there is at least one
+ client with that channel class in its HandlerChannelFilter, but
+ no installed client has the more specific channel classes in its
+ HandlerChannelFilter), then the connection manager SHOULD advertise
+ support for every content type (audio or video) that it
+ supports.</p>
+
+ <tp:rationale>
+ <p>This lowers the "barrier to entry" by allowing a simple client
+ to say merely that it supports streamed media at all.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
+ a video stream. This property is immutable (cannot change).</p>
+
+ <p>In particular, note that if this property is false, this does not
+ imply that an active video stream has not been added, only that no
+ video stream was active at the time the channel appeared.</p>
+
+ <p>This property is the correct way to discover whether connection
+ managers, contacts etc. support video calls; it appears in
+ capabilities structures in the same way as InitialAudio.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 84f54a7..97a3c4c 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -866,45 +866,46 @@ USA.</p>
information given by this signal can be used to supplement the
StatusChanged signal.</p>
</tp:rationale>
+ </tp:docstring>
- <arg name="Error" type="s" tp:type="DBus_Error_Name">
- <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
- suitable namespace.
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <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
+ suitable namespace.
- <tp:rationale>
- For instance, a SIP connection manager could signal
- "402 Payment Required" as an error in a
- connection-manager-specific namespace, or a link-local
- XMPP implementation that used Avahi could provide the error
- given to it by the avahi-daemon.
- </tp:rationale>
- </tp:docstring>
- </arg>
+ <tp:rationale>
+ For instance, a SIP connection manager could signal
+ "402 Payment Required" as an error in a
+ connection-manager-specific namespace, or a link-local
+ XMPP implementation that used Avahi could provide the error
+ given to it by the avahi-daemon.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
- <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Additional information about the error, which may include
- the following well-known keys:</p>
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about the error, which may include
+ the following well-known keys:</p>
- <dl>
- <dt>debug-message (s)</dt>
- <dd>Debugging information on the change, corresponding to the
- message part of a D-Bus error message, which SHOULD NOT be
- displayed to users under normal circumstances</dd>
- </dl>
+ <dl>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ </dl>
+
+ <tp:rationale>
+ <p>This argument allows for future extensions. For instance,
+ if indicating DNS lookup failure, we could define a key
+ that indicates the hostname that could not be found.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
- <tp:rationale>
- <p>This argument allows for future extensions. For instance,
- if indicating DNS lookup failure, we could define a key
- that indicates the hostname that could not be found.</p>
- </tp:rationale>
- </tp:docstring>
- </arg>
- </tp:docstring>
</signal>
<signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
diff --git a/spec/Makefile.am b/spec/Makefile.am
index 984a52f..3e12b10 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -17,6 +17,7 @@ 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 \
@@ -29,6 +30,7 @@ EXTRA_DIST = \
Channel_Type_Room_List.xml \
Channel_Type_Stream_Tube.xml \
Channel_Type_Streamed_Media.xml \
+ Channel_Type_Streamed_Media_Future.xml \
Channel_Type_Text.xml \
Channel_Type_Tubes.xml \
Channel.xml \
diff --git a/spec/all.xml b/spec/all.xml
index 7fc0e75..7745d54 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.18.1</tp:version>
+<tp:version>0.17.19</tp:version>
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
@@ -45,6 +45,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Future.xml"/>
<xi:include href="Channel_Type_Contact_List.xml"/>
<xi:include href="Channel_Type_Streamed_Media.xml"/>
+<xi:include href="Channel_Type_Streamed_Media_Future.xml"/>
<xi:include href="Channel_Type_Room_List.xml"/>
<xi:include href="Channel_Type_Text.xml"/>
<xi:include href="Channel_Type_Tubes.xml"/>
@@ -62,6 +63,7 @@ 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"/>
diff --git a/spec/errors.xml b/spec/errors.xml
index 954a575..0a2d7d2 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -235,6 +235,67 @@
not having required capabilities.
</tp:docstring>
</tp:error>
+
+ <tp:error name="Offline">
+ <tp:docstring>
+ Raised when requested functionality is unavailable because a contact is
+ offline.
+
+ <tp:rationale>
+ This corresponds to Offline in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Channel.Kicked">
+ <tp:docstring>
+ Used to represent a user being ejected from a channel by another user,
+ for instance being kicked from a chatroom.
+
+ <tp:rationale>
+ This corresponds to Kicked in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Busy">
+ <tp:docstring>
+ Used to represent a user being removed from a channel because of a
+ "busy" indication.
+
+ <tp:rationale>
+ This corresponds to Busy in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="No Answer">
+ <tp:docstring>
+ Used to represent a user being removed from a channel because they did
+ not respond, e.g. to a StreamedMedia call.
+
+ <tp:rationale>
+ This corresponds to No_Answer in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Does Not Exist">
+ <tp:docstring>
+ Raised when the requested user does not, in fact, exist.
+
+ <tp:rationale>
+ This corresponds to Invalid_Contact in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be
+ used to represent other things not existing (like chatrooms, perhaps).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
--
1.5.6.5
More information about the telepathy-commits
mailing list