[Telepathy-commits] [telepathy-spec/master] StreamedMedia: add a draft version of InitialAudio, InitialVideo
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Jan 27 09:46:50 PST 2009
These allow us to represent the audio and video capabilities in various
contexts.
---
spec/Channel_Type_Streamed_Media.xml | 10 ++-
spec/Channel_Type_Streamed_Media_Future.xml | 160 +++++++++++++++++++++++++++
spec/all.xml | 1 +
3 files changed, 170 insertions(+), 1 deletions(-)
create mode 100644 spec/Channel_Type_Streamed_Media_Future.xml
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 0a69782..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
@@ -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..6dfb4c7
--- /dev/null
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -0,0 +1,160 @@
+<?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, 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 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/all.xml b/spec/all.xml
index 7fc0e75..4318498 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -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"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list