summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSjoerd Simons <sjoerd.simons@collabora.co.uk>2011-01-10 18:32:56 (GMT)
committerSjoerd Simons <sjoerd.simons@collabora.co.uk>2011-01-10 18:33:16 (GMT)
commitd2f03a9a836b3ee1a8ae8fd0d76f0b50f9e89f31 (patch)
tree1898cdcf890e579cee1823130dd8156cc185978a
parent2ec2f2edc2cdefde9a40ea119702aedfac97f3d0 (diff)
downloadtelepathy-yell-update-spec.tar.gz
telepathy-yell-update-spec.tar.xz
Update telepathy-spec snapshotupdate-spec
-rw-r--r--spec/Call_Content.xml2
-rw-r--r--spec/Call_Content_Codec_Offer.xml87
-rw-r--r--spec/Call_Content_Interface_Media.xml381
-rw-r--r--spec/Call_Content_Media_Description.xml148
-rw-r--r--spec/Call_Stream_Interface_Media.xml9
-rw-r--r--spec/Channel_Type_Call.xml22
-rw-r--r--spec/Makefile.am2
7 files changed, 407 insertions, 244 deletions
diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml
index 17ed710..c947fbd 100644
--- a/spec/Call_Content.xml
+++ b/spec/Call_Content.xml
@@ -130,7 +130,7 @@
<tp:added version="0.19.11"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Extra interfaces provided by this content, such as <tp:dbus-ref
- namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or
+ namespace="ofdT.Call">Content.Interface.Media.DRAFT2</tp:dbus-ref> or
<tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>.
This SHOULD NOT include the Content interface itself, and cannot
change once the content has been created.</p>
diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml
deleted file mode 100644
index f88143f..0000000
--- a/spec/Call_Content_Codec_Offer.xml
+++ /dev/null
@@ -1,87 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Call_Content_Codec_Offer"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright © 2009-2010 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.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.
- </tp:docstring>
-
- <method name="Accept" tp:name-for-bindings="Accept">
- <arg name="Codecs" direction="in"
- type="a(usuua{ss})" tp:type="Codec[]">
- <tp:docstring>
- The local codec mapping to send to the remote contacts and
- to use in the <tp:dbus-ref
- namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
- </tp:docstring>
- </arg>
- <tp:docstring>
- Accept the updated Codec mapping and update the local mapping.
- </tp:docstring>
- <tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- <tp:docstring>
- The codecs given as the argument are invalid in some way.
- </tp:docstring>
- </tp:error>
- </tp:possible-errors>
- </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="Interfaces" tp:name-for-bindings="Interfaces"
- type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Extra interfaces provided by this codec offer. This SHOULD
- NOT include the CodecOffer interface itself, and cannot change
- once the content has been created.</p>
- </tp:docstring>
- </property>
-
- <property name="RemoteContactCodecs"
- tp:name-for-bindings="Remote_Contact_Codecs"
- type="a(usuua{ss})" tp:type="Codec[]" access="read"
- tp:immutable="yes">
- <tp:docstring>
- A list of codecs the remote contact supports.
- </tp:docstring>
- </property>
-
- <property name="RemoteContact" tp:name-for-bindings="Remote_Contact"
- type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes">
- <tp:docstring>
- The contact handle that this codec offer applies to.
- </tp:docstring>
- </property>
-
-
- </interface>
-</node>
-<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
index 274d8b2..abf9099 100644
--- a/spec/Call_Content_Interface_Media.xml
+++ b/spec/Call_Content_Interface_Media.xml
@@ -20,9 +20,10 @@
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.DRAFT2"
tp:causes-havoc="experimental">
- <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:added version="UNRELEASED">(draft 2)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -41,78 +42,95 @@
<p>When a new <tp:dbus-ref
namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel
appears, whether it was requested or not, a <tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
- will either be waiting in the
- <tp:member-ref>CodecOffer</tp:member-ref> property, or will
+ namespace="ofdT.Call.Content">MediaDescription.DRAFT</tp:dbus-ref>
+ object will either be waiting in the
+ <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property, or will
appear at some point via the
- <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p>
+ <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> signal.</p>
- <p>The <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
- property on the codec offer lists the codecs which are
+ <p> If the remote codecs and other content information are available
+ then the <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref> property will be true
+ and the <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteCodecs</tp:dbus-ref>
+ property on the description offer lists the codecs which are
supported by the remote contact, and so will determine the
codecs that should be proposed by the local user's streaming
- implementation. An empty list means all codecs can be proposed.</p>
+ implementation. </p>
- <p>For incoming calls on protocols where codecs are proposed when
+ <p>For incoming calls on protocols where the content is described when
starting the call (for example, <a
href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>),
the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteCodecs</tp:dbus-ref>
will contain information on the codecs that have already been
- proposed by the remote contact, otherwise the codec map will
- be the empty list.</p>
+ proposed by the remote contact, otherwise
+ the <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref> property will be false </p>
- <p>The streaming implementation should look at the remote codec
- map and the codecs known by the local user and call
+ <p>The streaming implementation should look at the remote description
+ and the codecs and other features known by the local user and call
<tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref>
- on the intersection of these two codec lists.</p>
-
- <p>This means that in practice, outgoing calls will have a codec
- offer pop up with no information in the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
- so the local user will call <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
- with the list of all codecs supported. If this codec offer is
- accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
- will fire with the details of the codecs passed into
- <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If
- the call is incoming, then the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ namespace="ofdT.Call.Content"
+ >MediaDescription.DRAFT.Accept</tp:dbus-ref>
+ with the locally supported description.</p>
+
+ <p>This means that in practice, outgoing calls will have a content
+ description pop up with <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref>,
+ property false so the local user will call <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >Accept</tp:dbus-ref>
+ with a description of all supported codecs and other features. If this
+ description is accepted, then
+ <tp:member-ref>LocalMediaDescriptionsChanged</tp:member-ref> will fire
+ with the details of description passed into <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >Accept</tp:dbus-ref>.
+ If the call is incoming, then the <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteCodecs</tp:dbus-ref>
will contain details of the remote contact's codecs and the
local user will call <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >Accept</tp:dbus-ref>
with the codecs that both sides understand. After the codec
- set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref>
- will fire to signal this change.</p>
+ set is accepted, both
+ <tp:member-ref>LocalMediaDescriptionsChanged</tp:member-ref> and
+ <tp:member-ref>RemoteMediaDescriptionsChanged</tp:member-ref>
+ will fire to signal their respective changes. </p>
- <h4>Protocols without codec negotiation</h4>
+ <h4>Protocols without negotiation</h4>
<p>For protocols where the codecs are not negotiable, instead of
popping up the initial content's <tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
- object with an empty <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
- the CM should set the supported codec values to known codec
- values in the said object's codec map.</p>
+ namespace="ofdT.Call.Content">MediaDescription.DRAFT</tp:dbus-ref>
+ object with <tp:dbus-ref
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref>,
+ set to false and no codecs/features being defined, the CM should set the
+ supported codec values to known codec values in said object's codec
+ map.</p>
<h4>Changing codecs mid-call</h4>
- <p>To update the codec list used mid-call, the
+ <p>To update the local codecs in all local descriptions mid-call, the
<tp:member-ref>UpdateCodecs</tp:member-ref> method should be
called with details of the new codec list. If this is
- accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
- will be emitted with the new codec set.</p>
+ accepted, then
+ <tp:member-ref>LocalMediaDescriptionsChanged</tp:member-ref>
+ will be emitted with the new codec set. </p>
<p>If the other side decides to update his or her codec list
during a call, a new <tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ namespace="ofdT.Call.Content">MediaDescription.DRAFT</tp:dbus-ref>
object will appear through
- <tp:member-ref>NewCodecOffer</tp:member-ref> which should be
+ <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> which should be
acted on as documented above.</p>
-
</tp:docstring>
<tp:struct name="Codec" array-name="Codec_List">
@@ -163,167 +181,240 @@
</tp:member>
</tp:mapping>
- <tp:struct name="Codec_Offering">
+ <tp:mapping name="Contact_Media_Description_Properties_Map">
+ <tp:member name="Remote_Contact" type="u" tp:type="Handle">
+ <tp:docstring>
+ The remote contact this description refers to or 0. This matches the
+ <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteContact</tp:dbus-ref> property on
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >MediaDescription.DRAFT</tp:dbus-ref>
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Media_Description_Properties" type="a{sv}"
+ tp:type="Media_Description_Properties">
+ <tp:docstring>
+ The properties of the description
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Media_Description_Offer">
<tp:docstring>
- A codec offer and its corresponding remote contact codec map.
+ The remote description offer and its information
</tp:docstring>
- <tp:member name="Codec_Offer" type="o">
+ <tp:member name="Media_Description" type="o">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
The object path to the <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT</tp:dbus-ref>
+ >MediaDescription.DRAFT</tp:dbus-ref>
</tp:docstring>
</tp:member>
<tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The contact handle that this codec offer applies to.
+ The contact handle that this description applies to.
</tp:docstring>
</tp:member>
- <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})"
- tp:type="Codec[]">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
- of the codec offer.
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Media_Description_Properties">
+ <tp:docstring>
+ The immutable properties of all interfaces of the codec description.
+
+ <tp:rationale>
+ Having all the codec description properties here saves a D-Bus
+ round-trip - it shouldn't be necessary to get the properties from the
+ MediaDescription object, in practice.
+ </tp:rationale>
</tp:docstring>
</tp:member>
</tp:struct>
- <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 contact to his or her 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_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="UpdateCodecs" tp:name-for-bindings="Update_Codecs">
<tp:docstring>
- Update the local codec mapping. This method should only be
- used during an existing call to update the codec mapping.
+ Update the codec mapping of the local MediaDescriptions. This
+ method should only be used during an existing call to update the local
+ media descriptions. Only parameters which strictly describe the media
+ being sent can be changed.
</tp:docstring>
<arg name="Codecs" direction="in"
type="a(usuua{ss})" tp:type="Codec[]">
<tp:docstring>
- The codecs now supported by the local user.
+ The updated codecs map as will be used by the local end.
</tp:docstring>
</arg>
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
<tp:docstring>
- Raised when a <tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
- object exists and is referred to in the
- <tp:member-ref>CodecOffer</tp:member-ref> property which
- should be used instead of calling this method, or before
- the content's initial <tp:dbus-ref
- namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
- object has appeared.
+ The protocol does not support changing the codecs mid-call.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
- <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map"
- type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ <property name="RemoteMediaDescriptions"
+ tp:name-for-bindings="Remote_Media_Descriptions"
+ type="a{ua{sv}}"
+ tp:type="Contact_Media_Description_Properties_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 the
- <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p>
+ <p>A map from contact handles to descriptions supported by that
+ contact.</p>
</tp:docstring>
</property>
- <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer">
+ <property name="LocalMediaDescriptions"
+ tp:name-for-bindings="Local_Media_Descriptions"
+ type="a{ua{sv}}"
+ tp:type="Contact_Media_Description_Properties_Map" access="read">
+ <tp:docstring>
+ <p>A map from contact handles to the descriptions the local side
+ responsed with.</p> </tp:docstring>
+ </property>
+
+ <signal name="NewMediaDescriptionOffer"
+ tp:name-for-bindings="New_Media_Description_Offer">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming
- implementation MUST respond by calling the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >MediaDescription.DRAFT</tp:dbus-ref> appears. The streaming
+ >implementation MUST respond by calling the
+ <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
>Accept</tp:dbus-ref> or <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT"
- >Reject</tp:dbus-ref> method on the codec offer object.</p>
+ namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >Reject</tp:dbus-ref> method on the description object appeared.</p>
<p>Emission of this signal indicates that the
- <tp:member-ref>CodecOffer</tp:member-ref> property has changed to
- <code>(Contact, Offer, Codecs)</code>.</p>
+ <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has
+ changed to
+ <code>(Description, Contact, MediaDescriptionProperties)</code>.</p>
+
+ <p>When the MediaDescriptionOffer has been dealt with then
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >MediaDescriptionOfferDone</tp:dbus-ref> must be emitted
+ before <tp:dbus-ref
+ namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >NewMediaDescriptionOffer</tp:dbus-ref> is emitted again.
+ </p>
+
</tp:docstring>
+ <arg name="Media_Description" type="o">
+ <tp:docstring>
+ The object path of the new media description. This replaces any
+ previous media description.
+ </tp:docstring>
+ </arg>
<arg name="Contact" type="u">
<tp:docstring>
- The contact the codec offer belongs to.
+ The remote contact the media description belongs to.
</tp:docstring>
</arg>
- <arg name="Offer" type="o">
+ <arg name="Properties" type="a{sv}"
+ tp:type="Media_Description_Properties">
<tp:docstring>
- The object path of the new codec offer. This replaces any previous
- codec offer.
+ The immutable properties of the remote media description.
+
+ <tp:rationale>
+ Having all the MediaDescription properties here saves a D-Bus
+ round-trip - it shouldn't be necessary to get the properties from the
+ MediaDescription object, in practice.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="MediaDescriptionOfferDone"
+ tp:name-for-bindings="Media_Description_Offer_Done">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call.Content"
+ >MediaDescription.DRAFT</tp:dbus-ref> has been handled. </p>
+ <p>Emission of this signal indicates that the
+ <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has
+ changed to
+ <code>("/", 0, {})</code>.</p>
+ </tp:docstring>
+ </signal>
+
+
+ <signal name="LocalMediaDescriptionsChanged"
+ tp:name-for-bindings="Local_Media_Descriptions_Changed">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Change notification for
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >LocalMediaDescriptions</tp:dbus-ref>
+ </p>
+ </tp:docstring>
+
+ <arg name="Updated_Media_Descriptions" type="a{ua{sv}}"
+ tp:type="Contact_Media_Description_Properties_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local content descriptions that were updated</p>
</tp:docstring>
</arg>
- <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ </signal>
+
+ <signal name="RemoteMediaDescriptionsChanged"
+ tp:name-for-bindings="Remote_Media_Descriptions_Changed">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Change notification for
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >RemoteMediaDescriptions</tp:dbus-ref>
+ </p>
+ </tp:docstring>
+
+ <arg name="Updated_Media_Descriptions" type="a{ua{sv}}"
+ tp:type="Contact_Media_Description_Properties_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
- of the codec offer.</p>
+ <p>The remote content descriptions that were updated</p>
+ </tp:docstring>
+ </arg>
+ </signal>
- <tp:rationale>
- Having the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
- property here saves a D-Bus round-trip - it shouldn't be
- necessary to get the property from the CodecOffer object, in
- practice.
- </tp:rationale>
+ <signal name="MediaDescriptionsRemoved"
+ tp:name-for-bindings="Media_Descriptions_Removed">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Removal notification for
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >RemoteMediaDescriptions</tp:dbus-ref>
+ and
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface.Media.DRAFT2"
+ >LocalMediaDescriptions</tp:dbus-ref>
+ </p>
+ </tp:docstring>
+
+ <arg name="Removed_Media_Descriptions" type="au"
+ tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local and remote content descriptions that are no longer part
+ of this content</p>
</tp:docstring>
</arg>
</signal>
- <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
- type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read">
+ <property name="MediaDescriptionOffer"
+ tp:name-for-bindings="Media_Description_Offer"
+ type="(oua{sv})" tp:type="Media_Description_Offer" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The object path to the current
<tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT</tp:dbus-ref> object, its
- <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and
- <tp:dbus-ref namespace="ofdT.Call.Content"
- >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties.
+ >MediaDescription.DRAFT</tp:dbus-ref> object, its
+ <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteContact</tp:dbus-ref> and
+ a mapping of the MediaDescriptions properties.
If the object path is "/" then there isn't an outstanding
- codec offer, and the mapping MUST be empty.</p>
+ content description, and the mapping MUST be empty.</p>
<tp:rationale>
- Having the <tp:dbus-ref
- namespace="ofdT.Call.Content.CodecOffer.DRAFT"
- >RemoteContact</tp:dbus-ref> and
- <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT"
- >RemoteContactCodecs</tp:dbus-ref>
+ Having all <tp:dbus-ref
+ namespace="ofdT.Call.Content">MediaDescription.DRAFT</tp:dbus-ref>
properties here saves a D-Bus round-trip - it shouldn't be
- necessary to get these properties from the CodecOffer object, in
- practice.
+ necessary to get these properties from the Content MediaDescription
+ object, in practice.
</tp:rationale>
<p>Change notification is via the
- <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) signals.</p>
+ <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> and
+ <tp:member-ref>MediaDescriptionOfferDone</tp:member-ref> signals.
+ </p>
</tp:docstring>
</property>
</interface>
diff --git a/spec/Call_Content_Media_Description.xml b/spec/Call_Content_Media_Description.xml
new file mode 100644
index 0000000..7e25fc3
--- /dev/null
+++ b/spec/Call_Content_Media_Description.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Media_Description"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 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.MediaDescription.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="UNRELEASED">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents a remote Description Offer to which the local
+ streaming implementation should reply with its local Description
+ </tp:docstring>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <arg name="Local_Media_Description" direction="in"
+ type="a{sv}" tp:type="Media_Description_Properties">
+ <tp:docstring>
+ The local description to send to the remote contacts and
+ to use in the <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Accepts the updated Description and update the corresponding
+ local description.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The decription given is invalid in some way.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Reject the proposed update to the remote description
+ FIXME add error codes and strings here
+ </tp:docstring>
+ </method>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this media description. This SHOULD
+ NOT include the Description interface itself, and cannot change
+ once the content has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="HasRemoteInformation"
+ tp:name-for-bindings="Has_Remote_Information" type="b"
+ access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml" >
+ <p> True if this offer contains information from the remote side:
+ If False then the Accept response solely depends on the
+ capabilities and preferences of the local side.
+
+ In most protocols this property will be False for the initial
+ DescriptionOffer on an outgoing call.
+ </p>
+
+ <p> This property will never be part of the DescriptionProperties used
+ to describe this object. If this property is true then the
+ DescriptionProperties describing this object will be empty (as
+ there is no remote information to put in it)
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteCodecs"
+ tp:name-for-bindings="Remote_Codecs"
+ type="a(usuua{ss})" tp:type="Codec[]" access="read"
+ tp:immutable="yes">
+ <tp:docstring>
+ A list of codecs the remote contact supports.
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteContact" tp:name-for-bindings="Remote_Contact"
+ type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes">
+ <tp:docstring>
+ The contact handle that this description applies to or 0 for a
+ description that will apply to all remote contacts in the call.
+
+ [FIXME] the usage of 0 needs further clarifications
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Media_Description_Properties">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ A mapping containing all properties that define the information from a
+ <tp:dbus-ref
+ namespace="ofdT.Call.Content"
+ >MediaDescription.DRAFT</tp:dbus-ref> and its interfaces.
+ </p>
+
+ <p>
+ If <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref> is False then this mapping
+ will be empty otherwise it willl always contains at least
+ <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >RemoteCodecs</tp:dbus-ref>
+ </p>
+
+ <p>
+ The <tp:dbus-ref namespace="ofdT.Call.Content.MediaDescription.DRAFT"
+ >HasRemoteInformation</tp:dbus-ref> property is never part of this
+ mapping.
+ </p>
+ </tp:docstring>
+
+ <tp:member name="Media_Description_Property"
+ type="s" tp:type="DBus_Qualified_Member">
+ <tp:docstring>
+ A D-Bus interface name, followed by a dot and a D-Bus property name.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Media_Description_Property_Value" type="v">
+ <tp:docstring>
+ The value of the property
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml
index 5f2bbec..9e62c87 100644
--- a/spec/Call_Stream_Interface_Media.xml
+++ b/spec/Call_Stream_Interface_Media.xml
@@ -155,7 +155,8 @@
</tp:docstring>
<tp:enumvalue suffix="Unknown" value="0">
<tp:docstring>
- The stream transport type is unknown or not applicable.
+ The stream transport type is unknown or not applicable
+ (for streams that do not have a configurable transport).
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Raw_UDP" value="1">
@@ -199,6 +200,12 @@
shmsrc and shmsink plugins.
</tp:docstring>
</tp:enumvalue>
+ <tp:enumvalue suffix="Multicast" value="6">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ Multicast transport.
+ </tp:docstring>
+ </tp:enumvalue>
</tp:enum>
<property name="Transport" tp:name-for-bindings="Transport"
diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
index eb1a663..74840f6 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -52,11 +52,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<h4>Contents</h4>
- <p><tp:dbus-ref
- namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects
- represent the actual media that forms the Call (for example an
- audio content and a video content). Calls always have one or
- more Content objects associated with them.</p>
+ <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>
+ objects represent the actual media that forms the Call (for
+ example an audio content and a video content). Calls always
+ have one or more Content objects associated with them. As a
+ result, a new Call channel request MUST have either
+ <tp:member-ref>InitialAudio</tp:member-ref>=True, or
+ <tp:member-ref>InitialVideo</tp:member-ref>=True, or both,
+ as the Requestable Channel Classes will document.</p>
<p><tp:dbus-ref
namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have
@@ -1035,7 +1038,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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="ofdT.Call.Content.Interface"
- >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary
+ >Media.DRAFT2</tp:dbus-ref> interface, to communicate the necessary
information to a streaming implementation. Connection managers SHOULD
operate like this, if possible.</p>
@@ -1160,12 +1163,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</property>
<property name="InitialTransport" tp:name-for-bindings="Initial_Transport"
- type="s" access="read" tp:requestable="yes" tp:immutable="yes">
+ type="u" tp:type="Stream_Transport_Type" access="read"
+ tp:requestable="yes" tp:immutable="yes">
<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. Where not applicable, this property
- is defined to be the empty string, in particular, on CMs with
- hardware streaming.</p>
+ is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown,
+ in particular, on CMs with hardware streaming.</p>
<tp:rationale>
When implementing a voip gateway one wants the outgoing leg of the
diff --git a/spec/Makefile.am b/spec/Makefile.am
index f0d43af..690a14f 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -1,5 +1,5 @@
EXTRA_DIST = \
- Call_Content_Codec_Offer.xml \
+ Call_Content_Media_Description.xml \
Call_Content_Interface_Media.xml \
Call_Content_Interface_Mute.xml \
Call_Content.xml \