[telepathy-gabble/master] Update the Call spec to the 0.19.0 version
Sjoerd Simons
sjoerd.simons at collabora.co.uk
Tue Dec 29 05:35:06 PST 2009
---
extensions/Call_Content.xml | 76 ++--
extensions/Call_Content_Codec_Offer.xml | 7 +-
extensions/Call_Content_Interface_Media.xml | 170 ++++++--
extensions/Call_Stream.xml | 78 +++-
extensions/Call_Stream_Endpoint.xml | 14 +-
extensions/Call_Stream_Interface_Media.xml | 251 +++++++++---
extensions/Channel_Type_Call.xml | 631 ++++++++++++++++++++++-----
extensions/all.xml | 17 +
src/call-channel.c | 4 +-
tests/twisted/constants.py | 14 +-
10 files changed, 990 insertions(+), 272 deletions(-)
diff --git a/extensions/Call_Content.xml b/extensions/Call_Content.xml
index b7f52be..1d5e891 100644
--- a/extensions/Call_Content.xml
+++ b/extensions/Call_Content.xml
@@ -20,63 +20,77 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Content.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Content.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
This object represents one Content inside a Call. For example in an
audio/video call there would be one audio and one video content. Each
content has one or more <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Call">Stream.Draft</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Call">Stream.DRAFT</tp:dbus-ref>
objects which represent the actual transport to one or more contacts.
</tp:docstring>
<property name="Name" tp:name-for-bindings="Name" type="s" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> The name of the content </p>
+ <p>The name of the content.
+ [FIXME: rationale?]</p>
</tp:docstring>
</property>
<property name="Type" tp:name-for-bindings="Type"
- type="u" tp:Type="Media_Stream_type" access="read">
+ type="u" tp:type="Media_Stream_Type" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> The media type of this content </p>
+ <p>The media type of this content</p>
</tp:docstring>
</property>
<property name="Creator" tp:name-for-bindings="Creator"
- type="u" tp:Type="Contact_Handle" access="read">
+ type="u" tp:type="Contact_Handle" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> Creator of this content </p>
+ <p>The creator of this content</p>
</tp:docstring>
</property>
- <tp:enum name="CallContentDisposition" type="u">
+ <tp:enum name="Call_Content_Disposition" type="u">
+ <tp:docstring>
+ [FIXME]
+ </tp:docstring>
+
<tp:enumvalue suffix="None" value="0">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The content has no specific disposition
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="EarlyMedia" value="1">
+ <tp:enumvalue suffix="Early_Media" value="1">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The content has no specific disposition
+ [FIXME: what does this mean?]
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Initial" value="2">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The content was initially part of the call. When answer is called on
- the channel, all streams of this content will be set to sending if
- they were pending.
+ <p>The content was initially part of the call. When <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"
+ >Accept</tp:dbus-ref> is called on the channel, all streams of
+ this content where the self-handle's sending state in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+ >Senders</tp:dbus-ref> is Sending_State_Pending_Send
+ will be moved to Sending_State_Sending as if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+ >SetSending</tp:dbus-ref>(TRUE) had been called.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<property name="Disposition" tp:name-for-bindings="Disposition"
- type="u" tp:type="CallContentDisposition" access="read">
-
+ type="u" tp:type="Call_Content_Disposition" access="read">
+ <tp:docstring>
+ The disposition of this content. This property cannot change.
+ </tp:docstring>
</property>
<signal name="StreamAdded" tp:name-for-bindings="Stream_Added">
@@ -101,23 +115,25 @@
</arg>
</signal>
- <property name="Streams"
- tp:name-for-bindings="Streams"
+ <property name="Streams" tp:name-for-bindings="Streams"
type="ao" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> The list of
+ <p>The list of
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Call">Stream.Draft</tp:dbus-ref>
- that exist in this content.
- </p>
-
- <tp:rational>
- In a conference call multiple parties can share one media contnet (say
- audio), but the streaming of that media can either be shared or
- seperate. For example in a multicast conference all contacts would
- share one stream, while in a Muji conference there would be a stream
- for each participant.
- </tp:rational>
+ namespace="org.freedesktop.Telepathy.Call">Stream.DRAFT</tp:dbus-ref>
+ objects that exist in this content.</p>
+
+ <tp:rationale>
+ <p>In a conference call multiple parties can share one media content
+ (say, audio), but the streaming of that media can either be shared
+ or separate. For example, in a multicast conference all contacts
+ would share one stream, while in a Muji conference there would be
+ a stream for each participant.</p>
+ </tp:rationale>
+
+ <p>Change notification is via
+ <tp:member-ref>StreamAdded</tp:member-ref> and
+ <tp:member-ref>StreamRemoved</tp:member-ref>.</p>
</tp:docstring>
</property>
</interface>
diff --git a/extensions/Call_Content_Codec_Offer.xml b/extensions/Call_Content_Codec_Offer.xml
index c421c96..31ff0b3 100644
--- a/extensions/Call_Content_Codec_Offer.xml
+++ b/extensions/Call_Content_Codec_Offer.xml
@@ -20,9 +20,9 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Content.CodecOffer.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
This object represents an offer of a Codec payload mapping.
@@ -47,6 +47,9 @@
<property name="RemoteContactCodecMap"
tp:name-for-bindings="Remote_Contact_Codec_Map"
type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ <tp:docstring>
+ A map from remote contacts to the lists of codecs they support.
+ </tp:docstring>
</property>
</interface>
diff --git a/extensions/Call_Content_Interface_Media.xml b/extensions/Call_Content_Interface_Media.xml
index d7318ca..2b3eb65 100644
--- a/extensions/Call_Content_Interface_Media.xml
+++ b/extensions/Call_Content_Interface_Media.xml
@@ -20,9 +20,9 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Call.Content"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -33,111 +33,195 @@
</tp:docstring>
<tp:struct name="Codec" array-name="Codec_List">
- <tp:member name="identifier" type="u">
+ <tp:docstring>
+ A description of a codec.
+ </tp:docstring>
+
+ <tp:member name="Identifier" type="u">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- Numeric identifier for the code. This will be used as the PT in the
+ Numeric identifier for the codec. This will be used as the PT in the
SDP or content description.
</tp:docstring>
</tp:member>
- <tp:member name="name" type="s">
+ <tp:member name="Name" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The name of the codec.
</tp:docstring>
</tp:member>
- <tp:member name="clockrate" type="u">
+ <tp:member name="Clockrate" type="u">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The clockrate of the codec
</tp:docstring>
</tp:member>
- <tp:member name="channels" type="u">
+ <tp:member name="Channels" type="u">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
Number of channels of the codec if applicable, otherwise 0
</tp:docstring>
</tp:member>
- <tp:member name="parameters" type="a{ss}">
+ <tp:member name="Parameters" type="a{ss}">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
Extra parameters for this codec
</tp:docstring>
</tp:member>
</tp:struct>
- <tp:mapping name = "Codec_Parameter_Map">
- <tp:member name="identifier" type="u">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- Numeric identifier for the code. This will be used as the PT in the
- SDP or content description.
- </tp:docstring>
- </tp:member>
+ <tp:mapping name="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contacts to the lists of codecs they support.
+ </tp:docstring>
- <tp:member name="parameters" type="a{ss}">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- Extra parameters for this codec
+ <tp:member name="Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ A contact
</tp:docstring>
</tp:member>
- </tp:mapping>
- <tp:mapping name="Contact_Codec_Map">
- <tp:member name="Handle" type="u" tp:type="Contact_Handle">
- </tp:member>
<tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs that the contact supports
+ </tp:docstring>
</tp:member>
</tp:mapping>
<tp:struct name="Codec_Offering">
- <tp:member name="CodecOffer" type="o">
+ <tp:docstring>
+ A codec offer and its corresponding remote contact codec map.
+ </tp:docstring>
+
+ <tp:member name="Codec_Offer" type="o">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The object path to the
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
- >CodecOffer.Draft</tp:dbus-ref>
+ >CodecOffer.DRAFT</tp:dbus-ref>
</tp:docstring>
</tp:member>
- <tp:member name="CodecMap" type="a{ua(usuua{ss})}"
+
+ <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}"
tp:type="Contact_Codec_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The CodecMap of this offer.
+ The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property
+ of the codec offer.
</tp:docstring>
</tp:member>
</tp:struct>
- <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"
- type="a{ua(usuua{ss}})au">
- <arg name="UpdateCodecs" type="a{ua(usuua{ss})}"
+ <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the codecs in use change.</p>
+
+ <p>As well as acting as change notification for the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this
+ signal implies that the <tp:member-ref>CodecOffer</tp:member-ref>
+ property has changed to <code>('/', {})</code>.</p>
+ </tp:docstring>
+
+ <arg name="Updated_Codecs" type="a{ua(usuua{ss})}"
tp:type="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contacts to their codecs. Each pair in this map is added
+ to the <tp:member-ref>ContactCodecMap</tp:member-ref> property,
+ replacing any previous pair with that key.
+ </tp:docstring>
</arg>
- <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+
+ <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of keys which were removed from the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because
+ those contacts left the call.
+ </tp:docstring>
</arg>
</signal>
<method name="SetCodecs" tp:name-for-bindings="Set_Codecs">
- <arg name="codecs" direction="in"
- type="a(usuua{ss})" tp:type="Codec[]">
- </arg>
<tp:docstring>
- Set or update the local codec mapping
+ Set or update the local codec mapping.
</tp:docstring>
+
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs now supported by the local user.
+ </tp:docstring>
+ </arg>
</method>
<property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map"
type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ <tp:docstring>
+ <p>A map from contact handles (including the local user's own handle)
+ to the codecs supported by that contact.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>CodecsChanged</tp:member-ref>.</p>
+ </tp:docstring>
</property>
<signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer">
- <arg name="Offer" type="o" />
- <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" />
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming
+ implementation MUST respond by calling the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT"
+ >Accept</tp:dbus-ref> or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT"
+ >Reject</tp:dbus-ref> method on the codec offer object.</p>
+
+ <p>Emission of this signal indicates that the
+ <tp:member-ref>CodecOffer</tp:member-ref> property has changed to
+ <code>(Offer, Codecs)</code>.</p>
+ </tp:docstring>
+
+ <arg name="Offer" type="o">
+ <tp:docstring>
+ The object path of the new codec offer. This replaces any previous
+ codec offer.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property
+ of the codec offer.</p>
+
+ <tp:rationale>
+ <p>Having the RemoteContactCodecMap property here saves a D-Bus
+ round-trip - it shouldn't be necessary to get the property
+ from the CodecOffer object, in practice.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
</signal>
<property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read">
- <tp:docstring>
- The object path to the current
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Call.Content"
- >CodecOffer.Draft</tp:dbus-ref> object and the
- Codec map associated with it.
- If the object path is "/" then there isn't an outstanding CodecOffer
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The object path to the current
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> object, and its
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property.
+ If the object path is "/" then there isn't an outstanding
+ codec offer, and the mapping MUST be empty.</p>
+
+ <tp:rationale>
+ <p>Having the RemoteContactCodecMap property here saves a D-Bus
+ round-trip - it shouldn't be necessary to get the property
+ from the CodecOffer object, in practice.</p>
+ </tp:rationale>
+
+ <p>Change notification is via
+ <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the
+ value of this property with a new codec offer), and
+ <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that
+ there is no longer any active codec offer).</p>
</tp:docstring>
</property>
</interface>
diff --git a/extensions/Call_Stream.xml b/extensions/Call_Stream.xml
index 829da12..302bd5e 100644
--- a/extensions/Call_Stream.xml
+++ b/extensions/Call_Stream.xml
@@ -20,9 +20,9 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Stream.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Stream.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
One stream inside a content
@@ -30,41 +30,50 @@
</tp:docstring>
<method name="SetSending" tp:name-for-bindings="Set_Sending">
- <arg name="Send" tp:name-for-bindings="Send" type="b" direction="in">
+ <p>Set the stream to start or stop sending media from the local
+ user to other contacts.</p>
+
+ <arg name="Send" type="b" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Set the stream to start or stop sending media</p>
+ <p>If true, the local user's sending state should change
+ to Sending, if it isn't already.</p>
+
+ <p>If false, the local user's sending state should change to None,
+ if it isn't already.</p>
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
<tp:docstring>
+ [FIXME: when?]
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
- <method name="RequestReceiving" tp:name-for-bindings="RequestReceiving">
+ <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
<tp:docstring>
- Request the remote contact to stop or start sending on this stream.
+ Request that a remote contact stops or starts sending on this stream.
</tp:docstring>
- <arg name="Contact" tp:name-for-bindings="Contact"
- type="u" direction="in">
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Contact from which sending is requested</p>
</tp:docstring>
</arg>
- <arg name="Receive" tp:name-for-bindings="Receive"
- type="b" direction="in">
+ <arg name="Receive" type="b" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Request to start receiving media over this stream</p>
+ <p>If true, request that the given contact starts to send media.
+ If false, request that the given contact stops sending media.</p>
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
<tp:docstring>
+ [FIXME: when?]
</tp:docstring>
</tp:error>
</tp:possible-errors>
@@ -73,12 +82,14 @@
<signal name="SendersChanged"
tp:name-for-bindings="Senders_Changed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when <tp:member-ref>Senders</tp:member-ref> changes.
</tp:docstring>
<arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
<tp:docstring>
A mapping from channel-specific handles to their updated sending
- state.
+ state, whose keys include at least the senders who were added,
+ and the senders whose states changed.
</tp:docstring>
</arg>
<arg name="Removed" type="au" tp:type="Contact_Handle[]">
@@ -90,13 +101,24 @@
</arg>
</signal>
- <tp:enum name="SendingState" tp:name-for-bindings="Sending_State" type="u">
- <tp:enumvalue suffix="PendingSend" value = "1">
+ <tp:enum name="Sending_State" type="u">
+ <tp:docstring>
+ Tristate indicating whether a contact is sending media.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
<tp:docstring>
- The contact has been asked to start sending Media.
+ The contact is not sending media and has not been asked to do so.
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Sending" value = "2">
+
+ <tp:enumvalue suffix="Pending_Send" value="1">
+ <tp:docstring>
+ The contact has been asked to start sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Sending" value="2">
<tp:docstring>
The contact is sending media.
</tp:docstring>
@@ -104,9 +126,12 @@
</tp:enum>
<tp:mapping name="Contact_Sending_State_Map">
+ <tp:docstring>
+ A map from contacts to their sending state.
+ </tp:docstring>
<tp:member name="Contact" type="u" tp:type="Contact_Handle">
</tp:member>
- <tp:member name="Sending" type="u" tp:type="SendingState">
+ <tp:member name="Sending" type="u" tp:type="Sending_State">
<tp:docstring>
</tp:docstring>
</tp:member>
@@ -115,7 +140,24 @@
<property name="Senders" tp:name-for-bindings="Senders"
type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> A map from contacts to their sending state</p>
+ <p>A map from contacts to their sending state.</p>
+
+ <p>The local user's handle in this map (the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group.SelfHandle</tp:dbus-ref> if the channel implements
+ Group, or the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.SelfHandle</tp:dbus-ref> otherwise) indicates
+ whether the local user is sending media. Media sent on this stream
+ should be assumed to be received, directly or indirectly, by every
+ other contact in the Senders mapping. Sending_State_Pending_Send
+ indicates that another contact has asked the local user to send
+ media.</p>
+
+ <p>Other contacts' handles in this map indicate whether they are
+ sending media to the contacts in this stream.
+ Sending_State_Pending_Send indicates contacts who are not sending but
+ have been asked to do so.</p>
</tp:docstring>
</property>
</interface>
diff --git a/extensions/Call_Stream_Endpoint.xml b/extensions/Call_Stream_Endpoint.xml
index 6b4293f..fbab2cf 100644
--- a/extensions/Call_Stream_Endpoint.xml
+++ b/extensions/Call_Stream_Endpoint.xml
@@ -20,9 +20,9 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
This object represents a set of candidates of one end-point.
@@ -30,13 +30,13 @@
<property name="RemoteCredentials"
tp:name-for-bindings="Remote_Credentials"
- type="(ss)" access="read">
+ type="(ss)" tp:type="Stream_Credentials" access="read">
</property>
<signal name="RemoteCredentialsSet"
tp:name-for-bindings="Remote_Credentials_Set">
- <arg name="username" type="s" />
- <arg name="password" type="s" />
+ <arg name="Username" type="s" />
+ <arg name="Password" type="s" />
</signal>
<property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
@@ -62,7 +62,7 @@
<method name="SetSelectedCandidate"
tp:name-for-bindings="Set_Selected_Candidate">
- <arg name="candidate"
+ <arg name="Candidate"
type="(usqa{sv})" tp:type="Candidate" direction="in">
<tp:docstring>
</tp:docstring>
@@ -82,7 +82,7 @@
<method name="SetStreamState"
tp:name-for-bindings="Set_Stream_State">
- <arg name="state" type="u" tp:type="Media_Stream_State"
+ <arg name="State" type="u" tp:type="Media_Stream_State"
direction="in" />
</method>
diff --git a/extensions/Call_Stream_Interface_Media.xml b/extensions/Call_Stream_Interface_Media.xml
index 0f18e4f..ccf9033 100644
--- a/extensions/Call_Stream_Interface_Media.xml
+++ b/extensions/Call_Stream_Interface_Media.xml
@@ -20,76 +20,101 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.Draft"
+ <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Call.Stream"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ [FIXME]
</tp:docstring>
<tp:method name="SetCredentials" tp:name-for-bindings="Set_Credentials">
<tp:docstring>
Used to set the username fragment and password for streams that have
- global credentials
+ global credentials.
+
+ <tp:rationale>
+ [FIXME: rationale?]
+ </tp:rationale>
</tp:docstring>
- <arg name="username" type="s" direction="in"/>
- <arg name="password" type="s" direction="in" />
+ <arg name="Username" type="s" direction="in"/>
+ <arg name="Password" type="s" direction="in" />
</tp:method>
<tp:mapping name="Candidate_Info">
- <tp:member name="key" type="s"/>
- <tp:member name="value" type="v"/>
- <tp:docstring>
- Extra information about the candidate. Allowed and Mandatory keys
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Extra information about the candidate. Allowed and mandatory keys
depend on the transport protocol used. The following keys are commenly
used:
<dl>
- <dt> Type (u)</dt>
- <dd> type of candidate (host, srflx, prflx, relay)</dd>
+ <dt>Type (u)</dt>
+ <dd>type of candidate (host, srflx, prflx, relay)</dd>
- <dt> Foundation (s)</dt>
- <dd> the foundation of this candiate</dd>
+ <dt>Foundation (s)</dt>
+ <dd>the foundation of this candiate</dd>
- <dt> Protocol (u) </dt>
- <dd> Underlying protocol of the candidate (udp, tcp) </dd>
+ <dt>Protocol (u) </dt>
+ <dd>Underlying protocol of the candidate (udp, tcp) </dd>
- <dt> Priority (u) </dt>
- <dd> Priority of the candidate </dd>
+ <dt>Priority (u) </dt>
+ <dd>Priority of the candidate </dd>
- <dt> BaseIP (u) </dt>
- <dd> Base IP of this candidate </dd>
+ <dt>BaseIP (u) </dt>
+ <dd>Base IP of this candidate </dd>
- <dt> Username (s) </dt>
- <dd> Username of this candidate
+ <dt>Username (s) </dt>
+ <dd>Username of this candidate
(only if credentials are per candidate)</dd>
- <dt> Password (s) </dt>
- <dd> Password of this candidate
+ <dt>Password (s) </dt>
+ <dd>Password of this candidate
(only if credentials are per candidate)</dd>
- <dt> RawUDPFallback (b) </dt>
- <dd> Indicate whether this candidate may be used to provide a UDP
+ <dt>RawUDPFallback (b) </dt>
+ <dd>Indicate whether this candidate may be used to provide a UDP
fallback</dd>
-
</dl>
</tp:docstring>
+ <tp:member name="Key" type="s">
+ <tp:docstring>One of the well-known keys documented here, or an
+ implementation-specific key</tp:docstring>
+ </tp:member>
+ <tp:member name="Value" type="v">
+ <tp:docstring>The value corresponding to that key</tp:docstring>
+ </tp:member>
</tp:mapping>
<tp:struct name="Candidate" array-name="Candidate_List">
<tp:docstring>A Stream Candidate</tp:docstring>
- <tp:member name="component" type="u" />
- <tp:member name="ip" type="s" />
- <tp:member name="port" type="q" />
- <tp:member name="info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:member name="Component" type="u">
+ <tp:docstring>The component number</tp:docstring>
+ </tp:member>
+ <tp:member name="IP" type="s">
+ <tp:docstring>The IP address to use</tp:docstring>
+ </tp:member>
+ <tp:member name="Port" type="q">
+ <tp:docstring>The port number to use</tp:docstring>
+ </tp:member>
+ <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:docstring>Additional information about the candidate</tp:docstring>
</tp:member>
-
</tp:struct>
<method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <tp:docstring>
+ Add candidates to <tp:member-ref>LocalCandidates</tp:member-ref>
+ and signal them to the remote contact(s).
+ </tp:docstring>
+
<arg name="candidates" direction="in"
- type="a(usqa{sv})" tp:type="Candidate[]" />
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates to be appended to
+ <tp:member-ref>LocalCandidates</tp:member-ref>
+ </tp:docstring>
+ </arg>
</method>
<method name="CandidatesPrepared"
@@ -97,39 +122,130 @@
<tp:docstring>
This indicates to the CM that the initial batch of candidates has been
added.
+
+ <tp:rationale>
+ [FIXME: rationale]
+ </tp:rationale>
</tp:docstring>
</method>
<tp:enum type="u" name="Stream_Transport_Type">
- <tp:enumvalue suffix="Raw_UDP" value="0" />
- <tp:enumvalue suffix="ICE" value="1" />
- <tp:enumvalue suffix="GTALK_P2P" value="2" />
- <tp:enumvalue suffix="MSN" value="3" />
- <tp:enumvalue suffix="WLM2009" value="4" />
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A transport that can be used for streaming.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Raw_UDP" value="0">
+ <tp:docstring>
+ Raw UDP, with or without STUN. All streaming clients are assumed to
+ support this transport, so there is no handler capability token for
+ it in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type"
+ >Call.DRAFT</tp:dbus-ref> interface.
+ [This corresponds to "none" or "stun" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="ICE" value="1">
+ <tp:docstring>
+ Interactive Connectivity Establishment, as defined by the IETF MMUSIC
+ working group.
+ [FIXME: do we want this to cover both ICE-UDP and ICE-TCP, or split
+ them?]
+ [This corresponds to "ice-udp" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="GTalk_P2P" value="2">
+ <tp:docstring>
+ Google Talk peer-to-peer connectivity establishment, as implemented
+ by libjingle 0.3.
+ [This corresponds to "gtalk-p2p" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="WLM_8_5" value="3">
+ <tp:docstring>
+ The transport used by Windows Live Messenger 8.5 or later, which
+ resembles ICE draft 6.
+ [This corresponds to "wlm-8.5" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="WLM_2009" value="4">
+ <tp:docstring>
+ The transport used by Windows Live Messenger 2009 or later, which
+ resembles ICE draft 19.
+ [This corresponds to "wlm-2009" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
</tp:enum>
<property name="Transport" tp:name-for-bindings="Transport"
type="u" tp:type="Stream_Transport_Type" access="read">
+ <tp:docstring>
+ The transport for this stream. This property is immutable.
+ </tp:docstring>
</property>
<property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via
+ <tp:member-ref>LocalCandidatesAdded</tp:member-ref>.
+ </tp:docstring>
</property>
<signal name="LocalCandidatesAdded"
- tp:name-for-bindings="Local_Candidates_Added">
+ tp:name-for-bindings="Local_Candidates_Added">
+ <tp:docstring>
+ Emitted when local candidates are added to
+ <tp:member-ref>LocalCandidates</tp:member-ref>.
+ </tp:docstring>
+
<arg name="Candidates"
- type="a(usqa{sv})" tp:type="Candidate[]"/>
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates that have been appended to
+ <tp:member-ref>LocalCandidates</tp:member-ref>
+ </tp:docstring>
+ </arg>
</signal>
+ <tp:struct name="Stream_Credentials">
+ <tp:docstring>A username/password pair.</tp:docstring>
+
+ <tp:member name="Username" type="s">
+ <tp:docstring>The username</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Password" type="s">
+ <tp:docstring>The password</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
<property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
- type="(ss)" access="read">
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via
+ <tp:member-ref>LocalCredentialsSet</tp:member-ref>.
+ </tp:docstring>
+
</property>
<signal name="LocalCredentialsSet"
- tp:name-for-bindings="LocalCredentialsSet">
- <arg name="username" type="s" />
- <arg name="password" type="s" />
+ tp:name-for-bindings="Local_Credentials_Set">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>LocalCredentials</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="Username" type="s" />
+ <arg name="Password" type="s" />
</signal>
<property name="STUNServers" tp:name-for-bindings="STUN_Servers"
@@ -177,9 +293,9 @@
<p>The precise meaning of this key depends on the
<tp:member-ref>Transport</tp:member-ref> property: if
- Transport is <code>ice-udp</code>, <code>tls</code> means
+ Transport is ICE, <code>tls</code> means
TLS over TCP as referenced by ICE draft 19, and if
- Transport is <code>gtalk-p2p</code>, <code>tls</code> means
+ Transport is GTalk_P2P, <code>tls</code> means
a fake SSL session over TCP as implemented by libjingle.</p>
</dd>
@@ -214,8 +330,8 @@
<p>The type of relay server that this represents depends on
the value of the <tp:member-ref>Transport</tp:member-ref>
- property. If Transport is ice-udp, this is a TURN server;
- if NATTraversal is gtalk-p2p, this is a Google relay server;
+ property. If Transport is ICE, this is a TURN server;
+ if Transport is GTalk_P2P, this is a Google relay server;
otherwise, the meaning of RelayInfo is undefined.</p>
<p>If relaying is not possible for this stream, the list is empty.</p>
@@ -225,9 +341,10 @@
<signal name="ServerInfoRetrieved"
tp:name-for-bindings="Server_Info_Retrieved">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> Signals that the initial information about STUN and Relay servers
- has been retrieived.
- </p>
+ <p>Signals that the initial information about STUN and Relay servers
+ has been retrieved, i.e. the
+ <tp:member-ref>RetrievedServerInfo</tp:member-ref> property is now
+ true.</p>
</tp:docstring>
</signal>
@@ -235,16 +352,35 @@
tp:name-for-bindings="Retrieved_Server_Info" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>True if the initial information about STUN servers and Relay servers
- has been retrieved. Change notification via the ServerInfoRetrieved
- signal.
- </p>
+ has been retrieved. Change notification is via the
+ <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ <p>Streaming implementations that can't cope with STUN and relay
+ servers being added later SHOULD wait for this property
+ to become true before proceeding.</p>
+ </tp:rationale>
</tp:docstring>
</property>
<signal name="EndpointsChanged"
tp:name-for-bindings="Endpoints_Changed">
- <arg name="EndpointsAdded" type="ao" />
- <arg name="EndpointsRemoved" type="ao" />
+ <tp:docstring>
+ Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property
+ changes.
+ </tp:docstring>
+
+ <arg name="EndpointsAdded" type="ao">
+ <tp:docstring>
+ Endpoints that were added.
+ </tp:docstring>
+ </arg>
+
+ <arg name="EndpointsRemoved" type="ao">
+ <tp:docstring>
+ Endpoints that no longer exist.
+ </tp:docstring>
+ </arg>
</signal>
<property name="Endpoints" tp:name-for-bindings="Endpoints"
@@ -252,9 +388,12 @@
<p> The list of endpoints
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Call.Stream"
- >Endpoint.Draft</tp:dbus-ref>
+ >Endpoint.DRAFT</tp:dbus-ref>
that exist for this stream.
</p>
+
+ <p>Change notification is via the
+ <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p>
</property>
</interface>
</node>
diff --git a/extensions/Channel_Type_Call.xml b/extensions/Channel_Type_Call.xml
index 72dd74d..702eb17 100644
--- a/extensions/Channel_Type_Call.xml
+++ b/extensions/Channel_Type_Call.xml
@@ -17,49 +17,148 @@ 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.
</tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Type.Call.Draft"
+ <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.19.0">(draft 1)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A channel type for making audio and video calls. </p>
- A Call channel can have one or more <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Call">Content.Draft</tp:dbus-ref>
- objects, which represent the actual Media that forms the Call (e.g. an
- audio content and a video content).
+ <p>A channel type for making audio and video calls.</p>
+
+ <p>A Call channel can have one or more <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call">Content.DRAFT</tp:dbus-ref>
+ objects, which represent the actual Media that forms the Call (e.g. an
+ audio content and a video content).</p>
</tp:docstring>
<method name="Ringing" tp:name-for-bindings="Ringing">
- <tp:docstring>
- Indicate the local user is alerted about the incoming call.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Indicate that the local user has been alerted about the incoming
+ call.</p>
+
+ <p>This method is only useful if the channel's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >Requested</tp:dbus-ref> property is false, and the
+ <tp:member-ref>CallState</tp:member-ref> is
+ Call_State_Pending_Initiator. While this is the case,
+ this method SHOULD change the
+ <tp:member-ref>CallFlags</tp:member-ref> to include
+ Call_Flag_Ringing, and notify the remote contact that the local
+ user has been alerted (if the protocol implements this); repeated
+ calls to this method SHOULD succeed, but have no further effect.</p>
+
+ <p>In all other states, this method SHOULD fail with the error
+ NotAvailable.</p>
</tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The call was <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >Requested</tp:dbus-ref>, so ringing does not make sense.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call is no longer in state Call_State_Pending_Initiator.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
</method>
<method name="Accept" tp:name-for-bindings="Accept">
- <tp:docstring>
- Accept the incoming call. The self-handles callstate changes to
- include accepted.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For incoming calls in state Call_State_Pending_Receiver, accept the
+ incoming call; this changes the
+ <tp:member-ref>CallState</tp:member-ref> to Call_State_Accepted.</p>
+
+ <p>For outgoing calls in state Call_State_Pending_Initiator, actually
+ call the remote contact; this changes the
+ <tp:member-ref>CallState</tp:member-ref> to
+ Call_State_Pending_Receiver.</p>
+
+ <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p>
+
+ <p>This method should be called exactly once per Call, by whatever
+ client (user interface) is handling the channel.</p>
+
+ <p>When this method is called, for each <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call"
+ >Content.DRAFT</tp:dbus-ref> whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content.DRAFT"
+ >Disposition</tp:dbus-ref> is Call_Content_Disposition_Initial,
+ any streams where the self-handle's sending state in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+ >Senders</tp:dbus-ref> is Sending_State_Pending_Send
+ will be moved to Sending_State_Sending as if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+ >SetSending</tp:dbus-ref>(TRUE) had been called.</p>
</tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call is not in one of the states where this method makes sense.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
</method>
<method name="Hangup" tp:name-for-bindings="Hangup">
<tp:docstring>
- End the call
- FIXME: add the possibility to add a reason and give
- to give more detailed errors.
+ Request that the call is ended.
</tp:docstring>
+
+ <arg direction="in" name="Reason"
+ type="u" tp:type="Call_State_Change_Reason">
+ <tp:docstring>
+ A generic hangup reason.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Detailed_Hangup_Reason"
+ type="s" tp:type="DBus_Error_Name">
+ <tp:docstring>
+ A more specific reason for the call hangup, if one is available, or
+ an empty string otherwise.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A human-readable message to be sent to the remote contact(s).
+
+ <tp:rationale>
+ XMPP Jingle allows calls to be terminated with a human-readable
+ message.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call has already been ended.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
</method>
<method name="AddContent" tp:name-for-bindings="Add_Content">
<tp:docstring>
+ [FIXME]
</tp:docstring>
- <arg direction="in" name="ContentName" type="s">
+ <arg direction="in" name="Content_Name" type="s">
<tp:docstring>
The suggested name of the content to add
+
+ <tp:rationale>
+ [FIXME: rationale]
+ </tp:rationale>
</tp:docstring>
</arg>
- <arg direction="in" name="ContentType" type="u"
+ <arg direction="in" name="Content_Type" type="u"
tp:type="Media_Stream_Type">
<tp:docstring>
The media type of the content to add
@@ -67,17 +166,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</arg>
<arg direction="out" name="Content" type="o">
<tp:docstring>
- Path to the created content
+ Path to the newly-created <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Call.Content.DRAFT</tp:dbus-ref> object.
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
+ [FIXME: when?]
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
<tp:docstring>
+ [FIXME: when?]
</tp:docstring>
</tp:error>
</tp:possible-errors>
@@ -86,14 +189,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<signal name="ContentAdded"
tp:name-for-bindings="Content_Added">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Emitted when a new content is added to the call</p>
+ <p>Emitted when a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call"
+ >Content.DRAFT</tp:dbus-ref> is added to the call.</p>
</tp:docstring>
<arg name="Content" type="o">
<tp:docstring>
- The object path of the added content
+ Path to the newly-created <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call"
+ >Content.DRAFT</tp:dbus-ref> object.
</tp:docstring>
</arg>
- <arg name="ContentType" type="u" tp:type="Media_Stream_Type">
+ <arg name="Content_Type" type="u" tp:type="Media_Stream_Type">
<tp:docstring>
The media type of the content which was added
</tp:docstring>
@@ -102,11 +209,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<signal name="ContentRemoved" tp:name-for-bindings="Content_Removed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Emitted when a contents is removed from a call</p>
+ <p>Emitted when a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call"
+ >Content.DRAFT</tp:dbus-ref> is removed from the call.</p>
</tp:docstring>
<arg name="Content" type="o">
<tp:docstring>
- The content which was removed
+ The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call"
+ >Content.DRAFT</tp:dbus-ref> which was removed.
</tp:docstring>
</arg>
</signal>
@@ -114,61 +224,91 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<property name="Contents" type="ao" access="read"
tp:name-for-bindings="Contents">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p> The list of
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Call">Content.Draft</tp:dbus-ref>
- objects that are part of this call. ChangeNotification
- happens via the <tp:member-ref>ContentAdded</tp:member-ref> and
- <tp:member-ref>ContentRemoved</tp:member-ref> signals.
+ <p>The list of
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call">Content.DRAFT</tp:dbus-ref>
+ objects that are part of this call. Change notification
+ is via the <tp:member-ref>ContentAdded</tp:member-ref> and
+ <tp:member-ref>ContentRemoved</tp:member-ref> signals.
</p>
</tp:docstring>
</property>
- <tp:mapping name="Call_State_Map">
- <tp:docstring>
- A map from contacts to call states. slates
- </tp:docstring>
+ <tp:enum type="u" name="Call_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The state of a call, as a whole.</p>
- <tp:member name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>A contact involved in this call.</tp:docstring>
- </tp:member>
- <tp:member type="a{sv}" name="State" tp:type="Contact_Call_State"/>
- </tp:mapping>
+ <p>The allowed transitions are:</p>
+
+ <ul>
+ <li>Pending_Initiator → Pending_Receiver (for outgoing calls,
+ when <tp:member-ref>Accept</tp:member-ref> is called)</li>
+ <li>Pending_Receiver → Accepted (for incoming calls, when
+ <tp:member-ref>Accept</tp:member-ref> is called; for outgoing
+ calls to a contact, when the remote contact accepts the call;
+ for joining a conference call, when the local user successfully
+ joins the conference)</li>
+ <li>Accepted → Pending_Receiver (when transferred to another
+ contact)</li>
+ <li>any state → Ended (when the call is terminated normally, or
+ when an error occurs)</li>
+ </ul>
- <tp:enum type="u" name="CallState" tp:name-for-bindings="Call_State">
- <tp:enumvalue suffix="Pending" value = "1">
+ <p>Clients MAY consider unknown values from this enum to be an
+ error - additional values will not be defined after the Call
+ specification is declared to be stable.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value = "0">
+ <tp:docstring>
+ The call state is not known. This call state MUST NOT appear as a
+ value of the <tp:member-ref>CallState</tp:member-ref> property, but
+ MAY be used by client code to represent calls whose state is as yet
+ unknown.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Pending_Initiator" value = "1">
<tp:docstring>
- This contact hasn't accepted the Call yet
+ The initiator of the call hasn't accepted the call yet. This state
+ only makes sense for outgoing calls, where it means that the local
+ user has not yet sent any signalling messages to the remote user(s),
+ and will not do so until <tp:member-ref>Accept</tp:member-ref> is
+ called.
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Accepted" value = "2">
+ <tp:enumvalue suffix="Pending_Receiver" value = "2">
<tp:docstring>
- The contact accepted this call
+ The receiver (the contact being called) hasn't accepted the call yet.
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Ended" value = "3">
+ <tp:enumvalue suffix="Accepted" value = "3">
<tp:docstring>
- The contact successfully ended its side of the call
+ The contact being called has accepted the call.
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Error" value = "4">
+ <tp:enumvalue suffix="Ended" value = "4">
<tp:docstring>
- The contact ended the call because of an error condition.
- FIXME: add well-known keys for errors
+ The call has ended, either via normal termination or an error.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
- <tp:flags name="CallFlags" tp:name-for-bindings="Call_Flags"
- value-prefix="Channel_Call_Flags" type="u">
+ <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u">
<tp:docstring>
- A set of flags representing call states.
+ A set of flags representing the status of the call as a whole,
+ providing more specific information than the
+ <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make
+ sense in a particular state.
</tp:docstring>
- <tp:flag suffix="Ringing" value="1">
+ <tp:flag suffix="Locally_Ringing" value="1">
<tp:docstring>
- The contact has been alerted about the call but has not responded
- (e.g. 180 Ringing in SIP).
+ The local contact has been alerted about the call but has not
+ responded; if possible, the remote contact(s) have been informed of
+ this fact. This flag only makes sense on incoming calls in
+ state Call_State_Pending_Receiver. It SHOULD be set when
+ <tp:member-ref>Ringing</tp:member-ref> is called successfully, and
+ unset when the state changes.
</tp:docstring>
</tp:flag>
@@ -176,14 +316,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
The contact is temporarily unavailable, and the call has been placed
in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).
+ This flag only makes sense on outgoing 1-1 calls in
+ state Call_State_Pending_Receiver. It SHOULD be set or unset
+ according to informational messages from other contacts.
</tp:docstring>
</tp:flag>
- <tp:flag suffix="Held" value="4">
+ <tp:flag suffix="Locally_Held" value="4">
<tp:docstring>
- The contact has placed the call on hold, and will not receive
- media from the local user or any other participants until they
- unhold the call again.
+ The call has been put on hold by the local user, e.g. using the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Hold</tp:dbus-ref> interface. This flag SHOULD only be set if
+ there is at least one Content, and all Contents are locally held;
+ it makes sense on calls in state Call_State_Pending_Receiver or
+ Call_State_Accepted.
+
+ <tp:rationale>
+ Otherwise, in transient situations where some but not all contents
+ are on hold, UIs would falsely indicate that the call as a whole
+ is on hold, which could lead to the user saying something they'll
+ regret, while under the impression that the other contacts can't
+ hear them!
+ </tp:rationale>
</tp:docstring>
</tp:flag>
@@ -191,7 +345,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
The initiator of the call originally called a contact other than the
current recipient of the call, but the call was then forwarded or
- diverted.
+ diverted. This flag only makes sense on outgoing calls, in state
+ Call_State_Pending_Receiver or Call_State_Accepted. It SHOULD be
+ set or unset according to informational messages from other contacts.
</tp:docstring>
</tp:flag>
@@ -202,71 +358,332 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
(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.
+ This flag only makes sense on outgoing calls in state
+ Call_State_Pending_Receiver, and SHOULD be set or unset according to
+ informational messages from servers, gateways and other
+ infrastructure.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Clearing" value="32">
+ <tp:docstring>
+ This flag only occurs when the CallState is Ended. The call with
+ this flag set has ended, but not all resources corresponding to the
+ call have been freed yet.
+
+ Depending on the protocol there might be some audible feedback while
+ the clearing flag is set.
+
+ <tp:rationale>
+ In calls following the ITU-T Q.931 standard there is a period of
+ time between the call ending and the underlying channel being
+ completely free for re-use.
+ </tp:rationale>
</tp:docstring>
</tp:flag>
</tp:flags>
- <tp:mapping name="Contact_Call_State" value-prefix="Contact_Call_State">
+ <property name="CallStateDetails"
+ tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- A mapping representing the state of a single contact in a call.
+ <p>A map used to provide optional extensible details for the
+ <tp:member-ref>CallState</tp:member-ref>,
+ <tp:member-ref>CallFlags</tp:member-ref> and/or
+ <tp:member-ref>CallStateReason</tp:member-ref>.</p>
- The following two keys are guaranteed to exist:
- <dl>
- <dt> State (u - <tp:type>CallState</tp:type>) </dt>
- <dd> The status of the contact in the call </dd>
+ <p>Well-known keys and their corresponding value types include:</p>
- <dt> Flags (u - <tp:type>CallFlags</tp:type>) </dt>
- <dd> Extra informational information about the status
- of this contact </dd>
+ <dl>
+ <dt>hangup-message - s</dt>
+ <dd>An optional human-readable message sent when the call was ended,
+ corresponding to the Message argument to the
+ <tp:member-ref>Hangup</tp:member-ref> method. This is only
+ applicable when the call state is Call_State_Ended.
+ <tp:rationale>
+ XMPP Jingle can send such messages.
+ </tp:rationale>
+ </dd>
+
+ <dt>queue-message - s</dt>
+ <dd>An optional human-readable message sent when the local contact
+ is being held in a queue. This is only applicable when
+ Call_Flag_Queued is in the call flags.
+ <tp:rationale>
+ SIP 182 notifications can have human-readable messages attached.
+ </tp:rationale>
+ </dd>
+
+ <dt>debug-message - s</dt>
+ <dd>A message giving further details of any error indicated by the
+ <tp:member-ref>CallStateReason</tp:member-ref>. This will not
+ normally be localized or suitable for display to users, and is only
+ applicable when the call state is Call_State_Ended.</dd>
</dl>
+ </tp:docstring>
+ </property>
+
+ <property name="CallState" type="u" access="read"
+ tp:name-for-bindings="Call_State" tp:type="Call_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The current high-level state of this call. The
+ <tp:member-ref>CallFlags</tp:member-ref> provide additional
+ information, and the <tp:member-ref>CallStateReason</tp:member-ref>
+ and <tp:member-ref>CallStateDetails</tp:member-ref> explain the
+ reason for the current values for those properties.</p>
+
+ <p>Clients MAY consider unknown values in this property to be an
+ error.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CallFlags" type="u" access="read"
+ tp:name-for-bindings="Call_Flags" tp:type="Call_Flags">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Flags representing the status of the call as a whole,
+ providing more specific information than the
+ <tp:member-ref>CallState</tp:member-ref>.</p>
+
+ <p>Clients are expected to ignore unknown flags in this property,
+ without error.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_State_Change_Reason" type="u">
+ <tp:docstring>
+ A simple representation of the reason for a change in the call's
+ state, which may be used by simple clients, or used as a fallback
+ when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type>
+ struct is not understood.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ We just don't know. Unknown values of this enum SHOULD also be
+ treated like this.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="User_Requested" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change was requested by the contact indicated by the Actor
+ member of a <tp:type>Call_State_Reason</tp:type> struct.</p>
+
+ <p>If the Actor is the local user, the DBus_Reason SHOULD be the
+ empty string.</p>
+ <p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty
+ string if the call was terminated normally, but MAY be a non-empty
+ error name to indicate error-like call termination reasons (call
+ rejected as busy, kicked from a conference by a moderator, etc.).</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Call_State_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A description of the reason for a change to the
+ <tp:member-ref>CallState</tp:member-ref> and/or
+ <tp:member-ref>CallFlags</tp:member-ref>.</p>
</tp:docstring>
- <tp:member type="s" name="Key">
+ <tp:member type="u" tp:type="Contact_Handle" name="Actor">
<tp:docstring>
- Well-known key
+ The contact responsible for the change, or 0 if no contact was
+ responsible.
</tp:docstring>
</tp:member>
- <tp:member type="v" name="Value">
+
+ <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason">
<tp:docstring>
- The value of the key as described above
+ The reason, chosen from a limited set of possibilities defined by
+ the Telepathy specification.
</tp:docstring>
</tp:member>
- </tp:mapping>
+ <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specific reason for the change, which may be a D-Bus error in
+ the Telepathy namespace, a D-Bus error in any other namespace
+ (for implementation-specific errors), or the empty string to
+ indicate that the state change was not an error.</p>
+
+ <p>This SHOULD be an empty string for changes to any state other
+ than Ended.</p>
+
+ <p>The errors Cancelled and Terminated SHOULD NOT be used here;
+ an empty string SHOULD be used instead.</p>
+
+ <tp:rationale>
+ <p>Those error names are used to indicate normal call
+ termination by the local user or another user, respectively,
+ in contexts where a D-Bus error name must appear.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason"
+ type="(uus)" access="read" tp:type="Call_State_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The reason for the last change to the
+ <tp:member-ref>CallState</tp:member-ref> and/or
+ <tp:member-ref>CallFlags</tp:member-ref>. The
+ <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional
+ information.</p>
+ </tp:docstring>
+ </property>
<signal name="CallStateChanged"
tp:name-for-bindings="Call_State_Changed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Emitted when the state of a contact on the call changed</p>
+ <p>Emitted when the state of the call as a whole changes.</p>
+
+ <p>This signal is emitted for any change in the properties
+ corresponding to its arguments, even if the other properties
+ referenced remain unchanged.</p>
</tp:docstring>
- <arg name="StateChanges" tp:name-for-bindings="State_Changes"
- type="a{ua{sv}}" tp:type="Call_State_Map">
+
+ <arg name="Call_State" type="u" tp:type="Call_State">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallState</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_Flags" type="u" tp:type="Call_Flags">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallFlags</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_State_Reason" type="(uus)">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_State_Details" type="a{sv}">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallStateDetails</tp:member-ref>
+ property.
+ </tp:docstring>
</arg>
</signal>
- <property name="CallState" type="a{ua{sv}}" access="read"
- tp:name-for-bindings="Call_State" tp:type="Call_State_Map">
+ <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
+ type="b" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Current state of the various contacts involved in this call</p>
- FIXME: Do we need to add error ? how to make that state recoverable?
+ <p>If this property is TRUE, all of the media streaming is done by some
+ mechanism outside the scope of Telepathy.</p>
+
+ <tp:rationale>
+ <p>A connection manager might be intended for a specialized hardware
+ device, which will take care of the audio streaming (e.g.
+ telepathy-yafono, which uses GSM hardware which does the actual
+ audio streaming for the call).</p>
+ </tp:rationale>
+
+ <p>If this is FALSE, the handler is responsible for doing the actual
+ media streaming for at least some contents itself. Those contents
+ will have the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content.Interface"
+ >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary
+ information to a streaming implementation. Connection managers SHOULD
+ operate like this, if possible.</p>
+
+ <tp:rationale>
+ <p>Many connection managers (such as telepathy-gabble) only do the
+ call signalling, and expect the client to do the actual streaming
+ using something like
+ <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve
+ latency and allow better UI integration.</p>
+ </tp:rationale>
</tp:docstring>
</property>
- <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
- type="b" access="read">
+ <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>
- If this property is TRUE then all the media streaming is done by a
- specialized component If this is FALSE then the handler should handle
- the media streaming at least some parts itself.
+ <p>A set of flags representing the status of a remote contact in a
+ call.</p>
+
+ <p>It is protocol- and client-specific whether a particular contact
+ will ever have a particular flag set on them, and Telepathy clients
+ SHOULD NOT assume that a flag will ever be set.</p>
+
+ <tp:rationale>
+ <p>180 Ringing in SIP, and its equivalent in XMPP, are optional
+ informational messages, and implementations are not required
+ to send them. The same applies to the messages used to indicate
+ hold state.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:flag suffix="Ringing" value = "1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The remote contact's client has told us that the contact has been
+ alerted about the call but has not responded.</p>
+
<tp:rationale>
- A connection-manager might be intended for a specialized hardware
- device, which will take care of the audio streaming. (e.g.
- telepathy-yafono which uses GSM hardware which does the audio actual
- streaming for the call)
+ <p>This is a flag per member, not a flag for the call as a whole,
+ because in Muji conference calls, you could invite someone and
+ have their state be "ringing" for a while.</p>
</tp:rationale>
- </p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Held" value = "2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The call member has put this call on hold.</p>
+
+ <tp:rationale>
+ <p>This is a flag per member, not a flag for the call as a whole,
+ because in conference calls, any member could put the conference
+ on hold.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List">
+ <tp:docstring>A mapping from handles to their current state in the call.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Handle" name="key"/>
+ <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/>
+ </tp:mapping>
+
+ <signal name="CallMembersChanged"
+ tp:name-for-bindings="Call_Members_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property
+ changes in any way, either because contacts have been added to the
+ call, contacts have been removed from the call, or contacts' flags
+ have changed.
+ </tp:docstring>
+
+ <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map">
+ <tp:docstring>
+ A map from members of the call to their new call member flags,
+ including at least the members who have been added to
+ <tp:member-ref>CallMembers</tp:member-ref>, and the members whose
+ flags have changed.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who have left the call, i.e. keys to be removed
+ from <tp:member-ref>CallMembers</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CallMembers" tp:name-for-bindings="Call_Members"
+ type="a{uu}" access="read" tp:type="Call_Member_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A mapping from the remote contacts that are part of this call to flags
+ discribing their status. This mapping never has the local user's handle
+ as a key.
</tp:docstring>
</property>
@@ -294,7 +711,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
audio stream to the remote contact, making it unnecessary for the
client to call
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.Call.Draft">AddContent</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.
</p>
<p>If this property, or InitialVideo, is passed to EnsureChannel
@@ -311,7 +728,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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.Call.Draft">Contents</tp:dbus-ref>).</p>
+ namespace="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT">Contents</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
@@ -326,7 +743,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
with <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type">Call.Draft</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Channel.Type">Call.DRAFT</tp:dbus-ref>
and <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= Contact in the fixed properties dictionary, and InitialAudio
@@ -344,7 +761,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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 = CAll
+ a contact's capabilities with ChannelType = Call
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
@@ -434,32 +851,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:handler-capability-token name="gtalk-p2p">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The client can implement streaming for streams whose <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
- property is <code>gtalk-p2p</code>.</p>
+ namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is Stream_Transport_Type_GTalk_P2P.</p>
</tp:docstring>
</tp:handler-capability-token>
- <tp:handler-capability-token name="ice-udp">
+ <tp:handler-capability-token name="ice">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The client can implement streaming for streams whose <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
- property is <code>ice-udp</code>.</p>
+ namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is Stream_Transport_Type_ICE.</p>
</tp:docstring>
</tp:handler-capability-token>
<tp:handler-capability-token name="wlm-8.5">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The client can implement streaming for streams whose <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
- property is <code>wlm-8.5</code>.</p>
+ namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is Stream_Transport_Type_WLM_8_5.</p>
</tp:docstring>
</tp:handler-capability-token>
<tp:handler-capability-token name="wlm-2009">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The client can implement streaming for streams whose <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
- property is <code>wlm-2009</code>.</p>
+ namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is Stream_Transport_Type_WLM_2009.</p>
</tp:docstring>
</tp:handler-capability-token>
@@ -490,9 +907,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<p>For example, a client could advertise support for
Speex, Theora and H264 by having three
handler capability tokens,
- <code>org.freedesktop.Telepathy.Channel.Type.Call.Draft/audio/speex</code>,
- <code>org.freedesktop.Telepathy.Channel.Type.Call.Draft/video/theora</code> and
- <code>org.freedesktop.Telepathy.Channel.Type.Call.Draft/video/h264</code>,
+ <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code>,
+ <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code> and
+ <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code>,
in its <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
property.</p>
diff --git a/extensions/all.xml b/extensions/all.xml
index 90a3893..76844c6 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -155,6 +155,23 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<tp:docstring>The TCP or UDP port number.</tp:docstring>
</tp:member>
</tp:struct>
+
+ <tp:enum name="Media_Stream_State" type="u">
+ <tp:enumvalue suffix="Disconnected" value="0">
+ <tp:docstring>The stream is disconnected.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connecting" value="1">
+ <tp:docstring>The stream is trying to connect.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connected" value="2">
+ <tp:docstring>The stream is connected.</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:simple-type name="Handle" type="u" array-name="Handle_List">
+ <tp:docstring>An unsigned 32-bit integer representing a
+ handle</tp:docstring>
+ </tp:simple-type>
</tp:generic-types>
</tp:spec>
diff --git a/src/call-channel.c b/src/call-channel.c
index 9879df0..1e91dcc 100644
--- a/src/call-channel.c
+++ b/src/call-channel.c
@@ -741,11 +741,11 @@ call_channel_init_async (GAsyncInitable *initable,
/* Setup the session and the initial contents */
if (priv->initial_audio)
call_channel_create_content (self, "Audio", JINGLE_MEDIA_TYPE_AUDIO,
- GABBLE_CALLCONTENTDISPOSITION_INITIAL);
+ GABBLE_CALL_CONTENT_DISPOSITION_INITIAL);
if (priv->initial_video)
call_channel_create_content (self, "Video", JINGLE_MEDIA_TYPE_VIDEO,
- GABBLE_CALLCONTENTDISPOSITION_INITIAL);
+ GABBLE_CALL_CONTENT_DISPOSITION_INITIAL);
}
call_channel_setup (self);
diff --git a/tests/twisted/constants.py b/tests/twisted/constants.py
index e6f0816..01df0d6 100644
--- a/tests/twisted/constants.py
+++ b/tests/twisted/constants.py
@@ -22,7 +22,7 @@ CHANNEL_IFACE_MESSAGES = CHANNEL + ".Interface.Messages"
CHANNEL_IFACE_PASSWORD = CHANNEL + ".Interface.Password"
CHANNEL_IFACE_TUBE = CHANNEL + ".Interface.Tube"
-CHANNEL_TYPE_CALL = CHANNEL + ".Type.Call.Draft"
+CHANNEL_TYPE_CALL = CHANNEL + ".Type.Call.DRAFT"
CHANNEL_TYPE_CONTACT_LIST = CHANNEL + ".Type.ContactList"
CHANNEL_TYPE_CONTACT_SEARCH = CHANNEL + ".Type.ContactSearch.DRAFT2"
CHANNEL_TYPE_TEXT = CHANNEL + ".Type.Text"
@@ -55,18 +55,18 @@ CALL_INITIAL_AUDIO = CHANNEL_TYPE_CALL + '.InitialAudio'
CALL_INITIAL_VIDEO = CHANNEL_TYPE_CALL + '.InitialVideo'
CALL_MUTABLE_CONTENTS = CHANNEL_TYPE_CALL + '.MutableContents'
-CALL_CONTENT = 'org.freedesktop.Telepathy.Call.Content.Draft'
+CALL_CONTENT = 'org.freedesktop.Telepathy.Call.Content.DRAFT'
CALL_CONTENT_IFACE_MEDIA = \
- 'org.freedesktop.Telepathy.Call.Content.Interface.Media.Draft'
+ 'org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT'
CALL_CONTENT_CODECOFFER = \
- 'org.freedesktop.Telepathy.Call.Content.CodecOffer.Draft'
+ 'org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT'
-CALL_STREAM = 'org.freedesktop.Telepathy.Call.Stream.Draft'
+CALL_STREAM = 'org.freedesktop.Telepathy.Call.Stream.DRAFT'
CALL_STREAM_IFACE_MEDIA = \
- 'org.freedesktop.Telepathy.Call.Stream.Interface.Media.Draft'
+ 'org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT'
-CALL_STREAM_ENDPOINT = 'org.freedesktop.Telepathy.Call.Stream.Endpoint.Draft'
+CALL_STREAM_ENDPOINT = 'org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT'
CALL_MEDIA_TYPE_AUDIO = 1
CALL_MEDIA_TYPE_VIDEO = 2
--
1.5.6.5
More information about the telepathy-commits
mailing list