[telepathy-gabble/master] Add an early draft of the new call spec
Sjoerd Simons
sjoerd.simons at collabora.co.uk
Tue Dec 29 05:34:30 PST 2009
---
extensions/Call_Content.xml | 125 +++++++
extensions/Call_Content_Codec_Offer.xml | 54 +++
extensions/Call_Content_Interface_Media.xml | 127 +++++++
extensions/Call_Stream.xml | 123 +++++++
extensions/Call_Stream_Endpoint.xml | 95 +++++
extensions/Call_Stream_Interface_Media.xml | 253 +++++++++++++
extensions/Channel_Type_Call.xml | 521 +++++++++++++++++++++++++++
extensions/all.xml | 55 +++
8 files changed, 1353 insertions(+), 0 deletions(-)
create mode 100644 extensions/Call_Content.xml
create mode 100644 extensions/Call_Content_Codec_Offer.xml
create mode 100644 extensions/Call_Content_Interface_Media.xml
create mode 100644 extensions/Call_Stream.xml
create mode 100644 extensions/Call_Stream_Endpoint.xml
create mode 100644 extensions/Call_Stream_Interface_Media.xml
create mode 100644 extensions/Channel_Type_Call.xml
diff --git a/extensions/Call_Content.xml b/extensions/Call_Content.xml
new file mode 100644
index 0000000..b7f52be
--- /dev/null
+++ b/extensions/Call_Content.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Content.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</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>
+ 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>
+ </tp:docstring>
+ </property>
+
+ <property name="Type" tp:name-for-bindings="Type"
+ 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>
+ </tp:docstring>
+ </property>
+
+ <property name="Creator" tp:name-for-bindings="Creator"
+ type="u" tp:Type="Contact_Handle" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p> Creator of this content </p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="CallContentDisposition" type="u">
+ <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:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The content has no specific disposition
+ </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.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Disposition" tp:name-for-bindings="Disposition"
+ type="u" tp:type="CallContentDisposition" access="read">
+
+ </property>
+
+ <signal name="StreamAdded" tp:name-for-bindings="Stream_Added">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a stream is added to a call</p>
+ </tp:docstring>
+ <arg name="Stream" type="o">
+ <tp:docstring>
+ The stream which was added
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a stream is added to a call</p>
+ </tp:docstring>
+ <arg name="Stream" type="o">
+ <tp:docstring>
+ The stream which was removed
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <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
+ <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>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Call_Content_Codec_Offer.xml b/extensions/Call_Content_Codec_Offer.xml
new file mode 100644
index 0000000..c421c96
--- /dev/null
+++ b/extensions/Call_Content_Codec_Offer.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Codec_Offer"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Content.CodecOffer.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents an offer of a Codec payload mapping.
+ FIXME add Accept and Reject signals ?
+ </tp:docstring>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]" />
+ <tp:docstring>
+ Accept the updated Codec mapping and update the local mapping
+ </tp:docstring>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Reject the proposed update to the codecs
+ FIXME add error codes and strings here
+ </tp:docstring>
+ </method>
+
+ <property name="RemoteContactCodecMap"
+ tp:name-for-bindings="Remote_Contact_Codec_Map"
+ type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Call_Content_Interface_Media.xml b/extensions/Call_Content_Interface_Media.xml
new file mode 100644
index 0000000..b52160c
--- /dev/null
+++ b/extensions/Call_Content_Interface_Media.xml
@@ -0,0 +1,127 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Content.Interface.Media.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Content"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Interface to use by a software implementation of media streaming.
+
+ FIXME: How should the streaming implementation know when it is its turn
+ to set the codecs.
+ </tp:docstring>
+
+ <tp:struct name="Codec" array-name="Codec_List">
+ <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: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:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The clockrate of the codec
+ </tp:docstring>
+ </tp:member>
+ <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: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: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: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:member>
+ </tp:mapping>
+
+ <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"
+ type="a{ua(usuua{ss}})au">
+ <arg name="UpdateCodecs" type="a{ua(usuua{ss})}"
+ tp:type="Contact_Codec_Map">
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ </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
+ </tp:docstring>
+ </method>
+
+ <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map"
+ type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ </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" />
+ </signal>
+
+ <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
+ type="o" access="read">
+ <tp:docstring>
+ If this object path is not "/" then refers to the current outstanding
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Content"
+ >CodecOffer.Draft</tp:dbus-ref> object.
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Call_Stream.xml b/extensions/Call_Stream.xml
new file mode 100644
index 0000000..829da12
--- /dev/null
+++ b/extensions/Call_Stream.xml
@@ -0,0 +1,123 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Stream.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ One stream inside a content
+ FIXME, direction should be a mapping of contact -> (bool)sending ?
+ </tp:docstring>
+
+ <method name="SetSending" tp:name-for-bindings="Set_Sending">
+ <arg name="Send" tp:name-for-bindings="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>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestReceiving" tp:name-for-bindings="RequestReceiving">
+ <tp:docstring>
+ Request the remote contact to stop or start sending on this stream.
+ </tp:docstring>
+ <arg name="Contact" tp:name-for-bindings="Contact"
+ type="u" 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">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request to start receiving media over this stream</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="SendersChanged"
+ tp:name-for-bindings="Senders_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ </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.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The channel-specific handles that were removed from
+ the keys of the Senders property, as a result of the
+ contact leaving this stream
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="SendingState" tp:name-for-bindings="Sending_State" type="u">
+ <tp:enumvalue suffix="PendingSend" 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>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:mapping name="Contact_Sending_State_Map">
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ </tp:member>
+ <tp:member name="Sending" type="u" tp:type="SendingState">
+ <tp:docstring>
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <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>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Call_Stream_Endpoint.xml b/extensions/Call_Stream_Endpoint.xml
new file mode 100644
index 0000000..a2f62e0
--- /dev/null
+++ b/extensions/Call_Stream_Endpoint.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Endpoint"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Stream.Endpoint.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents a set of candidates of one end-point.
+ </tp:docstring>
+
+ <property name="RemoteCredentials"
+ tp:name-for-bindings="Remote_Credentials"
+ type="(ss)" access="read">
+ </property>
+
+ <signal name="RemoteCredentialsSet"
+ tp:name-for-bindings="Remote_Credentials_Set">
+ <arg name="username" type="s" />
+ <arg name="password" type="s" />
+ </signal>
+
+ <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ </property>
+
+ <signal name="RemoteCandidatesAdded"
+ tp:name-for-bindings="Remote_Candidates_Added">
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]"/>
+ </signal>
+
+ <signal name="CandidateSelected"
+ tp:name-for-bindings="Candidate_Selected">
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate"/>
+ </signal>
+
+ <property name="SelectedCandidate"
+ tp:name-for-bindings="Selected_Candidate"
+ type="(usqa{sv})" tp:type="Candidate" access="read">
+ </property>
+
+ <method name="SetSelectedCandidate"
+ tp:name-for-bindings="Set_Selected_Candidate">
+ <arg name="candidate"
+ type="(usqa{sv})" tp:type="Candidate" direction="in">
+ <tp:docstring>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <property name="StreamState" tp:name-for-bindings="Stream_State"
+ type="u" tp:type="Media_Stream_Type"
+ access="read">
+ </property>
+
+ <signal name="StreamStateChanged"
+ tp:name-for-bindings="Stream_State_Changed">
+ <arg name="state"
+ type="u" tp:type="Media_Stream_Type"/>
+ </signal>
+
+ <method name="SetStreamState"
+ tp:name-for-bindings="Set_Stream_State">
+ <arg name="state" type="u" tp:type="Media_Stream_Type"
+ direction="in" />
+ </method>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read">
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Call_Stream_Interface_Media.xml b/extensions/Call_Stream_Interface_Media.xml
new file mode 100644
index 0000000..2df580a
--- /dev/null
+++ b/extensions/Call_Stream_Interface_Media.xml
@@ -0,0 +1,253 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Call.Stream.Interface.Media.Draft"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Stream"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ </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
+ </tp:docstring>
+ <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
+ 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> Foundation (s)</dt>
+ <dd> the foundation of this candiate</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> BaseIP (u) </dt>
+ <dd> Base IP of this candidate </dd>
+
+ <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
+ (only if credentials are per candidate)</dd>
+
+ <dt> RawUDPFallback (b) </dt>
+ <dd> Indicate whether this candidate may be used to provide a UDP
+ fallback</dd>
+
+ </dl>
+ </tp:docstring>
+ </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>
+
+ </tp:struct>
+
+ <method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <arg name="candidates" direction="in"
+ type="a(usqa{sv})" tp:type="Candidate[]" />
+ </method>
+
+ <method name="CandidatesPrepared"
+ tp:name-for-bindings="Candidates_Prepared">
+ <tp:docstring>
+ This indicates to the CM that the initial batch of candidates has been
+ added.
+ </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:enum>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read">
+ </property>
+
+ <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ </property>
+
+ <signal name="LocalCandidatesAdded"
+ tp:name-for-bindings="Local_Candidates_Added">
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]"/>
+ </signal>
+
+ <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
+ type="(ss)" access="read">
+ </property>
+
+ <signal name="LocalCredentialsSet"
+ tp:name-for-bindings="LocalCredentialsSet">
+ <arg name="username" type="s" />
+ <arg name="password" type="s" />
+ </signal>
+
+ <signal name="STUNServersAdded"
+ tp:name-for-bindings="STUN_Servers_Added">
+ <arg name="servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]"/>
+ </signal>
+
+ <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
+ <tp:docstring>
+ The IP addresses of possible STUN servers to use for NAT traversal, as
+ dotted-quad IPv4 address literals or RFC2373 IPv6 address literals.
+ This property cannot change once the stream has been created, so there
+ is no change notification. The IP addresses MUST NOT be given as DNS
+ hostnames.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ to make life easier for streaming implementations.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="RelayInfoAdded" tp:name-for-bindings="Relay_Info_Added">
+ <arg name="relay_info"
+ type="aa{sv}" tp:type="String_Variant_Map[]"/>
+ </signal>
+
+ <property name="RelayInfo" type="aa{sv}" access="read"
+ tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings describing TURN or Google relay servers
+ available for the client to use in its candidate gathering, as
+ determined from the protocol. Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code> - s</dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal. This MUST NOT
+ be a DNS hostname.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ and make life easier for streaming implementations.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>type</code> - s</dt>
+ <dd>
+ <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code>.</p>
+
+ <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
+ TLS over TCP as referenced by ICE draft 19, and if
+ Transport is <code>gtalk-p2p</code>, <code>tls</code> means
+ a fake SSL session over TCP as implemented by libjingle.</p>
+ </dd>
+
+ <dt><code>port</code> - q</dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code> - s</dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code> - s</dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code> - u</dt>
+ <dd>The component number to use this relay server for, as an
+ ASCII unsigned integer; if not included, this relay server
+ may be used for any or all components.
+
+ <tp:rationale>
+ In ICE draft 6, as used by Google Talk, credentials are only
+ valid once, so each component needs relaying separately.
+ </tp:rationale>
+ </dd>
+ </dl>
+
+ <tp:rationale>
+ <p>An equivalent of the gtalk-p2p-relay-token property on
+ MediaSignalling channels is not included here. The connection
+ manager should be responsible for making the necessary HTTP
+ requests to turn the token into a username and password.</p>
+ </tp:rationale>
+
+ <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;
+ otherwise, the meaning of RelayInfo is undefined.</p>
+
+ <p>If relaying is not possible for this stream, the list is empty.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="EndpointsChanged"
+ tp:name-for-bindings="Endpoints_Changed">
+ <arg name="EndpointsAdded" type="ao" />
+ <arg name="EndpointsRemoved" type="ao" />
+ </signal>
+
+ <property name="Endpoints" tp:name-for-bindings="Endpoints"
+ type="ao" access="read">
+ <p> The list of endpoints
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Call.Stream"
+ >Endpoint.Draft</tp:dbus-ref>
+ that exist for this stream.
+ </p>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Channel_Type_Call.xml b/extensions/Channel_Type_Call.xml
new file mode 100644
index 0000000..212dd06
--- /dev/null
+++ b/extensions/Channel_Type_Call.xml
@@ -0,0 +1,521 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Call" 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>
+ 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.
+
+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.
+
+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"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.UNRELEASED">(as a draft)</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).
+ </tp:docstring>
+
+ <method name="Ringing" tp:name-for-bindings="Ringing">
+ <tp:docstring>
+ Indicate the local user is alerted about the incoming call.
+ </tp:docstring>
+ </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>
+ </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.
+ </tp:docstring>
+ </method>
+
+ <method name="AddContent" tp:name-for-bindings="Add_Content">
+ <tp:docstring>
+ </tp:docstring>
+ <arg direction="in" name="ContentName" type="s">
+ <tp:docstring>
+ The suggested name of the content to add
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="ContentType" type="u"
+ tp:type="Media_Stream_Type">
+ <tp:docstring>
+ The media type of the content to add
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Content" type="o">
+ <tp:docstring>
+ Path to the created content
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <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>
+ </tp:docstring>
+ <arg name="Content" type="o">
+ <tp:docstring>
+ The object path of the added content
+ </tp:docstring>
+ </arg>
+ <arg name="ContentType" type="u" tp:type="Media_Stream_Type">
+ <tp:docstring>
+ The media type of the content which was added
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <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>
+ </tp:docstring>
+ <arg name="Content" type="o">
+ <tp:docstring>
+ The content which was removed
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <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>
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Call_State_Map">
+ <tp:docstring>
+ A map from contacts to call states. slates
+ </tp:docstring>
+
+ <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>
+
+ <tp:enum type="u" name="CallState" tp:name-for-bindings="Call_State">
+ <tp:enumvalue suffix="Pending" value = "1">
+ <tp:docstring>
+ This contact hasn't accepted the Call yet
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Accepted" value = "2">
+ <tp:docstring>
+ The contact accepted this call
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Ended" value = "3">
+ <tp:docstring>
+ The contact successfully ended its side of the call
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value = "4">
+ <tp:docstring>
+ The contact ended the call because of an error condition.
+ FIXME: add well-known keys for errors
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:flags name="CallFlags" tp:name-for-bindings="Call_Flags"
+ value-prefix="Channel_Call_Flags" type="u">
+ <tp:docstring>
+ A set of flags representing call states.
+ </tp:docstring>
+
+ <tp:flag suffix="Ringing" value="1">
+ <tp:docstring>
+ The contact has been alerted about the call but has not responded
+ (e.g. 180 Ringing in SIP).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Queued" value="2">
+ <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).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="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.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Forwarded" value="8">
+ <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.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ 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>
+
+ <tp:mapping name="Contact_Call_State" value-prefix="Contact_Call_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A mapping representing the state of a single contact in a call.
+
+ 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>
+
+ <dt> Flags (u - <tp:type>CallFlags</tp:type>) </dt>
+ <dd> Extra informational information about the status
+ of this contact </dd>
+ </dl>
+
+ </tp:docstring>
+
+ <tp:member type="s" name="Key">
+ <tp:docstring>
+ Well-known key
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="v" name="Value">
+ <tp:docstring>
+ The value of the key as described above
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+
+ <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>
+ </tp:docstring>
+ <arg name="StateChanges" tp:name-for-bindings="State_Changes"
+ type="a{ua{sv}}" tp:type="Call_State_Map">
+ </arg>
+ </signal>
+
+ <property name="CallState" type="a{ua{sv}}" access="read"
+ tp:name-for-bindings="Call_State" tp:type="Call_State_Map">
+ <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?
+ </tp:docstring>
+ </property>
+
+ <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
+ type="b" access="read">
+ <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.
+ <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)
+ </tp:rationale>
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialTransport" tp:name-for-bindings="Initial_Transport"
+ type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ If set on a requested channel this indicates the transport that
+ should be used for this call.
+ <tp:rationale>
+ When implementing a voip gateway one wants the outgoing leg of the
+ gatewayed to have the same transport as the incoming leg. This
+ property allows the gateway to request a Call with the right
+ transport from the CM.
+ </tp:rationale>
+ </p>
+ </tp:docstring>
+ </property>
+
+ <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.Call.Draft">AddContent</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.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
+ 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">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
+ (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 = 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
+ 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 = Call }</li>
+ <li>{ ChannelType = Call, InitialAudio = true }
+ if receiving calls with audio is supported</li>
+ <li>{ ChannelType = Call, 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="ImmutableContents" tp:name-for-bindings="Immutable_Contents"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tt>True</tt>, once contents 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>AddContent</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>AddContent</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
+ Call 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: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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="ice-udp">
+ <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>
+ </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>
+ </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>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="video/h264" is-family="yes">
+ <tp:docstring>
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on Call channels.</p>
+ </tp:rationale>
+
+ <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>,
+ in its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.</p>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/all.xml b/extensions/all.xml
index f9ca417..90a3893 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -48,6 +48,14 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<xi:include href="Gabble_Plugin_Test.xml"/>
+<xi:include href="Call_Content.xml" />
+<xi:include href="Call_Content_Codec_Offer.xml" />
+<xi:include href="Call_Content_Interface_Media.xml" />
+<xi:include href="Call_Stream.xml" />
+<xi:include href="Call_Stream_Endpoint.xml" />
+<xi:include href="Call_Stream_Interface_Media.xml" />
+<xi:include href="Channel_Type_Call.xml" />
+
<tp:generic-types>
<tp:external-type name="Contact_Handle" type="u"
from="Telepathy specification"/>
@@ -100,6 +108,53 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<tp:external-type name="Connection_Status" type="u"
from="Telepathy specification"/>
+ <!-- use types from Channel_Type_Streamed_Media.xml -->
+ <tp:enum name="Media_Stream_Type" type="u"
+ array-name="Media_Stream_Type_List">
+ <tp:enumvalue suffix="Audio" value="0">
+ <tp:docstring>An audio stream</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Video" value="1">
+ <tp:docstring>A video stream</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <!-- use types from generic-types.xml -->
+ <tp:struct name="Socket_Address_IP" array-name="Socket_Address_IP_List">
+ <tp:docstring>An IP address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>Either a dotted-quad IPv4 address literal as for
+ <tp:type>Socket_Address_IPv4</tp:type>, or an RFC2373 IPv6 address
+ as for <tp:type>Socket_Address_IPv6</tp:type>.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Address_IPv4">
+ <tp:docstring>An IPv4 address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal
+ numbers, each between 0 and 255 inclusive, e.g.
+ "192.168.0.1".</tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Address_IPv6">
+ <tp:docstring>An IPv6 address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>An IPv6 address literal as specified by RFC2373
+ section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
</tp:generic-types>
</tp:spec>
--
1.5.6.5
More information about the telepathy-commits
mailing list