diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-10-15 15:34:37 +0100 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-10-15 16:03:22 +0100 |
| commit | 25ecb5c19f540c2bbf397c9224c074d446cc4c91 (patch) | |
| tree | bb4e32c46e4390b6084a27b32605e46fee8dee3f /spec | |
| parent | 8e5e5b675aaf67dfdfa64c78213786f3216f9355 (diff) | |
| download | telepathy-glib-25ecb5c19f540c2bbf397c9224c074d446cc4c91.tar.gz | |
Update to spec 0.21.2
- add TP_ERROR_REJECTED
- add SendNamedTelephonyEvent and SendSoundTelephonyEvent
- do a trivial port of the Call CM to new APIs:
- rename Senders to Members, etc.
- emit added/removed streams as an array of one path
Reviewed-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
Diffstat (limited to 'spec')
25 files changed, 1142 insertions, 464 deletions
diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 8df078b66..704769adf 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -1,8 +1,8 @@ <?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: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 @@ -27,14 +27,78 @@ <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. - + content has one or more <tp:dbus-ref namespace="ofdT.Call" + >Stream.DRAFT</tp:dbus-ref> objects which represent the actual + transport to one or more contacts. </tp:docstring> + <tp:enum name="Content_Removal_Reason" type="u"> + <tp:added version="0.21.2"/> + <tp:docstring> + A simple representation of the reason for a content to be + removed, which may be used by simple clients, or used as a + fallback when the DBus_Reason 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 local user requests that this content is removed + from the call.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Error" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There is an error with the content which means that it + has to be removed from the call.</p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Unsupported" value="3"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some aspect of the content is unsupported so has to be + removed from the call.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + <method name="Remove" tp:name-for-bindings="Remove"> - <tp:docstring>Remove the content from the call.</tp:docstring> + <tp:changed version="0.21.2">previously there were no + arguments</tp:changed> + <tp:docstring> + Remove the content from the call. + </tp:docstring> + + <arg direction="in" name="Reason" type="u" + tp:type="Content_Removal_Reason"> + <tp:docstring> + A generic hangup reason. + </tp:docstring> + </arg> + + <arg direction="in" name="Detailed_Removal_Reason" type="s" + tp:type="DBus_Error_Name"> + <tp:docstring> + A more specific reason for the content removal, 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 for the reason of removing the + content, for example "Fatal streaming failure", "no codec + intersection", etc. This property can be left empty if no + reason is to be given. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"> @@ -52,9 +116,8 @@ <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 - <tp:dbus-ref - namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>. + namespace="ofdT.Call">Content.Interface.Media.DRAFT</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> </tp:docstring> @@ -62,8 +125,15 @@ <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. - [FIXME: rationale?]</p> + <p>The name of the content.</p> + + <tp:rationale> + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. + </tp:rationale> </tp:docstring> </property> @@ -101,14 +171,14 @@ <tp:enumvalue suffix="Initial" value="2"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <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> + namespace="ofdT.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="ofdT.Call.Stream.DRAFT">Members</tp:dbus-ref> + is Sending_State_Pending_Send will be moved to + Sending_State_Sending as if <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> + (TRUE) had been called.</p> </tp:docstring> </tp:enumvalue> </tp:enum> @@ -120,24 +190,28 @@ </tp:docstring> </property> - <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> + <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added"> + <tp:changed version="0.21.2">plural version, renamed from + StreamAdded</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a stream is added to a call</p> + <p>Emitted when streams are added to a call.</p> </tp:docstring> - <arg name="Stream" type="o"> + <arg name="Streams" type="ao"> <tp:docstring> - The stream which was added + The streams which were added. </tp:docstring> </arg> </signal> - <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed"> + <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed"> + <tp:changed version="0.21.2">plural version, renamed from + StreamRemoved</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a stream is added to a call</p> + <p>Emitted when streams are removed from a call</p> </tp:docstring> - <arg name="Stream" type="o"> + <arg name="Streams" type="ao"> <tp:docstring> - The stream which was removed + The streams which were removed. </tp:docstring> </arg> </signal> @@ -145,10 +219,9 @@ <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> - objects that exist in this content.</p> + <p>The list of <tp:dbus-ref namespace="ofdT.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 @@ -159,8 +232,44 @@ </tp:rationale> <p>Change notification is via - <tp:member-ref>StreamAdded</tp:member-ref> and - <tp:member-ref>StreamRemoved</tp:member-ref>.</p> + <tp:member-ref>StreamsAdded</tp:member-ref> and + <tp:member-ref>StreamsRemoved</tp:member-ref>.</p> + </tp:docstring> + </property> + + <tp:enum name="Call_Content_Packetization_Type" type="u"> + <tp:added version="0.21.2"/> + <tp:docstring> + A packetization method that can be used for a content. + </tp:docstring> + + <tp:enumvalue suffix="RTP" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Real-time Transport Protocol, as documented by RFC 3550. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Raw" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Raw media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="MSN_Webcam" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Packetization" tp:name-for-bindings="Packetization" + type="u" tp:type="Call_Content_Packetization_Type" access="read"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The packetization method in use for this content. This + property is immutable.</p> </tp:docstring> </property> </interface> diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index 31ff0b3c9..5fc45258a 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -1,8 +1,8 @@ <?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: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 diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 8b9a17c84..2b7a5ca88 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -1,8 +1,8 @@ <?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: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 @@ -23,7 +23,7 @@ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content"/> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Interface to use by a software implementation of media streaming. @@ -93,17 +93,16 @@ <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> + The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> </tp:docstring> </tp:member> <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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property of the codec offer. </tp:docstring> </tp:member> @@ -163,14 +162,13 @@ <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> <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 + <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="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> + namespace="ofdT.Call.Content.CodecOffer.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> <p>Emission of this signal indicates that the <tp:member-ref>CodecOffer</tp:member-ref> property has changed to @@ -186,8 +184,8 @@ <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 + <p>The <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property of the codec offer.</p> <tp:rationale> @@ -203,13 +201,12 @@ type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read"> <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. + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> object, and its + <tp:dbus-ref namespace="ofdT.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> + codec offer, and the mapping MUST be empty.</p> <tp:rationale> <p>Having the RemoteContactCodecMap property here saves a D-Bus diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml index eea724f59..b727231e9 100644 --- a/spec/Call_Content_Interface_Mute.xml +++ b/spec/Call_Content_Interface_Mute.xml @@ -43,7 +43,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Emitted to indicate that the mute state has changed for this call content. This may occur as a consequence of the client calling - <tp:member-ref>Muted</tp:member-ref>, or as an indication that another + <tp:member-ref>Mute</tp:member-ref>, or as an indication that another client has (un)muted the content. </tp:docstring> @@ -61,7 +61,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <method name="Muted" tp:name-for-bindings="Muted"> + <method name="Mute" tp:name-for-bindings="Mute"> + <tp:changed version="0.21.2">renamed from Muted</tp:changed> <arg direction="in" name="Muted" type="b"> <tp:docstring> True if the client has muted the content. @@ -70,7 +71,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> <p>Inform the CM that the call content has been muted or unmuted by - che client.</p> + the client.</p> <p>It is the client's responsibility to actually mute or unmute the microphone or camera used for the content. However, the client diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index 0fbb9c8aa..738564d23 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -1,8 +1,8 @@ <?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: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 @@ -56,7 +56,12 @@ <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving"> <tp:docstring> - Request that a remote contact stops or starts sending on this stream. + <p>Request that a remote contact stops or starts sending on + this stream.</p> + + <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref> + property defines whether the protocol allows the local user to + request the other side start sending on this stream.</p> </tp:docstring> <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> @@ -73,31 +78,40 @@ </arg> <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request contact is valid but is not involved in this + stream. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> - [FIXME: when?] + The protocol does not allow the local user to request the + other side starts sending on this stream. </tp:docstring> </tp:error> </tp:possible-errors> </method> - <signal name="SendersChanged" - tp:name-for-bindings="Senders_Changed"> + <signal name="MembersChanged" + tp:name-for-bindings="Members_Changed"> + <tp:changed version="0.21.2">renamed from SendersChanged</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Emitted when <tp:member-ref>Senders</tp:member-ref> changes. + Emitted when <tp:member-ref>Members</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, whose keys include at least the senders who were added, - and the senders whose states changed. + state, whose keys include at least the members who were added, + and the members whose states changed. </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 + the keys of the Members property, as a result of the contact leaving this stream </tp:docstring> </arg> @@ -125,6 +139,12 @@ The contact is sending media. </tp:docstring> </tp:enumvalue> + + <tp:enumvalue suffix="Pending_Stop_Sending" value="3"> + <tp:docstring> + The contact has been asked to stop sending media. + </tp:docstring> + </tp:enumvalue> </tp:enum> <tp:mapping name="Contact_Sending_State_Map"> @@ -150,20 +170,21 @@ </tp:docstring> </property> - <property name="Senders" tp:name-for-bindings="Senders" + <property name="Members" tp:name-for-bindings="Members" type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> + <tp:changed version="0.21.2">renamed from Senders</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <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" + namespace="ofdT.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 + other contact in the Members mapping. Sending_State_Pending_Send indicates that another contact has asked the local user to send media.</p> @@ -173,6 +194,18 @@ have been asked to do so.</p> </tp:docstring> </property> + + <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving" + type="b" access="read"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the user can request that a remote contact starts + sending on this stream.</p> + + <tp:rationale>Not all protocols allow the user to ask the + other side to start sending media.</tp:rationale> + </tp:docstring> + </property> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index fbab2cfa3..34925eefe 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -1,8 +1,8 @@ <?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: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 diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index b1b9e1932..b009c4464 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -1,8 +1,8 @@ <?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: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 @@ -23,13 +23,13 @@ <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Stream"/> + <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> [FIXME] </tp:docstring> - <tp:method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> + <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. @@ -40,7 +40,7 @@ </tp:docstring> <arg name="Username" type="s" direction="in"/> <arg name="Password" type="s" direction="in" /> - </tp:method> + </method> <tp:mapping name="Candidate_Info"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -130,6 +130,7 @@ </method> <tp:enum type="u" name="Stream_Transport_Type"> + <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> A transport that can be used for streaming. </tp:docstring> @@ -138,9 +139,8 @@ <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. + it in the <tp:dbus-ref namespace="ofdT.Channel.Type" + >Call.DRAFT</tp:dbus-ref> interface. [This corresponds to "none" or "stun" in the old Media.StreamHandler interface.] </tp:docstring> @@ -148,12 +148,10 @@ <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.] + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] </tp:docstring> </tp:enumvalue> @@ -166,21 +164,20 @@ </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="WLM_8_5" value="3"> + <tp:enumvalue suffix="WLM_2009" 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 + 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:enumvalue suffix="WLM_2009" value="4"> + <tp:enumvalue suffix="SHM" value="4"> + <tp:added version="0.21.2"/> <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.] + Shared memory transport, as implemented by the GStreamer + shmmsrc and shmsink plugins. </tp:docstring> </tp:enumvalue> </tp:enum> @@ -232,13 +229,14 @@ type="(ss)" tp:type="Stream_Credentials" access="read"> <tp:docstring> [FIXME]. Change notification is via - <tp:member-ref>LocalCredentialsSet</tp:member-ref>. + <tp:member-ref>LocalCredentialsChanged</tp:member-ref>. </tp:docstring> </property> - <signal name="LocalCredentialsSet" - tp:name-for-bindings="Local_Credentials_Set"> + <signal name="LocalCredentialsChanged" + tp:name-for-bindings="Local_Credentials_Changed"> + <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed> <tp:docstring> Emitted when the value of <tp:member-ref>LocalCredentials</tp:member-ref> changes. @@ -386,12 +384,8 @@ <property name="Endpoints" tp:name-for-bindings="Endpoints" type="ao" access="read"> <tp:docstring> - <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> + <p>The list of endpoints <tp:dbus-ref namespace="ofdT.Call.Stream" + >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> diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml index d61123f9c..be06f5caa 100644 --- a/spec/Channel_Dispatcher_Interface_Operation_List.xml +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -66,7 +66,7 @@ <tp:rationale> <p>The rationale is the same as for - <tp:type-ref>Channel_Details</tp:type-ref>.</p> + <tp:type>Channel_Details</tp:type>.</p> </tp:rationale> <p>Each dictionary MUST contain at least the following keys:</p> @@ -108,7 +108,7 @@ type="a{sv}" tp:type="Qualified_Property_Value_Map"> <tp:docstring> The same properties that would appear in the Properties member of - <tp:type-ref>Dispatch_Operation_Details</tp:type-ref>. + <tp:type>Dispatch_Operation_Details</tp:type>. </tp:docstring> </arg> </signal> diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml index afb99c5ca..abda59eef 100644 --- a/spec/Channel_Interface_Conference.xml +++ b/spec/Channel_Interface_Conference.xml @@ -355,7 +355,7 @@ </signal> <property name="InitialChannels" tp:name-for-bindings="Initial_Channels" - access="read" type="ao"> + access="read" type="ao" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p> @@ -413,14 +413,13 @@ we arbitrarily mandate that it SHOULD choose the first channel in the list as the one to continue.</p> </tp:rationale> - - <p>This property is immutable.</p> </tp:docstring> </property> <property name="InitialInviteeHandles" tp:name-for-bindings="Initial_Invitee_Handles" - access="read" type="au" tp:type="Contact_Handle[]"> + access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes" + tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of additional contacts invited to this conference when it was created.</p> @@ -460,8 +459,6 @@ property, together with any other contacts invited at the same time (if that information is known).</p> - <p>This property is immutable.</p> - <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be combined in a single request.</p> @@ -496,7 +493,7 @@ <property name="InitialInviteeIDs" tp:name-for-bindings="Initial_Invitee_IDs" - access="read" type="as"> + access="read" type="as" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of additional contacts invited to this conference when it was created.</p> @@ -512,13 +509,11 @@ means that the value of InitialInviteeIDs will include the TargetID of each channel in InitialChannels, and the ID corresponding to each handle in InitialInviteeHandles.</p> - - <p>This property is immutable.</p> </tp:docstring> </property> <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message" - access="read" type="s"> + access="read" type="s" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The message that was sent to the <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were @@ -539,8 +534,6 @@ <p>If the local user was not the initiator of this channel, the message with which they were invited (if any) SHOULD appear in the value of this property.</p> - - <p>This property is immutable.</p> </tp:docstring> </property> diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml index 03e89683c..cd606c1b7 100644 --- a/spec/Channel_Interface_Mergeable_Conference.xml +++ b/spec/Channel_Interface_Mergeable_Conference.xml @@ -82,19 +82,19 @@ </arg> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Errors.InvalidArgument"> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> The given channel isn't suitable for merging into this one: for instance, it might have the wrong channel type or handle type. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Errors.NotImplemented"> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> It will never be possible to merge channels into this particular conference. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable"> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The given channel is theoretically suitable for merging into this one, but that's not currently possible for some reason (for diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index d4fde0d2b..0eeee39e2 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -95,7 +95,8 @@ USA.</p> </tp:docstring> <property name="SupportedContentTypes" type="as" access="read" - tp:name-for-bindings="Supported_Content_Types"> + tp:name-for-bindings="Supported_Content_Types" + tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of MIME types supported by this channel, with more preferred MIME types appearing earlier in the list. The list MAY include "*/*" @@ -143,7 +144,8 @@ USA.</p> <property name="MessagePartSupportFlags" type="u" tp:type="Message_Part_Support_Flags" access="read" - tp:name-for-bindings="Message_Part_Support_Flags"> + tp:name-for-bindings="Message_Part_Support_Flags" + tp:immutable="yes"> <tp:docstring> Flags indicating the level of support for message parts on this channel. @@ -1087,15 +1089,19 @@ USA.</p> <property name="PendingMessages" type="aaa{sv}" access="read" tp:type="Message_Part[][]" tp:name-for-bindings="Pending_Messages"> - <tp:docstring> - A list of incoming messages that have neither been acknowledged nor - rejected. This list is a more detailed version of the one returned - by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>, - and contains the same messages, uniquely identified by the same - pending message IDs. Its items can be removed using - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of incoming messages that have neither been acknowledged nor + rejected. This list is a more detailed version of the one returned + by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>, + and contains the same messages, uniquely identified by the same + pending message IDs. Its items can be removed using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.</p> + + <p>Change notification is via + <tp:member-ref>MessageReceived</tp:member-ref> and + <tp:member-ref>PendingMessagesRemoved</tp:member-ref>.</p> </tp:docstring> </property> @@ -1340,7 +1346,8 @@ USA.</p> <property name="DeliveryReportingSupport" access="read" tp:type="Delivery_Reporting_Support_Flags" type="u" - tp:name-for-bindings="Delivery_Reporting_Support"> + tp:name-for-bindings="Delivery_Reporting_Support" + tp:immutable="yes"> <tp:docstring> A bitfield indicating features supported by this channel. </tp:docstring> diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml index 7509c9c89..760c13406 100644 --- a/spec/Channel_Interface_Splittable.xml +++ b/spec/Channel_Interface_Splittable.xml @@ -53,12 +53,12 @@ </tp:docstring> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Errors.InvalidArgument"> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> This channel isn't in a conference. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable"> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> This channel is in a conference but can't currently be split away from it. diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index 68dc7ffc7..50bf83f22 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -1,7 +1,7 @@ <?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:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009-2010 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 @@ -23,29 +23,395 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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> + <p>A channel type for making audio and video calls. Call + channels supersede the old <tp:dbus-ref + namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref> + channel type. Call channels are much more flexible than its + predecessor and allow more than two participants.</p> + + <p>Handlers are advised against executing all the media + signalling, codec and candidate negotiation themselves but + instead use a helper library such as <a + href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a> + which when given a new Call channel will set up the + transports and codecs and create GStreamer pads which + can be added to the handler UI. This is useful as it means + the handler does not have to worry how exactly the + connection between the call participants is being made.</p> + + <p>The <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> + properties in a Call channel refer to the contact that the + user initially called, or which contact initially called the + user. Even in a conference call, where there are multiple + contacts in the call, these properties refer to the + initial contact, who might have left the conference since + then. As a result, handlers should not rely on these + properties.</p> + + <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 have + one or more stream associated with them. More information on + these streams and how to maniuplate them can be found on the + <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> + interface page.</p> + + <h4>Outgoing calls</h4> + + <p>To make an audio-only call to a contact <tt>foo@example.com</tt> + handlers should call:</p> + + <blockquote> + <pre> +<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + ...<tp:member-ref>InitialAudio</tp:member-ref>: True, +})</pre></blockquote> + + <p>As always, <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used + in place of + <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> + if the contact's handle is already known. To make an audio + and video call, the handler should also specify + <tp:member-ref>InitialVideo</tp:member-ref> The + connection manager SHOULD return a channel whose immutable + properties contain the local user as the <tp:dbus-ref + namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the + remote contact as the <tp:dbus-ref + namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> = + <code>True</code> (indicating the call is outgoing).</p> + + <p>After a new Call channel is requested, the + <tp:member-ref>CallState</tp:member-ref> property will be + <tp:type>Call_State</tp:type>_Pending_Initiator. As the local + user is the initiator, the call must be accepted by the handler + by calling the <tp:member-ref>Accept</tp:member-ref> method. + At this point, <tp:member-ref>CallState</tp:member-ref> changes + to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies + that the call is ringing, waiting for the remote contact to + accept the call. All changes to + <tp:member-ref>CallState</tp:member-ref> property are signalled + using the <tp:member-ref>CallStateChanged</tp:member-ref> + signal.</p> + + <p>When the call is accepted by the remote contact, the + <tp:member-ref>CallStateChanged</tp:member-ref> signal fires + again to show that <tp:member-ref>CallState</tp:member-ref> = + <tp:type>Call_State</tp:type>_Accepted.</p> + + <p>At this point <a + href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a> + will signal that a pad is available for the handler to show + in the user interface.</p> + + <h5>Missed calls</h5> + + <p>If the remote contact does not accept the call in time, then + the call can be terminated by the server. Note that this only + happens in some protocols. Most XMPP clients, for example, do + not do this and rely on the call initiator terminating the call. + A missed call is shown in a Call channel by the + <tp:member-ref>CallState</tp:member-ref> property changing to + <tp:type>Call_State</tp:type>_Ended, and the + <tp:member-ref>CallStateReason</tp:member-ref> property changing + to (remote contact, + <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p> + + <h5>Rejected calls</h5> + + <p>If the remote contact decides he or she does not feel like + talking to the local user, he or she can reject his or her + incoming call. This will be shown in the Call channel by + <tp:member-ref>CallState</tp:member-ref> changing to + <tp:type>Call_State</tp:type>_Ended and the + <tp:member-ref>CallStateReason</tp:member-ref> property + changing to (remote contact, + <tp:type>Call_State</tp:type>_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").</p> + + <h4>Incoming calls</h4> + + <p>When an incoming call occurs, something like the following + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal will occur:</p> + + <blockquote> + <pre> +<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([ + /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel, + { + ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42, + ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False, + ...<tp:member-ref>InitialAudio</tp:member-ref>: True, + ...<tp:member-ref>InitialVideo</tp:member-ref>: True, + ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio", + ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video", + ...<tp:member-ref>MutableContents</tp:member-ref>: True, + }])</pre></blockquote> + + <p>The <tp:member-ref>InitialAudio</tp:member-ref> and + <tp:member-ref>InitialVideo</tp:member-ref> properties show that + the call has been started with two contents: one for audio + streaming and one for video streaming. The + <tp:member-ref>InitialAudioName</tp:member-ref> and + <tp:member-ref>InitialVideoName</tp:member-ref> properties also + show that the aforementioned audio and video contents have names + "audio" and "video".</p> + + <p>Once the handler has notified the local user that there is an + incoming call waiting for acceptance, the handler should call + <tp:member-ref>SetRinging</tp:member-ref> to let the CM know. + The new channel should also be given to telepathy-farsight to + work out how the two participants will connect together. + telepathy-farsight will call the appropriate methods on the call's + <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s + to negotiate codecs and transports.</p> + + <p>To pick up the call, the handler should call + <tp:member-ref>Accept</tp:member-ref>. The + <tp:member-ref>CallState</tp:member-ref> property changes to + <tp:type>Call_State</tp:type>_Accepted and once media is + being transferred, telepathy-farsight will notify the + handler of a new pad to be shown to the local user in the + UI</p> + + <p>To reject the call, the handler should call the + <tp:member-ref>Hangup</tp:member-ref> method. The + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and the + <tp:member-ref>CallStateReason</tp:member-ref> property will + change to (self handle, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").</p> + + <h4>Ongoing calls</h4> + + <h5>Adding and removing contents</h5> + + <p>When a call is open, new contents can be added as long as the + CM supports it. The + <tp:member-ref>MutableContents</tp:member-ref> property will let + the handler know whether further contents can be added or + existing contents removed. An example of this is starting a + voice call between a contact and then adding a video content. + To do this, the should call + <tp:member-ref>AddContent</tp:member-ref> like this:</p> + + <blockquote> + <pre><tp:member-ref>AddContent</tp:member-ref>("video", + <tp:type>Media_Stream_Type</tp:type>_Video)</pre> + </blockquote> + + <p>Assuming no errors, the new video content will be added to + the call. telepathy-farsight will pick up the new content and + perform the transport and codec negotiation automatically. + telpathy-farsight will signal when the video is ready to + show in the handler's user interface.</p> + + <p>A similar method is used for removing contents from a call, + except that the <tp:dbus-ref + namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method + is on the <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p> + + <h5>Ending the call</h5> + + <p>To end the call, the handler should call the + <tp:member-ref>Hangup</tp:member-ref> method. The + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and + <tp:member-ref>CallStateReason</tp:member-ref> will change + to (self handle, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Cancelled").</p> + + <p>If the other participant hangs up first then the + <tp:member-ref>CallState</tp:member-ref> property will change to + <tp:type>Call_State</tp:type>_Ended and + <tp:member-ref>CallStateReason</tp:member-ref> will change + to (remote contact, + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated").</p> + + <h4>Multi-party calls</h4> + + [TODO] + + <h4>Call states</h4> + + <p>There are many combinations of the + <tp:member-ref>CallState</tp:member-ref> and + <tp:member-ref>CallStateReason</tp:member-ref> properties which + mean different things. Here is a table to try to make these + meanings clearer:</p> + + <table> + <tr> + <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th> + <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th> + <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th> + <th rowspan="2">Meaning</th> + </tr> + <tr> + <th>Actor</th> + <th>Reason</th> + <th>DBus_Reason</th> + </tr> + <!-- Pending_Initiator --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Pending_Initiator</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td> + </tr> + <!-- Pending_Receiver --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The outgoing call is waiting for the remote contact to pick up the call.</td> + </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> + <td>0</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td> + <td>""</td> + <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td> + </tr> + <!-- Accepted --> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Accepted</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The remote contact accepted the outgoing call.</td> + </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Accepted</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td>""</td> + <td>The local user accepted the incoming call.</td> + </tr> + <!-- Ended --> + <tr> + <td>True or False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Self handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>Cancelled</tp:error-ref></td> + <td>The local user hung up the incoming or outgoing call.</td> + </tr> + <tr> + <td>True or False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>Terminated</tp:error-ref></td> + <td>The remote contact hung up the incoming or outgoing call.</td> + </tr> + <tr> + <td>True</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td> + <td>""</td> + <td>The outgoing call was not picked up and the call ended.</td> + </tr> + </table> + + <h4>Requestable channel classes</h4> + + <p>The <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + for <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + can be:</p> + + <blockquote> + <pre> +[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:member-ref>InitialVideo</tp:member-ref>: True + }, + Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>, + ...<tp:member-ref>InitialAudio</tp:member-ref>, + ...<tp:member-ref>InitialAudioName</tp:member-ref> + ] +), +( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, + ...<tp:member-ref>InitialAudio</tp:member-ref>: True + }, + Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>, + ...<tp:member-ref>InitialVideo</tp:member-ref>, + ...<tp:member-ref>InitialVideoName</tp:member-ref> + ] +)]</pre></blockquote> + + <p>Clients aren't allowed to make outgoing calls that have + neither initial audio nor initial video. Clearly, CMs + which don't support video should leave out the first class and + omit <tp:member-ref>InitialVideo</tp:member-ref> from the second + class, and vice versa for CMs without audio support.</p> + + <p>Handlers should not close <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + without first calling <tp:member-ref>Hangup</tp:member-ref> on + the channel. If a Call handler crashes, the <tp:dbus-ref + namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the + channel which SHOULD also imply a call to + <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated", "") before + actually closing the channel.</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"> + <method name="SetRinging" tp:name-for-bindings="Set_Ringing"> + <tp:changed version="0.21.2">renamed from Ringing</tp:changed> <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_Receiver. While this is the case, - this method SHOULD change the + <p>This method is only useful if the + channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> + property is False, and + the <tp:member-ref>CallState</tp:member-ref> is + <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming + call waiting on the local user to pick up). 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> + <tp:type>Call_Flags</tp:type>_Locally_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> @@ -54,14 +420,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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. + The call was <tp:dbus-ref namespace="ofdT.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_Receiver. + The call is no longer in state + <tp:type>Call_State</tp:type>_Pending_Receiver. </tp:docstring> </tp:error> </tp:possible-errors> @@ -69,14 +435,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="Accept" tp:name-for-bindings="Accept"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For incoming calls in state Call_State_Pending_Receiver, accept the + <p>For incoming calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver, accept the incoming call; this changes the - <tp:member-ref>CallState</tp:member-ref> to Call_State_Accepted.</p> + <tp:member-ref>CallState</tp:member-ref> to + <tp:type>Call_State</tp:type>_Accepted.</p> - <p>For outgoing calls in state Call_State_Pending_Initiator, actually + <p>For outgoing calls in state + <tp:type>Call_State</tp:type>_Pending_Initiator, actually call the remote contact; this changes the <tp:member-ref>CallState</tp:member-ref> to - Call_State_Pending_Receiver.</p> + <tp:type>Call_State</tp:type>_Pending_Receiver.</p> <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> @@ -84,16 +453,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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> + namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose + <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" + >Disposition</tp:dbus-ref> is + <tp:type>Call_Content_Disposition</tp:type>_Initial, any + streams where the self-handle's sending state in <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT" >Members</tp:dbus-ref> is + <tp:type>Sending_State</tp:type>_Pending_Send will be + moved to <tp:type>Sending_State</tp:type>_Sending as if + <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" + >SetSending</tp:dbus-ref>(True) had been called.</p> </tp:docstring> <tp:possible-errors> @@ -107,11 +476,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="Hangup" tp:name-for-bindings="Hangup"> <tp:docstring> - Request that the call is ended. + Request that the call is ended. All contents will be removed + from the Call so that the + <tp:member-ref>Contents</tp:member-ref> property will be the + empty list. </tp:docstring> <arg direction="in" name="Reason" - type="u" tp:type="Call_State_Change_Reason"> + type="u" tp:type="Call_State_Change_Reason"> <tp:docstring> A generic hangup reason. </tp:docstring> @@ -147,21 +519,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="AddContent" tp:name-for-bindings="Add_Content"> <tp:docstring> - [FIXME] + Request that a new <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type + Content_Type is added to the Call. Handlers should check the + value of the <tp:member-ref>MutableContents</tp:member-ref> + property before trying to add another content as it might not + be allowed. </tp:docstring> <arg direction="in" name="Content_Name" type="s"> <tp:docstring> - The suggested name of the content to add + <p>The suggested name of the content to add.</p> <tp:rationale> - [FIXME: rationale] + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. </tp:rationale> + + <p>If there is already a content with the same name as this + property then a sensible suffix should be added. For example, + if this argument is "audio" but a content of the same name + already exists, a sensible suffix such as " (1)" is appended + to name the new content "audio (1)". A further content with the + name "audio" would then be named "audio (2)".</p> + </tp:docstring> </arg> <arg direction="in" name="Content_Type" type="u" tp:type="Media_Stream_Type"> <tp:docstring> - The media type of the content to add + The media stream type of the content to be added to the + call. </tp:docstring> </arg> <arg direction="out" name="Content" type="o"> @@ -175,12 +565,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> - [FIXME: when?] + The media stream type given is invalid. </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> - [FIXME: when?] + The media stream type requested is not implemented by the + CM. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The content type requested cannot be added to this + call. Examples of why this might be the case include + because a second video stream cannot be added, or a + content cannot be added when the content set isn't + mutable. </tp:docstring> </tp:error> </tp:possible-errors> @@ -189,46 +589,37 @@ 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 <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call" - >Content.DRAFT</tp:dbus-ref> is added to the call.</p> + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> is added to the call.</p> </tp:docstring> <arg name="Content" type="o"> <tp:docstring> - Path to the newly-created <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call" - >Content.DRAFT</tp:dbus-ref> object. + Path to the newly-created <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> object. </tp:docstring> </arg> - <arg name="Content_Type" 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 <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Call" - >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> + <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> </tp:docstring> <arg name="Content" type="o"> <tp:docstring> - The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call" - >Content.DRAFT</tp:dbus-ref> which was removed. + The <tp:dbus-ref namespace="ofdT.Call" + >Content.DRAFT</tp:dbus-ref> which was removed. </tp:docstring> </arg> </signal> <property name="Contents" type="ao" access="read" - tp:name-for-bindings="Contents"> + 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. Change notification - is via the <tp:member-ref>ContentAdded</tp:member-ref> and + <p>The list of <tp:dbus-ref + namespace="ofdT.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> @@ -306,9 +697,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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. + state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD + be set when <tp:member-ref>SetRinging</tp:member-ref> is + called successfully, and unset when the state changes. </tp:docstring> </tp:flag> @@ -317,19 +708,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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. + state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be + set or unset according to informational messages from other + contacts. </tp:docstring> </tp:flag> <tp:flag suffix="Locally_Held" value="4"> <tp:docstring> - 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. + The call has been put on hold by the local user, e.g. using + the <tp:dbus-ref namespace="ofdT.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 + <tp:type>Call_State</tp:type>_Pending_Receiver + or <tp:type>Call_State</tp:type>_Accepted. <tp:rationale> Otherwise, in transient situations where some but not all contents @@ -346,8 +739,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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. 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:type>Call_State</tp:type>_Pending_Receiver or + <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset + according to informational messages from other contacts. </tp:docstring> </tp:flag> @@ -359,9 +753,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set + or unset according to informational messages from servers, gateways + and other infrastructure. </tp:docstring> </tp:flag> @@ -385,11 +779,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:flag suffix="Muted" value="64"> <tp:docstring> The call has been muted by the local user, e.g. using the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content.Interface" - >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only be set if - there is at least one Content, and all Contents are locally muted; - it makes sense on calls in state Call_State_Pending_Receiver or - Call_State_Accepted. + <tp:dbus-ref namespace="ofdT.Call.Content.Interface" + >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only + be set if there is at least one Content, and all Contents + are locally muted; it makes sense on calls in state + <tp:type>Call_State</tp:type>_Pending_Receiver or + <tp:type>Call_State</tp:type>_Accepted. </tp:docstring> </tp:flag> </tp:flags> @@ -409,7 +804,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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. + applicable when the call state is <tp:type>Call_State</tp:type>_Ended. <tp:rationale> XMPP Jingle can send such messages. </tp:rationale> @@ -418,7 +813,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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:type>Call_Flags</tp:type>_Queued is in the call flags. <tp:rationale> SIP 182 notifications can have human-readable messages attached. </tp:rationale> @@ -428,7 +823,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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> + applicable when the call state is + <tp:type>Call_State</tp:type>_Ended.</dd> </dl> </tp:docstring> </property> @@ -442,6 +838,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. and <tp:member-ref>CallStateDetails</tp:member-ref> explain the reason for the current values for those properties.</p> + <p>Note that when in a conference call, this property is + purely to show your state in joining the call. The receiver + (or remote contact) in this context is the conference server + itself. The property does not change when other call members' + states change.</p> + <p>Clients MAY consider unknown values in this property to be an error.</p> </tp:docstring> @@ -456,6 +858,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>Clients are expected to ignore unknown flags in this property, without error.</p> + + <p>When an ongoing call is active and not on hold or has any + other problems, this property will be 0.</p> </tp:docstring> </property> @@ -496,6 +901,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. of a <tp:type>Call_State_Reason</tp:type> struct.</p> </tp:docstring> </tp:enumvalue> + + <tp:enumvalue suffix="No_Answer" value="3"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed from + <tp:type>Call_State</tp:type>_Pending_Receiver to + <tp:type>Call_State</tp:type>_Ended because the initiator + ended the call before the receiver accepted it. With an + incoming call this state change reason signifies a missed + call.</p> + </tp:docstring> + </tp:enumvalue> </tp:enum> <tp:struct name="Call_State_Reason"> @@ -592,9 +1009,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </signal> <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming" - type="b" access="read"> + type="b" access="read" tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If this property is TRUE, all of the media streaming is done by some + <p>If this property is True, all of the media streaming is done by some mechanism outside the scope of Telepathy.</p> <tp:rationale> @@ -604,11 +1021,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. audio streaming for the call).</p> </tp:rationale> - <p>If this is FALSE, the handler is responsible for doing the actual + <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 + will have the <tp:dbus-ref namespace="ofdT.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> @@ -713,38 +1129,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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. + <p>A mapping from the remote contacts that are part of this call to flags + describing their status. This mapping never has the local user's handle + as a key.</p> + + <p>When the call ends, this property should be an empty list, + and notified with + <tp:member-ref>CallMembersChanged</tp:member-ref></p> + + <p>If the Call implements + <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Group</tp:dbus-ref> and the Group members are + channel-specific handles, then this call SHOULD also use + channel-specific handles.</p> + + <p>Anonymous members are exposed as channel-specific handles + with no owner.</p> </tp:docstring> </property> <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" - type="s" access="read"> + type="s" 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. - <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> + <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> + + <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> </tp:docstring> </property> <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" - type="b" access="read"> + type="b" access="read" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If set to true in a channel request that will create a new channel, + <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> + client to call <tp:dbus-ref + namespace="ofdT.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 @@ -752,25 +1180,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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 + <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 + <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> + <tp:dbus-ref namespace="ofdT.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>The name of this new content can be decided by using the + <tp:member-ref>InitialAudioName</tp:member-ref> property.</p> <p>Connection managers that support the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> + namespace="ofdT.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 @@ -788,19 +1212,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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> + namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> (clients of a <tp:dbus-ref - namespace="org.freedesktop.Telepathy">ChannelDispatcher</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> + namespace="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref> properties):</p> <ul> <li>{ ChannelType = Call }</li> - <li>{ ChannelType = Call, InitialAudio = true } + <li>{ ChannelType = Call, InitialAudio = True } if receiving calls with audio is supported</li> - <li>{ ChannelType = Call, InitialVideo = true } + <li>{ ChannelType = Call, InitialVideo = True } if receiving calls with video is supported</li> </ul> @@ -813,12 +1237,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </property> <property name="InitialVideo" tp:name-for-bindings="Initial_Video" - type="b" access="read"> + type="b" access="read" tp:immutable="yes" tp:requestable="yes"> <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 + <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> @@ -828,13 +1252,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name" + type="s" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to + True, then this property will name the intial audio content + with the value of this property.</p> + + <tp:rationale> + <p>Content names are meant to be significant, but if no name + can be given to initial audio content, then its name cannot + be meaningful or even localized.</p> + </tp:rationale> + + <p>If this property is empty or missing from the channel + request and InitialAudio is True, then the CM must come up + with a sensible for the content, such as "audio".</p> + + <p>If the protocol has no concept of stream names then this + property will not show up in the allowed properties list of + the Requestable Channel Classes for call channels.</p> + </tp:docstring> + </property> + + <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name" + type="s" access="read" tp:immutable="yes" tp:requestable="yes"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as + <tp:member-ref>InitialAudioName</tp:member-ref>, but for a + video stream created by setting + <tp:member-ref>InitialVideo</tp:member-ref> to True. This + property is immutable and so cannot change.</p> + </tp:docstring> + </property> + <property name="MutableContents" tp:name-for-bindings="Mutable_Contents" - type="b" access="read"> + type="b" access="read" tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tt>True</tt>, a stream of a different content type can be added + <p>If True, a stream of a different content type can be added after the Channel has been requested </p> - <p>If this property is missing, clients SHOULD assume that it is false, + <p>If this property is missing, clients SHOULD assume that it is False, and thus that the channel's streams cannot be changed once the call has started.</p> @@ -852,11 +1312,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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> @@ -875,32 +1330,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:hct 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.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is Stream_Transport_Type_GTalk_P2P.</p> + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p> </tp:docstring> </tp:hct> <tp:hct 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.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is Stream_Transport_Type_ICE.</p> + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p> </tp:docstring> </tp:hct> - <tp:hct name="wlm-8.5"> + <tp:hct 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.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is Stream_Transport_Type_WLM_8_5.</p> + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p> </tp:docstring> </tp:hct> - <tp:hct name="wlm-2009"> + <tp:hct name="shm"> <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.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is Stream_Transport_Type_WLM_2009.</p> + namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p> </tp:docstring> </tp:hct> @@ -931,7 +1386,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>For example, a client could advertise support for audio and video calls using Speex, Theora and H264 by having five handler capability tokens in its <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> + namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref> property:</p> <ul> diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index de58bfcc0..335c71fba 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -352,7 +352,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ while the SearchState is In_Progress, <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted, with the state Failed and the error - <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p> <p>Calling this method on a search in state Completed or Failed succeeds, but has no effect.</p> diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml index da31fadc3..4c1a8b761 100644 --- a/spec/Client_Handler_Future.xml +++ b/spec/Client_Handler_Future.xml @@ -33,6 +33,29 @@ API or ABI guarantees.</p> </tp:docstring> + <property name="BypassObservers" tp:name-for-bindings="Bypass_Observers" + type="b" access="read"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler are not passed to + observers for observing.</p> + + <tp:rationale> + <p>This is useful in use-cases where the handler doesn't want anyone + observing the channel - for example, because channels it handles + shouldn't be logged.</p> + </tp:rationale> + + <p>For service-activatable handlers, this property should be specified + in the handler's <tt>.client</tt> file as follows:</p> + +<pre> +[org.freedesktop.Telepathy.Client.Handler] +BypassObservers=true +</pre> + </tp:docstring> + </property> + <property name="RelatedConferencesBypassApproval" tp:name-for-bindings="Related_Conferences_Bypass_Approval" type="b" access="read"> diff --git a/spec/Connection.xml b/spec/Connection.xml index 72f1e343c..084705504 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -722,7 +722,7 @@ USA.</p> reasons SHOULD be treated like this reason.</p> <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Disconnected</code>.</p> + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p> </tp:docstring> </tp:enumvalue> @@ -985,7 +985,7 @@ USA.</p> <tp:type>Connection_Status_Reason</tp:type>, or may be a more specific Telepathy error (such as - <code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code> + <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code> for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml index 31f1554f8..704263cb9 100644 --- a/spec/Connection_Interface_Anonymity.xml +++ b/spec/Connection_Interface_Anonymity.xml @@ -111,60 +111,30 @@ </property> <property name="AnonymityMandatory" type="b" access="readwrite" - tp:name-for-bindings="Anonymity_Mandatory"> + tp:name-for-bindings="Anonymity_Mandatory" + tp:is-connection-parameter='yeah'> <tp:docstring> <p>This specifies whether or not the anonymity settings MUST be respected by the CM and any intermediaries between the local and remote contacts. If this is set to true but anonymity settings cannot be followed, then the session MUST be denied with a - <code>org.freedesktop.Telepathy.Errors.WouldBreakAnonymity</code> + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>WouldBreakAnonymity</tp:error-ref></code> error. Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref> SHOULD also set this property first (rather than accepting the CM's default value).</p> - - <p>This property SHOULD also be made available as a parameter of the - same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, - with the DBus_Property flag in its - <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed - by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityMandatory": <var>new_value</var> - }, [])</code> - </blockquote> </tp:docstring> </property> <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags" - access="readwrite" tp:name-for-bindings="Anonymity_Modes"> + access="readwrite" tp:name-for-bindings="Anonymity_Modes" + tp:is-connection-parameter='yeah'> <tp:docstring> <p>The currently enabled anonymity modes for the connection. Setting has the effect of requesting new modes for the connection, and may raise an error if the unsupported modes are set. Successfully changing the modes will result in emission of <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p> - - <p>This property SHOULD also be made available as a parameter of the - same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, - with the DBus_Property flag in its - <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed - by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityModes": <var>new_value</var> - }, [])</code> - </blockquote> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml index 3dc29e329..99a360283 100644 --- a/spec/Connection_Interface_Cellular.xml +++ b/spec/Connection_Interface_Cellular.xml @@ -30,7 +30,8 @@ </tp:docstring> <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period" - type="u" access="readwrite"> + type="u" access="readwrite" + tp:is-connection-parameter='yup'> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Define how long should the service centre try message delivery before giving up, failing delivery and deleting the message. A value of 0 @@ -40,32 +41,13 @@ implementations may round the value up (eg. to a minute or hour precision). The maximum validity period may vary depending on protocol or provider.</p> - - <p>Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >ConnectionManager.RequestConnection</tp:dbus-ref>, with the - <code>DBus_Property</code> flag. For connections managed by the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageValidityPeriod": <var>new_validity_period</var> - }, [])</code> - </blockquote> - - <p>The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.</p> </tp:docstring> </property> <property name="OverrideMessageServiceCentre" tp:name-for-bindings="Override_Message_Service_Centre" - type="b" access="readwrite"> + type="b" access="readwrite" + tp:is-connection-parameter='can i get a hell yeah?'> <tp:added version='0.19.12'>Previously, as an undocumented feature, setting <tp:member-ref>MessageServiceCentre</tp:member-ref> to the empty string caused the SIM's default SMSC to be used.</tp:added> @@ -82,31 +64,12 @@ by Mission Control, rather than the UI needing to save it elsewhere to be restored if the user wants to reactivate it.</p> </tp:rationale> - - <p>Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >ConnectionManager.RequestConnection</tp:dbus-ref>, with the - <code>DBus_Property</code> flag. For connections managed by the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.OverrideMessageServiceCentre": True - }, [])</code> - </blockquote> - - <p>The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.</p> </tp:docstring> </property> <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre" - type="s" access="readwrite"> + type="s" access="readwrite" + tp:is-connection-parameter='HELL YEAH!!!'> <tp:changed version='0.19.12'>This property's value is now ignored unless <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is @@ -120,26 +83,6 @@ <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is <code>False</code>, this property's value should be ignored by the CM in favour of the SIM's default SMSC.</p> - - <p>Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >ConnectionManager.RequestConnection</tp:dbus-ref>, with the - <code>DBus_Property</code> flag. For connections managed by the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageServiceCentre": <var>new_smsc_address</var> - }, [])</code> - </blockquote> - - <p>The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.</p> </tp:docstring> </property> @@ -171,7 +114,8 @@ <property name="MessageReducedCharacterSet" tp:name-for-bindings="Message_Reduced_Character_Set" - type="b" access="readwrite"> + type="b" access="readwrite" + tp:is-connection-parameter='no... just kidding! yes!'> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Determines whether SMSes containing characters that do not fit into a 7‐bit GSM character set should be sent as UCS‐2, or lossily @@ -180,26 +124,6 @@ financial cost of using twice as many SMSes); if <code>True</code>, the message will be recoded in an implementation‐specific way to fit into a country‐specific GSM reduced character set.</p> - - <p>Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >ConnectionManager.RequestConnection</tp:dbus-ref>, with the - <code>DBus_Property</code> flag. For connections managed by the - <tp:dbus-ref - namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, - this property SHOULD be set via the Account Manager as follows:</p> - - <blockquote> - <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" - >UpdateParameters</tp:dbus-ref>({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageReducedCharacterSet": <var>new_value</var> - }, [])</code> - </blockquote> - - <p>The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.</p> </tp:docstring> </property> </interface> diff --git a/spec/Connection_Interface_Keepalive.xml b/spec/Connection_Interface_Keepalive.xml new file mode 100644 index 000000000..9f4ac6833 --- /dev/null +++ b/spec/Connection_Interface_Keepalive.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Keepalive" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 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.Connection.Interface.Keepalive.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.21.2">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Most messaging protocols allow the client to send periodic + content-less pings to the server when the connection is otherwise idle, + to reassure both itself and the server that its connection is still + alive. Depending on the nature of the network connection, and the + device running the client, the desired interval between such pings may + vary.</p> + + <tp:rationale> + <p>For instance, on a mobile handset connected via 3G, + overly-frequent keepalives can drain the battery through needlessly + waking up the radio, and a relatively high interval is appropiate. By + contrast, a desktop computer is less likely to be asleep in the first + place, and users expect dropped connections to be noticed as soon as + possible.</p> + </tp:rationale> + + <p>This interface provides a + <tp:member-ref>KeepaliveInterval</tp:member-ref> property which + controls the frequency of keepalive pings, if any. Connection managers + implementing this property should also include it in <tp:dbus-ref + namespace='org.freedesktop.Telepathy'>Protocol.Parameters</tp:dbus-ref> + with the <code>DBus_Property</code> flag, allowing the desired value to + be stored in <tp:dbus-ref + namespace='org.freedesktop.Telepathy'>Account.Parameters</tp:dbus-ref> + and passed onto the connection by the account manager.</p> + </tp:docstring> + + <property name="KeepaliveInterval" type="u" access="readwrite" + tp:name-for-bindings="Keepalive_Interval" + tp:is-connection-parameter='och aye'> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time in seconds between pings sent to the server to ensure that + the connection is still alive, or <tt>0</tt> to disable such + pings.</p> + + <p>This property (and parameter) supersedes the older + <tt>keepalive-interval</tt> + <tp:type>Connection_Parameter_Name</tp:type>.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 709a9b952..d75d866dd 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -147,13 +147,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> <tp:flag suffix="DBus_Property" value="16"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This parameter is also a D-Bus property on the resulting <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>; a - parameter named <code>com.example.Duck.Macaroni</code> with this flag - corresponds to the <code>Macaroni</code> property on the - <code>com.example.Duck</code> interface. Its value can be queried - and possibly changed on an existing Connection using methods on the - <code>org.freedesktop.DBus.Properties</code> interface. + <p>This parameter is also a D-Bus property on the resulting + <tp:dbus-ref + namespace="ofdT">Connection</tp:dbus-ref>; a + parameter named <code>com.example.Duck.Macaroni</code> with this + flag corresponds to the <code>Macaroni</code> property on the + <code>com.example.Duck</code> interface. Its value can be queried + and possibly changed on an existing Connection using methods on the + <code>org.freedesktop.DBus.Properties</code> interface.</p> + + <p>When a parameter with this flag is changed with <tp:dbus-ref + namespace="ofdT">Account.UpdateParameters</tp:dbus-ref>, the + account manager will attempt to update its value on any running + connections. Thus, clients generally do not need to directly access + or update the connection property; instead, they SHOULD manipulate + <tp:dbus-ref namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> + + <tp:rationale> + <p>This allows runtime-configurable options to be stored and + maintained by the <tp:dbus-ref + namespace='ofdT'>AccountManager</tp:dbus-ref>, without needing to + invent a separate account preference for “properties that should + be set on the connection as soon as it is created”. It was + originally invented to manage <tp:dbus-ref + namespace='ofdT.Connection.Interface'>Cellular</tp:dbus-ref> + preferences.</p> + </tp:rationale> </tp:docstring> <tp:added version="0.17.16"/> </tp:flag> @@ -273,7 +292,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> A dictionary mapping parameter names to values of the appropriate type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> - and the above well-known list. + and the well-known list of names and value types documented on the + <tp:type>Connection_Parameter_Name</tp:type> type. </tp:docstring> </arg> <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name"> @@ -307,7 +327,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the - following well-known names and types should be used where appropriate:</p> + well-known names and types defined by the + <tp:type>Connection_Parameter_Name</tp:type> type should be used where + appropriate.</p> + + <p>Connection manager authors SHOULD avoid introducing parameters + whose default values would not be serializable in a + <code>.manager</code> file.</p> + + <tp:rationale> + <p>The same serialization format is used in Mission Control + to store accounts.</p> + </tp:rationale> + + <p>Every successful RequestConnection call will cause the emission of a + <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly + created connection. The + requester can use the returned object path and service name + independently of the emission of that signal. In that case this signal + emission is most useful for, e.g. other processes that are monitoring + the creation of new connections.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested protocol is not supported by this manager + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested connection already appears to exist + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Unrecognised connection parameters + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:simple-type name="Connection_Parameter_Name" type="s"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known connection parameter names, along with their expected + type. Where possible, connection managers should use names and types + from this list in the <tp:dbus-ref + namespace='ofdT.Protocol'>Parameters</tp:dbus-ref> that may be passed + to <tp:member-ref>RequestConnection</tp:member-ref>.</p> <dl> <dt>account (s)</dt> @@ -354,47 +422,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ significant if the stun-server is also supplied.</dd> <dt>keepalive-interval (u)</dt> - <dd>The time in seconds between pings sent to the server to ensure - that the connection is still alive, or <tt>0</tt> to disable such - pings.</dd> + <dd> + <p>The time in seconds between pings sent to the server to ensure + that the connection is still alive, or <tt>0</tt> to disable such + pings.</p> + + <p>This parameter is superseded by the <tp:dbus-ref + namespace='ofdT.Connection.Interface.Keepalive.DRAFT'>KeepaliveInterval</tp:dbus-ref> + property, which can be updated on an already-established + connection as well as being specified when requesting the + connection. Clients SHOULD provide that parameter instead, if + allowed; new connection managers SHOULD implement it in + preference to this one.</p> + </dd> </dl> - <p>Connection manager authors SHOULD avoid introducing parameters - whose default values would not be serializable in a - <code>.manager</code> file.</p> - - <tp:rationale> - <p>The same serialization format is used in Mission Control - to store accounts.</p> - </tp:rationale> + <p>The following well-known parameter names correspond to D-Bus + properties, and thus their <tp:type>Conn_Mgr_Param_Flags</tp:type> + should include DBus_Property. See that flag for more details on this + kind of parameter.</p> - <p>Every successful RequestConnection call will cause the emission of a - <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly - created connection. The - requester can use the returned object path and service name - independently of the emission of that signal. In that case this signal - emission is most useful for, e.g. other processes that are monitoring - the creation of new connections.</p> + <tp:list-dbus-property-parameters/> </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The requested protocol is not supported by this manager - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The requested connection already appears to exist - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - Unrecognised connection parameters - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> + </tp:simple-type> <property name="Interfaces" tp:name-for-bindings="Interfaces" type="as" access="read"> diff --git a/spec/Makefile.am b/spec/Makefile.am index d0849249e..f41b3faf0 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -75,6 +75,7 @@ EXTRA_DIST = \ Connection_Interface_Contact_List.xml \ Connection_Interface_Contacts.xml \ Connection_Interface_Forwarding.xml \ + Connection_Interface_Keepalive.xml \ Connection_Interface_Location.xml \ Connection_Interface_Mail_Notification.xml \ Connection_Interface_Power_Saving.xml \ diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index c9ae78f46..8881c115b 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -513,9 +513,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <signal name="StartTelephonyEvent" tp:name-for-bindings="Start_Telephony_Event"> - <arg name="Event" type="y"> + <arg name="Event" type="y" tp:type="DTMF_Event"> <tp:docstring> - A telephony event code as defined by RFC 4733. + A telephony event code. </tp:docstring> </arg> <tp:docstring> @@ -523,6 +523,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ over this stream until StopTelephonyEvent is called. </tp:docstring> </signal> + <signal name="StartNamedTelephonyEvent" + tp:name-for-bindings="Start_Named_Telephony_Event"> + <tp:added version="0.21.2"/> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + A telephony event code as defined by RFC 4733. + </tp:docstring> + </arg> + <arg name="Codec_ID" type="u"> + <tp:docstring> + The payload type to use when sending events. The value 0xFFFFFFFF + means to send with the already configured event type instead of using + the specified one. + </tp:docstring> + </arg> + <tp:docstring> + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as a RFC 4733 named event, not as sound. You can also force a specific + Codec ID. + </tp:docstring> + </signal> + <signal name="StartSoundTelephonyEvent" + tp:name-for-bindings="Start_Sound_Telephony_Event"> + <tp:added version="0.21.2"/> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + A telephony event code as defined by RFC 4733. + </tp:docstring> + </arg> + <tp:docstring> + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as sound instead of as a named event. + </tp:docstring> + </signal> <signal name="StopTelephonyEvent" tp:name-for-bindings="Stop_Telephony_Event"> <tp:docstring> diff --git a/spec/all.xml b/spec/all.xml index 2709a4124..22568f5ad 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.21.1</tp:version> +<tp:version>0.21.2</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> @@ -60,6 +60,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Contact_List.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> <xi:include href="Connection_Interface_Forwarding.xml"/> + <xi:include href="Connection_Interface_Keepalive.xml"/> <xi:include href="Connection_Interface_Location.xml"/> <xi:include href="Connection_Interface_Mail_Notification.xml"/> <xi:include href="Connection_Interface_Power_Saving.xml"/> diff --git a/spec/errors.xml b/spec/errors.xml index a5368c02f..58a9d9d5d 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -491,6 +491,15 @@ </tp:docstring> </tp:error> + <tp:error name="Rejected"> + <tp:added version="0.21.2"/> + <tp:docstring> + Raised when an incoming or outgoing <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is + rejected by the the receiver. + </tp:docstring> + </tp:error> + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/template.xml b/spec/template.xml index d752d721c..726472070 100644 --- a/spec/template.xml +++ b/spec/template.xml @@ -22,7 +22,7 @@ <interface name="org.freedesktop.Telepathy.Foo.DRAFT" tp:causes-havoc="experimental"> - <tp:added version="0.19.UNRELEASED">(draft 1)</tp:added> + <tp:added version="0.21.UNRELEASED">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Foo.</p> |