[telepathy-glib/master] Update spec to 0.17.28
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Sep 14 05:37:56 PDT 2009
* ContactCapabilities undrafted (identical to draft 2)
* In_Progress call state
* InitialAudio, InitialVideo, ImmutableStreams properties on streamed
media calls
---
spec/Channel.xml | 11 +-
spec/Channel_Interface_Call_State.xml | 10 +
spec/Channel_Interface_Tube.xml | 2 +-
spec/Channel_Type_File_Transfer.xml | 2 +-
spec/Channel_Type_Room_List.xml | 2 +-
spec/Channel_Type_Streamed_Media.xml | 174 ++++++++++++++--
spec/Channel_Type_Streamed_Media_Future.xml | 210 --------------------
spec/Channel_Type_Text.xml | 4 +-
spec/Connection.xml | 22 ++-
spec/Connection_Interface_Aliasing.xml | 7 +-
spec/Connection_Interface_Contact_Capabilities.xml | 6 +-
spec/Connection_Interface_Renaming.xml | 2 +-
spec/Connection_Interface_Requests.xml | 2 +
spec/Makefile.am | 1 -
spec/all.xml | 3 +-
spec/errors.xml | 2 +-
16 files changed, 198 insertions(+), 262 deletions(-)
delete mode 100644 spec/Channel_Type_Streamed_Media_Future.xml
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 2937680..223a612 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -362,10 +362,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
handle).</p>
<tp:rationale>
- <p>The careful wording about the self-handle is because the Renaming
- interface can cause the return from Connection.GetSelfHandle to
- change. It's something of a specification bug that we don't signal
- this in the Connection interface yet.</p>
+ <p>On some protocols, the SelfHandle may change (as signalled by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>),
+ but this property is immutable. Hence, locally-requested channels'
+ InitiatorHandle and InitiatorID may not match the current
+ SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
+ determine whether the channel was created locally.</p>
</tp:rationale>
<p>For channels requested by a remote user, this MUST be their handle.
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
index 78a123f..b569a7f 100644
--- a/spec/Channel_Interface_Call_State.xml
+++ b/spec/Channel_Interface_Call_State.xml
@@ -116,6 +116,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
diverted.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ destination contact may not have been made aware of the call yet
+ (so the Ringing state is not appropriate). This corresponds to SIP's
+ status code 183 Session Progress, and could be used when the
+ outgoing call has reached a gateway, for instance.
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
</interface>
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 45f7510..858a15d 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.DRAFT2">UpdateCapabilities</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
that such a tube is supported. They SHOULD also allow clients to offer tubes with any
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index c53444d..19dda06 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.DRAFT2">UpdateCapabilities</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">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_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 93ea777..6d6ce31 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -74,7 +74,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dl>
<dt>handle-name (s)</dt>
- <dd>The string name of the room handle (as would be returned by
+ <dd>The identifier of the room (as would be returned by
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd>
<dt>name (s)</dt>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 31ef965..4c651cd 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -441,6 +441,156 @@ 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), a stream of a different content type cannot be added;
+ subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref>
+ that attempt to do so 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 the "allowed" set 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>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.
+ </p>
+ </tp:rationale>
+
+ <p>This property is immutable, and therefore SHOULD be announced
+ in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>,
+ etc.</p>
+ </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 +667,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">
@@ -552,25 +701,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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>
+ Channels whose target handle is this contact will have
+ <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>.
</tp:docstring>
</tp:flag>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
deleted file mode 100644
index 8757d67..0000000
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ /dev/null
@@ -1,210 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Type_Streamed_Media_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.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.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
- 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.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,
- 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>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 7d6e314..5315a55 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -419,8 +419,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:property>
<tp:property name="name" type="s">
<tp:docstring>
- A human-visible name for the channel, if it differs from the string
- version of the channel's handle.
+ A human-visible name for the channel, if it differs from the channel's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>.
</tp:docstring>
</tp:property>
<tp:property name="description" type="s">
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 2d04ce5..72e1bb8 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -251,7 +251,7 @@ USA.</p>
<arg direction="out" type="as" name="Identifiers">
<tp:docstring>
- An array of handle names in the same order as the given numbers
+ An array of identifiers corresponding to the given handles, in the same order.
</tp:docstring>
</arg>
@@ -591,16 +591,16 @@ USA.</p>
</tp:docstring>
</arg>
- <arg direction="in" name="Names" type="as">
+ <arg direction="in" name="Identifiers" type="as">
<tp:docstring>
- An array of names of entities to request handles for
+ An array of identifiers of entities to request handles for
</tp:docstring>
</arg>
<arg direction="out" type="au" tp:type="Handle[]"
name="Handles">
<tp:docstring>
- An array of integer handle numbers in the same order as the given strings
+ An array of integer handle numbers in the same order as the given identifiers.
</tp:docstring>
</arg>
@@ -611,16 +611,18 @@ USA.</p>
client who invokes this method, and must not deallocate the handles
until the client disconnects from the bus or calls the
<tp:member-ref>ReleaseHandles</tp:member-ref>
- method. Where the name refers to an entity that already has a handle
- in this connection manager, this handle should be returned instead.
- The handle number 0 must not be returned by the connection manager.
+ method. Where the identifier refers to an entity that already has a
+ handle in this connection manager, this handle should be returned
+ instead. The handle number 0 must not be returned by the connection
+ manager.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
- The given name does not identify a valid entity of the given type.
+ The given identifier does not identify a valid entity of the given
+ type.
<tp:rationale>
For instance, an XMPP connection would raise this error for
@@ -1040,9 +1042,9 @@ USA.</p>
ambiguous. Connection manager implementations should reference count these
handles to determine if they are in use either by any active clients or any
open channels, and may deallocate them when this ceases to be true. Clients
- may request handles of a given type and name with the
+ may request handles of a given type and identifier with the
<tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
- name of handles with the <tp:member-ref>InspectHandles</tp:member-ref>
+ identifier with the <tp:member-ref>InspectHandles</tp:member-ref>
method, keep handles from being released with
<tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
longer storing handles with
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
index 3c99b62..9675771 100644
--- a/spec/Connection_Interface_Aliasing.xml
+++ b/spec/Connection_Interface_Aliasing.xml
@@ -119,9 +119,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<tp:docstring>
Request the value of several contacts' aliases at once. This SHOULD
- only return cached aliases, falling back on the handle name if none is
- present. Also if there was no cached alias, a request SHOULD be started
- of which the result is later signalled by
+ only return cached aliases, falling back on the contact identifier
+ (i.e. the string corresponding to the handle) if none is present. Also
+ if there was no cached alias, a request SHOULD be started of which the
+ result is later signalled by
<tp:member-ref>AliasesChanged</tp:member-ref>.
</tp:docstring>
<tp:possible-errors>
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
index d5ccebf..6596ecb 100644
--- a/spec/Connection_Interface_Contact_Capabilities.xml
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -18,11 +18,9 @@ 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.DRAFT2"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">
<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:added version="0.17.28">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Contact capabilities describe the channel classes which may be
diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml
index c81d7ed..d08b748 100644
--- a/spec/Connection_Interface_Renaming.xml
+++ b/spec/Connection_Interface_Renaming.xml
@@ -65,7 +65,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</signal>
<method name="RequestRename" tp:name-for-bindings="Request_Rename">
- <arg direction="in" name="Name" type="s">
+ <arg direction="in" name="Identifier" type="s">
<tp:docstring>
The desired identifier
</tp:docstring>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 5c56db3..d8239e5 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -252,6 +252,7 @@
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
@@ -383,6 +384,7 @@
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index ec9610e..ecccdcc 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -29,7 +29,6 @@ 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 876d150..076bb83 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.27</tp:version>
+<tp:version>0.17.28</tp:version>
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
@@ -79,7 +79,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
<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"/>
diff --git a/spec/errors.xml b/spec/errors.xml
index f32acea..22a629b 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -48,7 +48,7 @@
<tp:error name="Invalid Handle">
<tp:docstring>
- The contact name specified is unknown on this channel or connection.
+ The handle specified is unknown on this channel or connection.
</tp:docstring>
</tp:error>
--
1.5.6.5
More information about the telepathy-commits
mailing list