[telepathy-spec/master] Declare InitialAudio, InitialVideo, ImmutableStreams to be stable
Simon McVittie
simon.mcvittie at collabora.co.uk
Fri Sep 11 09:29:43 PDT 2009
---
spec/Channel_Type_Streamed_Media.xml | 176 +++++++++++++++++++++++++-
spec/Channel_Type_Streamed_Media_Future.xml | 169 -------------------------
2 files changed, 169 insertions(+), 176 deletions(-)
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 31ef965..c881a40 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -441,6 +441,170 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</signal>
+ <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</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 among their channel classes if
+ calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">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,
+ 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 }</li>
+ <li>{ ChannelType = StreamedMedia, InitialAudio = true }
+ if receiving calls with audio is supported</li>
+ <li>{ ChannelType = StreamedMedia, InitialVideo = true }
+ if receiving calls with video 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>
+ </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>
+
+ <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:member-ref>RequestStreams</tp:member-ref> on a channel with no
+ streams), the channel's streams cannot be changed;
+ subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref>
+ or <tp:member-ref>RemoveStreams</tp:member-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 StreamedMedia
+ 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:member-ref>RequestStreams</tp:member-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>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel that can send and receive streamed media such as audio or video.
Provides a number of methods for listing and requesting new streams, and
@@ -517,8 +681,7 @@ 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. See the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>
+ interface. See the <tp:member-ref>InitialAudio</tp:member-ref>
property for details of the mechanisms that will replace this.
</tp:docstring>
<tp:flag suffix="Audio" value="1">
@@ -554,11 +717,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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;
+ with no streams, or by specifying
+ <tp:member-ref>InitialAudio</tp:member-ref> = <tt>True</tt> or
+ <tp:member-ref>InitialVideo</tp:member-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.
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 09e54ef..921f910 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -37,174 +37,5 @@
</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</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 among their channel classes if
- calling <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">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,
- 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 }</li>
- <li>{ ChannelType = StreamedMedia, InitialAudio = true }
- if receiving calls with audio is supported</li>
- <li>{ ChannelType = StreamedMedia, InitialVideo = true }
- if receiving calls with video 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>
- </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>
-
- <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>
--
1.5.6.5
More information about the telepathy-commits
mailing list