diff options
| author | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2012-02-21 15:04:05 -0200 |
|---|---|---|
| committer | Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk> | 2012-02-21 15:24:07 -0200 |
| commit | a0241265d075952d9f27c2bed52b1bd07be8c343 (patch) | |
| tree | d783ecfa6d1340837fbd48e5988f48fb0b37300a /spec | |
| parent | 61a5b530dec334b4edcc5e05095f862ebc529338 (diff) | |
Update to spec 0.25.2
Changes in this commit:
- Update all interfaces to spec 0.25.2
- As this spec renames Conn.I.Addressing.DRAFT to Conn.I.Addressing1 as final version and we don't want
to break the build, the changes to support Addressing1 are already included in this commit
- Add all missing pretty headers
- Generate proxy for Channel.I.CaptchaAuthentication
- Generate proxies for Call1 interfaces. To avoid breaking the build, the support for Conn.I.Addressing
Diffstat (limited to 'spec')
28 files changed, 970 insertions, 178 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index 675ea812..fff0232d 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Account" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008-2012 Collabora Ltd.</tp:copyright> <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or @@ -277,6 +277,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </ul> + <p>For the <tt>IRC</tt> protocol, the network name (<tt>freenode</tt>, + <tt>gimpnet</tt>, etc.) can be used if relevant.</p> + <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a corresponding brand-specific icon name, if possible. In the future, this property may be used as an index into additional @@ -710,6 +713,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="Supersedes" tp:name-for-bindings="Supersedes" + type="ao" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the object paths of formerly-used accounts which are + superseded by this one.</p> + + <tp:rationale> + <p>For instance, if an account is migrated from one connection + manager implementation to another, or even from one protocol + to another (for instance formerly-proprietary services which + can now be accessed via XMPP), log storage services could + look for logs under all of the superseded object paths as well + as the new object path.</p> + + <p>This is a list because a single user-visible account could be + migrated more than once.</p> + </tp:rationale> + + <p>If the Account Manager implementation performs an account migration + automatically, it SHOULD set this property. If a client performs + an account migration, it SHOULD set this property via + via the Properties argument of <tp:dbus-ref + namespace="ofdT.AccountManager">CreateAccount</tp:dbus-ref> + when creating the migrated account. In either case, the value + SHOULD include the old account's path, and every path from + the old account's Supersedes property.</p> + </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml index 52cd42a1..defa074f 100644 --- a/spec/Account_Manager.xml +++ b/spec/Account_Manager.xml @@ -145,6 +145,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>, <tp:dbus-ref + namespace="ofdT.Account">Supersedes</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref> and <tp:dbus-ref diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index ef08acc3..be3376fe 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This object represents one Content inside a <tp:dbus-ref @@ -52,7 +51,7 @@ arguments</tp:changed> <tp:docstring> Remove the content from the call. This will cause - <tp:member-ref>Removed</tp:member-ref>((self_handle, + <tp:dbus-ref namespace="ofdT.Channel.Type">Call1.ContentRemoved</tp:dbus-ref>((self_handle, <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "", "")) to be emitted. </tp:docstring> @@ -68,15 +67,6 @@ </tp:possible-errors> </method> - <signal name="Removed" tp:name-for-bindings="Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the content is removed from the call. This - is the same as the <tp:dbus-ref - namespace="ofdT.Channel.Type">Call1.ContentRemoved</tp:dbus-ref> - signal.</p> - </tp:docstring> - </signal> - <property name="Interfaces" tp:name-for-bindings="Interfaces" type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> <tp:added version="0.19.11"/> diff --git a/spec/Call_Content_Interface_Audio_Control.xml b/spec/Call_Content_Interface_Audio_Control.xml index b13e02f5..0efb488c 100644 --- a/spec/Call_Content_Interface_Audio_Control.xml +++ b/spec/Call_Content_Interface_Audio_Control.xml @@ -19,9 +19,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.AudioControl" - tp:causes-havoc="experimental"> - <tp:added version="0.25.1">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.AudioControl"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.Interface.Media"/> <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/> diff --git a/spec/Call_Content_Interface_DTMF.xml b/spec/Call_Content_Interface_DTMF.xml new file mode 100644 index 00000000..f6e9bda0 --- /dev/null +++ b/spec/Call_Content_Interface_DTMF.xml @@ -0,0 +1,229 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</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.Call1.Content.Interface.DTMF"> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/> + <tp:added version="0.25.2">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An interface that gives audio Contents the ability to send DTMF events + which have been established using the Call1 channel + type. The event codes used are in common with those defined in <a + href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are + listed in the <tp:type>DTMF_Event</tp:type> enumeration. + </tp:docstring> + + <method name="StartTone" tp:name-for-bindings="Start_Tone"> + <arg direction="in" name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring> + </arg> + + <tp:docstring> + <p>Start sending a DTMF tone to all eligible streams in the channel. + Where possible, the tone will continue until + <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols, + it may only be possible to send events with a predetermined length. In + this case, the implementation MAY emit a fixed-length tone, and the + StopTone method call SHOULD return NotAvailable.</p> + <tp:rationale> + The client may wish to control the exact duration and timing of the + tones sent as a result of user's interaction with the dialpad, thus + starting and stopping the tone sending explicitly. + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The event id was invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StopTone" tp:name-for-bindings="Stop_Tone"> + <tp:docstring> + Stop sending any DTMF tones which have been started using the + <tp:member-ref>StartTone</tp:member-ref> or + <tp:member-ref>MultipleTones</tp:member-ref> methods. + If there is no current tone, this method will do nothing. + If MultipleTones was used, the client should not assume the + sending has stopped immediately; instead, the client should wait + for the StoppedTones signal. + <tp:rationale> + On some protocols it might be impossible to cancel queued tones + immediately. + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Continuous tones are not supported by this stream. Deprecated, + since stream IDs are ignored. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones"> + <arg direction="in" name="Tones" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string representation of one or more DTMF + events. Implementations of this method MUST support all of the + following characters in this string:</p> + + <ul> + <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#' + correspond to the members of <tp:type>DTMF_Event</tp:type></li> + + <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an + implementation-defined pause, typically for 3 seconds</li> + + <li>'w' or 'W' waits for the user to continue, by stopping + interpretation of the string, and if there is more to be played, + emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal + with the rest of the string as its argument: see that signal + for details</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + <p>Send multiple DTMF events to all eligible streams in the channel. + Each tone will be played for an implementation-defined number of + milliseconds (typically 250ms), followed by a gap before the next tone + is played (typically 100ms). The + duration and gap are defined by the protocol or connection manager.</p> + + <tp:rationale> + <p>In cases where the client knows in advance the tone sequence it + wants to send, it's easier to use this method than manually start + and stop each tone in the sequence.</p> + + <p>The tone and gap lengths may need to vary for interoperability, + according to the protocol and other implementations' ability to + recognise tones. At the time of writing, GStreamer uses a + minimum of 250ms tones and 100ms gaps when playing in-band DTMF + in the normal audio stream, or 70ms tones and 50ms gaps when + encoding DTMF as <code>audio/telephone-event</code>.</p> + </tp:rationale> + + <p>Tone overlaping or queueing is not supported, so this method can only + be called if no DTMF tones are already being played.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The supplied Tones string was invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + DTMF tones are already being played. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <property name="CurrentlySendingTones" + tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read"> + <tp:docstring> + Indicates whether there are DTMF tones currently being sent in the + channel. If so, the client should wait for + <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to + send more tones. + </tp:docstring> + </property> + + <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones" + type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The tones waiting for the user to continue, if any.</p> + + <p>When this property is set to a non-empty value, + <tp:member-ref>TonesDeferred</tp:member-ref> is emitted. + When any tones are played (i.e. whenever + <tp:member-ref>SendingTones</tp:member-ref> is emitted), + this property is reset to the empty string.</p> + </tp:docstring> + </property> + + <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred"> + <tp:added version="0.21.3" /> + <arg name="Tones" type="s"> + <tp:docstring>The new non-empty value of + <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when 'w' or 'W', indicating "wait for the user to continue", + is encountered while playing a DTMF string queued by + <tp:member-ref>MultipleTones</tp:member-ref>. Any queued DTMF events + after the 'w', which have not yet been played, are placed in the + <tp:member-ref>DeferredTones</tp:member-ref> property and copied + into this signal's argument.</p> + + <p>When the channel handler is ready to continue, it MAY pass the + value of <tp:member-ref>DeferredTones</tp:member-ref> to + <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending. + Alternatively, it MAY ignore the deferred tones, or even play + different tones instead. Any deferred tones are discarded the next + time a tone is played.</p> + + <p>This signal SHOULD NOT be emitted if there is nothing left to play, + i.e. if the 'w' was the last character in the DTMF string.</p> + </tp:docstring> + </signal> + + <signal name="SendingTones" tp:name-for-bindings="Sending_Tones"> + <arg name="Tones" type="s"> + <tp:docstring>DTMF string (one or more events) that is to be played. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tone(s)are being sent to all eligible streams in the channel. + The signal is provided to indicating the fact that the streams are + currently being used to send one or more DTMF tones, so any other + media input is not getting through to the audio stream. It also + serves as a cue for the + <tp:member-ref>StopTone</tp:member-ref> method.</p> + </tp:docstring> + </signal> + + <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones"> + <arg name="Cancelled" type="b"> + <tp:docstring>True if the DTMF tones were actively cancelled via + <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>DTMF tones have finished playing on streams in this channel.</p> + </tp:docstring> + </signal> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index ca5ed36b..3f04df9b 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -21,9 +21,8 @@ </tp:license> <interface - name="org.freedesktop.Telepathy.Call1.Content.Interface.Media" - tp:causes-havoc="experimental"> - <tp:added version="0.23.4">(draft 2)</tp:added> + name="org.freedesktop.Telepathy.Call1.Content.Interface.Media"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -225,11 +224,6 @@ >MediaDescription</tp:dbus-ref> </tp:docstring> </tp:member> - <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The contact handle that this description applies to. - </tp:docstring> - </tp:member> <tp:member name="Properties" type="a{sv}" tp:type="Media_Description_Properties"> <tp:docstring> @@ -256,15 +250,6 @@ Otherwise, only parameters which strictly describe the media being sent can be changed. </tp:docstring> - <arg name="Remote_Contact" type="u" tp:type="Handle" direction="in"> - <tp:docstring> - The remote contact that this description should be negotiated with - (or 0 to mean "negotiate this with everyone"). Note that encoding - the same video multiple times is often needlessly expensive, so - differences in MediaDescriptions negotiated with different parties - in the call should be limited to payloading parameters if possible. - </tp:docstring> - </arg> <arg name="MediaDescription" direction="in" type="a{sv}" tp:type="Media_Description_Properties"> <tp:docstring> @@ -341,11 +326,6 @@ previous media description. </tp:docstring> </arg> - <arg name="Contact" type="u"> - <tp:docstring> - The remote contact the media description belongs to. - </tp:docstring> - </arg> <arg name="Properties" type="a{sv}" tp:type="Media_Description_Properties"> <tp:docstring> @@ -383,13 +363,6 @@ </p> </tp:docstring> - <arg name="Remote_Contact" type="u" tp:type="Handle"> - <tp:docstring> - The remote contact that this description was negotiated with - (or 0 to mean "negotiated with everyone"). - </tp:docstring> - </arg> - <arg name="Updated_Media_Description" type="a{sv}" tp:type="Media_Description_Properties"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -440,7 +413,7 @@ <property name="MediaDescriptionOffer" tp:name-for-bindings="Media_Description_Offer" - type="(oua{sv})" tp:type="Media_Description_Offer" access="read"> + type="(oa{sv})" tp:type="Media_Description_Offer" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The object path to the current <tp:dbus-ref namespace="ofdT.Call1.Content" diff --git a/spec/Call_Content_Interface_Video_Control.xml b/spec/Call_Content_Interface_Video_Control.xml index 086d4758..5a11dcba 100644 --- a/spec/Call_Content_Interface_Video_Control.xml +++ b/spec/Call_Content_Interface_Video_Control.xml @@ -19,9 +19,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.VideoControl" - tp:causes-havoc="experimental"> - <tp:added version="0.21.10">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.VideoControl"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.Interface.Media"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Call_Content_Media_Description.xml b/spec/Call_Content_Media_Description.xml index 7c494a41..88791a25 100644 --- a/spec/Call_Content_Media_Description.xml +++ b/spec/Call_Content_Media_Description.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription" - tp:causes-havoc="experimental"> - <tp:added version="0.23.4">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> This object represents a remote Description Offer to which the local @@ -69,7 +68,7 @@ Reject the proposed update to the remote description. </tp:docstring> <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason" - direction="out"> + direction="in"> <tp:docstring> A structured reason for the rejection. </tp:docstring> diff --git a/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml b/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml index f973306c..eb5fbdb6 100644 --- a/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml +++ b/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml @@ -18,9 +18,8 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPExtendedReports" - tp:causes-havoc="experimental"> - <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPExtendedReports"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> diff --git a/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml b/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml index f586fe4c..7a558cc3 100644 --- a/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml +++ b/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml @@ -18,9 +18,8 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPFeedback" - tp:causes-havoc="experimental"> - <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPFeedback"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml b/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml index a35615ad..25a77e02 100644 --- a/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml +++ b/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml @@ -18,9 +18,8 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTPHeaderExtensions" - tp:causes-havoc="experimental"> - <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTPHeaderExtensions"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Call_Interface_Mute.xml b/spec/Call_Interface_Mute.xml index 1202383f..573efcc8 100644 --- a/spec/Call_Interface_Mute.xml +++ b/spec/Call_Interface_Mute.xml @@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> <interface name="org.freedesktop.Telepathy.Call1.Interface.Mute" tp:causes-havoc="experimental"> - <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:xor-requires> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call1"/> <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/> diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index b8b347d4..729dc7ea 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Stream" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Stream"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>One stream inside a <tp:dbus-ref diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index 2aa7e52f..cf2397b4 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Stream.Endpoint" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Stream.Endpoint"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This object represents an endpoint for a stream. In a one-to-one @@ -340,7 +339,12 @@ <property name="Transport" tp:name-for-bindings="Transport" type="u" tp:type="Stream_Transport_Type" access="read"> <tp:docstring> - The transport type for the stream endpoint. + The transport type for the stream endpoint. This can be + different from the transport of the Stream in the case where + of falling back from <tp:value-ref + type="Stream_Transport_Type">ICE</tp:value-ref> to + <tp:value-ref + type="Stream_Transport_Type">Raw_UDP</tp:value-ref>. </tp:docstring> </property> diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index 450d5ea4..1356faa1 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call1.Stream.Interface.Media" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Call1.Stream.Interface.Media"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Call1.Stream"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -80,19 +79,6 @@ data, and everything is going swimmingly. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Pending_Pause" value="4"> - <tp:docstring> - The streaming implementation has been told to pause sending or - displaying data, but it has not yet indicated that it has done so. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Paused" value="5"> - <tp:docstring> - The streaming implementation has successfully paused either sending or - displaying data, and the local user's privacy or peace-and-quiet is - protected. - </tp:docstring> - </tp:enumvalue> </tp:enum> <property name="SendingState" tp:name-for-bindings="Sending_State" @@ -103,7 +89,7 @@ rely on reading this value and listening to <tp:member-ref>SendingStateChanged</tp:member-ref> to determine whether it should be sending media or not. It should not - need to listen to the Mute/Hold interfaces on the Call/Content. + need to listen to the Hold interfaces on the Call/Content. Feedback on success should be given via <tp:member-ref>CompleteSendingStateChange</tp:member-ref>. Failures should be reported via <tp:member-ref>ReportSendingFailure</tp:member-ref>. @@ -215,7 +201,7 @@ <method name="ReportReceivingFailure" tp:name-for-bindings="Report_Receiving_Failure"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Can be called at any point to indicate a failure in the outgoing + Can be called at any point to indicate a failure in the incoming portion of the stream. </tp:docstring> <arg name="Reason" type="u" tp:type="Call_State_Change_Reason" @@ -420,6 +406,16 @@ and then set the lowest priority candidate as the Raw UDP candidate. </tp:rationale> </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The minimal required candidates have not been set. For + example, for an RTP protocol, at least one candidate on the + component 1 (RTP) must have been set. + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <tp:enum type="u" name="Stream_Transport_Type"> diff --git a/spec/Channel.xml b/spec/Channel.xml index 11d3e509..e0fa7659 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -102,7 +102,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ MUST be present and not Handle_Type_None, and <tp:member-ref>TargetID</tp:member-ref> MUST NOT be present. Properties from - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref> MUST NOT be present.</p> <p>The channel that satisfies the request MUST either:</p> @@ -150,7 +150,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ MUST be present and not Handle_Type_None, and <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be present. Properties from - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing1</tp:dbus-ref> MUST NOT be present.The request MUST fail with error InvalidHandle, without side-effects, if the requested TargetID would not be accepted by diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml index 494fd7bf..2524ac7f 100644 --- a/spec/Channel_Interface_Addressing.xml +++ b/spec/Channel_Interface_Addressing.xml @@ -16,7 +16,7 @@ Lesser General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Addressing.DRAFT" + <interface name="org.freedesktop.Telepathy.Channel.Interface.Addressing1" tp:causes-havoc="experimental"> <tp:added version="0.19.12">(as draft)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Channel_Interface_Captcha_Authentication.xml b/spec/Channel_Interface_Captcha_Authentication.xml new file mode 100644 index 00000000..27b1e0cf --- /dev/null +++ b/spec/Channel_Interface_Captcha_Authentication.xml @@ -0,0 +1,505 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Captcha_Authentication" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010-2012 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Interface.CaptchaAuthentication1"> + <tp:added version="0.25.2">(version 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" + value="true"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel interface for captcha authentication. + When this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, it represents authentication with the server. In future, + it could also be used to authenticate with secondary services, + or even to authenticate end-to-end connections with contacts. As a result, + this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type" + >ServerAuthentication</tp:dbus-ref> to allow for a potential future + Channel.Type.PeerAuthentication interface.</p> + + <p>In any protocol that requires a captcha, the connection manager can + use this channel to let a user interface carry out a simple captcha + handshake with it, as a way to test the user is human + interactively.</p> + + <p>For channels managed by a + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>, + only the channel's <tp:dbus-ref + namespace="ofdT.Client">Handler</tp:dbus-ref> may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.</p> + + <p>The most commonly used form of captcha challenge is OCR (recognition + of distorted letters or words in an image), but for accessibility + reasons, this interface also allows various other types of challenge, + such as plain-text questions or recognition of words in audio. Its + structure is modelled on XMPP's + <a href="http://xmpp.org/extensions/xep-0158.html">XEP-0158</a>, + but can be used with other protocols by mapping their semantics + into those used in XMPP.</p> + + <tp:rationale> + <p>It is important to support multiple types of captcha + challenge to avoid discriminating against certain users; for + instance, blind or partially-sighted users cannot be expected + to answer an OCR challenge.</p> + + <p>XEP-0158 supports a superset of all other known protocols' captcha + interfaces, and is sufficiently elaborate that we expect it will + continue to do so.</p> + + <p>There can only be one Handler, which is a good fit for the + question/answer model implied by captchas.</p> + </tp:rationale> + </tp:docstring> + + <tp:struct name="Captcha_Info" array-name="Captcha_Info_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A struct containing information regarding a single captcha + mechanism.</p> + </tp:docstring> + <tp:member type="u" name="ID"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The ID with which to reference this captcha method + when retrieving its data and answering it. + They are unique within this channel instance only.</p> + </tp:docstring> + </tp:member> + <tp:member type="s" name="Type"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of challenge + <a href="http://xmpp.org/extensions/xep-0158.html#challenge"> + as defined by XEP-0158</a>. For instance, the commonly-used + "type the letters/words you see in this image" challenge is + represented by <code>ocr</code></p> + </tp:docstring> + </tp:member> + <tp:member type="s" name="Label"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A human-readable label for the challenge, as defined in + XEP-0158.</p> + + <p>If the server does not supply a label for a challenge of type + other than <code>qa</code>, connection managers SHOULD set Label + to an empty string instead of generating their own text. + If the Label is an empty string, the Handler SHOULD replace + it with a generic label in the user's locale, such as + the strings suggested in XEP-0158 (for instance, + <code>Enter the text you see</code> for <code>ocr</code> + challenges). The Handler MAY use those generic labels + in any case, as per + <a href="http://xmpp.org/extensions/xep-0158.html#i18n">the + Internationalization Considerations section of XEP-0158</a>.</p> + + <tp:rationale> + <p>Connection managers are not usually localized, so text + generated by the connection manager would be in English, + regardless of the user's locale. The Handler is better-placed + to generate a generic Label in the user's locale.</p> + </tp:rationale> + + <p>For challenges of type <code>qa</code>, the Label is a plain-text + question for the user to answer. The connection manager + SHOULD NOT provide an empty Label; if it does, the Handler + SHOULD treat that challenge as impossible, and SHOULD NOT + attempt to display it.</p> + </tp:docstring> + </tp:member> + <tp:member type="u" name="Flags" tp:type="Captcha_Flags"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One flag defined: Required. Most captchas will have no flags.</p> + </tp:docstring> + </tp:member> + <tp:member type="as" name="Available_MIME_Types"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of MIME types the server is offering to provide + for this captcha method.</p> + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Captcha_Answers"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A mapping of captcha IDs to answer strings. + </tp:docstring> + <tp:member type="u" name="ID"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The ID of the captcha to which the associated + answer string is answering. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Answer"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The answer string to answer the captcha referenced + by the associated ID. + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="CanRetryCaptcha" + tp:name-for-bindings="Can_Retry_Captcha" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>GetCaptchas</tp:member-ref> + can be expected to return new captcha information when + in the Local_Pending state. If false, + <tp:member-ref>GetCaptchas</tp:member-ref> will return + NotAvailable on subsequent calls.</p> + + <tp:rationale> + <p>Refreshing the captcha isn't required to work, although + some protocols and implementations allow it. This is usually + done in case a given captcha is unintelligible.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property type="u" tp:type="Captcha_Status" access="read" + name="CaptchaStatus" tp:name-for-bindings="Captcha_Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The current status of this channel.</p> + + <p>Because only the Handler should call methods on this interface, + the Handler MAY reduce round-trips by not fetching the initial + value of this property, and instead assume that is initially + Local_Pending.</p> + + <tp:rationale> + <p>This assumption normally avoids the need to call GetAll(), + since the values of <tp:member-ref>CaptchaError</tp:member-ref> + and <tp:member-ref>CaptchaErrorDetails</tp:member-ref> + are also implied by this assumption, and the only other + property is <tp:member-ref>CanRetryCaptcha</tp:member-ref>, + which is immutable.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property type="s" tp:type="DBus_Error_Name" access="read" + name="CaptchaError" tp:name-for-bindings="Captcha_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for the <tp:member-ref>CaptchaStatus</tp:member-ref>, or + an empty string if the state is neither Try_Again nor Failed.</p> + + <p>Typical values: "", Cancelled, AuthenticationFailed, + CaptchaNotSupported</p> + + <p>In particular, an ordinary authentication failure (as would + be produced for an incorrect answer) SHOULD be represented by + <tp:error-ref>AuthenticationFailed</tp:error-ref>, + cancellation by the user's request SHOULD be represented + by <tp:error-ref>Cancelled</tp:error-ref>, cancellation due + to the inability to display the captcha to the user or otherwise + answer it SHOULD be represented by + <tp:error-ref>CaptchaNotSupported</tp:error-ref>, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + <tp:error-ref>ServiceConfused</tp:error-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, this error code SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="CaptchaErrorDetails" + tp:name-for-bindings="Captcha_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>CaptchaError</tp:member-ref> is non-empty, + any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, these details SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <method name="GetCaptchas" tp:name-for-bindings="Get_Captchas"> + <arg direction="out" name="Captcha_Info" + type="a(ussuas)" tp:type="Captcha_Info[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Information about each of the available captcha methods. + </tp:docstring> + </arg> + <arg direction="out" name="Number_Required" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The number of captcha methods required to be answered + in order to successfully complete this captcha challenge + (most frequently 1, but XMPP allows servers to demand that + more than one captcha is answered). + </tp:docstring> + </arg> + <arg direction="out" name="Language" type="s" tp:type="Language_Tag"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The language of each Label in Captcha_Info if available, + for instance en_US, or "" if unknown. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Gets information regarding each of the captcha methods + available and which and how many need to be successfully answered</p> + + <p>To call this method successfully, the state must be Local_Pending + or Try_Again. If it is Local_Pending, it remains Local_Pending. If + called more than once while in Local_Pending state, or if the state + is Try_Again, this method fetches a new set of captcha challenges, + if possible, and the state returns to Local_Pending.</p> + + <tp:rationale> + <p>For instance, you could call GetCaptchas again from Local_Pending + state if the user indicates that they can't understand the + initially-offered captcha.</p> + + <p>This is a method, not a property, so that it can be used to + fetch more than one set of captcha challenges, and so that + change notification is not required. Only the Handler should + call this method and calling GetAll would not reduce round-trips, + so the usual reasons to prefer a property do not apply here.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is not Local_Pending or Try_Again, or it has + already been called and + <tp:member-ref>CanRetryCaptcha</tp:member-ref> is False. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="GetCaptchaData" tp:name-for-bindings="Get_Captcha_Data"> + <arg direction="in" name="ID" type="u"> + <tp:docstring> + The ID of the captcha of which to retrieve data. + </tp:docstring> + </arg> + <arg direction="in" name="Mime_Type" type="s"> + <tp:docstring> + MIME type picked by the Handler, chosen from the list of MIME + types received in <tp:member-ref>GetCaptchas</tp:member-ref>. + <tp:rationale> + XEP-0158 allows the same captcha to be made available in + multiple formats, for instance the same spoken question as + audio/x-wav, application/ogg and audio/speex. + </tp:rationale> + </tp:docstring> + </arg> + <arg direction="out" name="Captcha_Data" type="ay"> + <tp:docstring> + Captcha data as requested. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Fetch and return the captcha data. In protocols + where captchas are downloaded out-of-band (for instance via HTTP), + the connection manager is expected to do so.</p> + <p>Returns an empty array if the type was "qa"</p> + <tp:rationale> + <p>If audio-based and image-based captchas are both available, + we don't want to waste time downloading the audio until/unless + the user asks to hear it. The extra D-Bus round-trips are not + a problem, since they are expected to be quick compared with + the time taken for the user to solve the captcha.</p> + </tp:rationale> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The state is not in Local_Pending or + <tp:member-ref>GetCaptchas</tp:member-ref> had never been called. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AnswerCaptchas" tp:name-for-bindings="Answer_Captchas"> + <arg direction="in" name="Answers" + type="a{us}" tp:type="Captcha_Answers"> + <tp:docstring> + The mapping of captcha IDs to answer strings. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Answer as many captchas as desired and/or required.</p> + <p>Callable in state Local_Pending only. State changes to + Remote_Pending.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The state is not in Local_Pending. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="CancelCaptcha" tp:name-for-bindings="Cancel_Captcha"> + <arg direction="in" name="Reason" + type="u" tp:type="Captcha_Cancel_Reason"> + <tp:docstring> + Reason for cancelling. This MAY be used to choose an error + response to the remote server, and SHOULD also be reflected + in the <tp:member-ref>CaptchaError</tp:member-ref>. + </tp:docstring> + </arg> + <arg direction="in" name="Debug_Message" type="s"> + <tp:docstring> + A textual description of the reason for cancelling, supplied + by the Handler. This message SHOULD NOT be sent to the remote + server, but SHOULD be copied into the 'debug-message' field + of the <tp:member-ref>CaptchaErrorDetails</tp:member-ref> and + <tp:dbus-ref namespace="ofdT.Connection">ConnectionError</tp:dbus-ref>. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Cancel. State changes to Failed with error NotAvailable or + Cancelled if it isn't already Failed. All you can do now is + to close the channel.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The current state is Failed. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <tp:flags name="Captcha_Flags" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra flags to include with Captcha information</p> + </tp:docstring> + + <tp:flag suffix="Required" value="1"> + <tp:docstring> + This captcha mechanism is required to be successfully + answered in order to pass this captcha challenge. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:enum name="Captcha_Cancel_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why captcha authentication was aborted by the client.</p> + </tp:docstring> + + <tp:enumvalue suffix="User_Cancelled" value="0"> + <tp:docstring> + The user aborted the authentication. If this is used, the + <tp:member-ref>CaptchaError</tp:member-ref> SHOULD be set to + <tp:error-ref>Cancelled</tp:error-ref> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Not_Supported" value="1"> + <tp:docstring> + The Handler doesn't support the given/required captcha types. + If this is used, the <tp:member-ref>CaptchaError</tp:member-ref> + SHOULD be set to <tp:error-ref>CaptchaNotSupported</tp:error-ref>. + This SHOULD also be used if + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> is called + before <tp:member-ref>CancelCaptcha</tp:member-ref>. + <tp:rationale> + If no Handler supports captcha channels, + the ChannelDispatcher will just call + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref>, + because it has no knowledge of specific channel types. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Service_Confused" value="2"> + <tp:docstring> + The Handler doesn't understand the captcha data received. The + challenger may be sending gibberish. + If this is used, the <tp:member-ref>CaptchaError</tp:member-ref> + SHOULD be set to <tp:error-ref>ServiceConfused</tp:error-ref>. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Captcha_Status" type="u" plural="Captcha_Statuses"> + <tp:enumvalue suffix="Local_Pending" value="0"> + <tp:docstring> + The challenge/response exchange is in progress and waiting for + a local action. Call <tp:member-ref>AnswerCaptchas</tp:member-ref> + to go to the Remote_Pending state, or call + <tp:member-ref>CancelCaptcha</tp:member-ref> followed by + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> + to give up. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:docstring> + The challenge/response exchange is in progress and waiting for + a response from the server. Wait for a reply from the server, + which will result in the Succeeded, Try_Again, or Failed state, + or call <tp:member-ref>CancelCaptcha</tp:member-ref> followed by + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> + to give up. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Succeeded" value="2"> + <tp:docstring> + Everyone is happy. Connection to the server will proceed as soon as + this state is reached. There is nothing useful to do in this state + except to call <tp:dbus-ref + namespace="ofdT.Channel">Close</tp:dbus-ref> + to close the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Try_Again" value="3"> + <tp:docstring> + The server has indicated an authentication failure. + Call <tp:member-ref>GetCaptchas</tp:member-ref> again to get + a new captcha, or + <tp:member-ref>CancelCaptcha</tp:member-ref> followed by + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> + to give up. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Failed" value="4"> + <tp:docstring> + Authentication has failed in some way. There is nothing + useful to do in this state except to close the channel with + <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref>. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index bb579a11..00e3a549 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -23,11 +23,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call1"/> </tp:xor-requires> + + <tp:changed version="0.25.2">The only part of this spec that should + be used with a Call1 channel is the "InitialTones" property. + </tp:changed> + <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this - interface should now be ignored by CMs. This is primarily to allow this - interface to be used with <tp:dbus-ref - namespace='ofdT.Channel.Type'>Call1</tp:dbus-ref> - channels.</tp:changed> + interface can now be ignored by CMs. + </tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An interface that gives a Channel the ability to send DTMF events over @@ -207,7 +210,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <property name="InitialTones" tp:name-for-bindings="Initial_Tones" - type="s" access="read"> + type="s" access="read" tp:immutable="yes" tp:requestable="yes"> <tp:added version="0.19.6" /> <tp:docstring> <p>If non-empty in a channel request that will create a new channel, @@ -215,6 +218,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ at least one eligible audio stream has been created in the channel.</p> + <p>This should only be used with InitialAudio=true.</p> + <p>This property is immutable (cannot change).</p> </tp:docstring> </property> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index 0ea1319c..383db251 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -17,9 +17,8 @@ You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Call1" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Channel.Type.Call1"> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires @@ -111,7 +110,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. something. When the CM has information indicating that the remote contact has been notified about the call (or immediately if the network is known not to convey such information) it should also change to - <tp:value-ref type="Call_State">Ringing</tp:value-ref>. All changes to + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. All changes to the <tp:member-ref>CallState</tp:member-ref> property are signalled using the <tp:member-ref>CallStateChanged</tp:member-ref> signal.</p> @@ -324,7 +323,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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:value-ref type="Call_State">Ringing</tp:value-ref> (an incoming + <tp:value-ref type="Call_State">Initialised</tp:value-ref> (an incoming call is ready and waiting for the user to be notified). Calling this method SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit <tp:value-ref type="Call_Flags">Locally_Ringing</tp:value-ref>, and notify the @@ -346,7 +345,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> The call is no longer in state - <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. </tp:docstring> </tp:error> </tp:possible-errors> @@ -363,7 +362,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. property is False, and the <tp:member-ref>CallState</tp:member-ref> is <tp:value-ref type="Call_State">Initialising</tp:value-ref> or - <tp:value-ref type="Call_State">Ringing</tp:value-ref>. Calling this method + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. Calling this method SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref>, and notify the remote contact that the call is in a queue (if the @@ -380,13 +379,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> The call was <tp:dbus-ref namespace="ofdT.Channel" - >Requested</tp:dbus-ref>, so ringing does not make sense. + >Requested</tp:dbus-ref>, so queueing 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 - <tp:value-ref type="Call_State">Initialising</tp:value-ref> or _Ringing. + <tp:value-ref type="Call_State">Initialising</tp:value-ref> or + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. </tp:docstring> </tp:error> </tp:possible-errors> @@ -395,7 +395,7 @@ 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 - <tp:value-ref type="Call_State">Ringing</tp:value-ref>, accept the incoming call. + <tp:value-ref type="Call_State">Initialised</tp:value-ref>, accept the incoming call. This changes the <tp:member-ref>CallState</tp:member-ref> to <tp:value-ref type="Call_State">Accepted</tp:value-ref>.</p> @@ -512,6 +512,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. call. </tp:docstring> </arg> + <arg direction="in" name="InitialDirection" type="u" + tp:type="Media_Stream_Direction"> + <tp:docstring> + The requested initial direction of the new content. + </tp:docstring> + </arg> <arg direction="out" name="Content" type="o"> <tp:docstring> Path to the newly-created <tp:dbus-ref @@ -603,18 +609,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <ul> <li>Pending_Initiator → Initialising (for outgoing calls, when <tp:member-ref>Accept</tp:member-ref> is called)</li> - <li>Initialising → Ringing (for outgoing calls, when + <li>Initialising → Initialised (for outgoing calls, when the remote client indicates that the user has been notified about the call. If the network is known not to provide feedback about whether the remote side is ringing, then the call should immediately be set to Ringing.</li> - <li>Initialising → Ringing (for incoming calls, when e.g. the + <li>Initialising → Initialised (for incoming calls, when e.g. the implementation has been initialised far enough that it is sensible to notify the user about the call (to reduce the probability that the user will pick up the call and have it immediately fail). The UI should then alert the user about the call, and call <tp:member-ref>SetRinging</tp:member-ref>)</li> - <li>Ringing → Accepted (for outgoing calls to a contact, + <li>Initialised → Accepted (for outgoing calls to a contact, when the remote contact accepts the call; for incoming calls, when <tp:member-ref>Accept</tp:member-ref> is called.)</li> <li>Accepted → Active (when the local user successfully @@ -664,7 +670,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. this state. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Ringing" value="3"> + <tp:enumvalue suffix="Initialised" value="3"> <tp:docstring> In the outgoing case: at least one called user has been alerted about the call (a SIP 180 (Ringing) packet or equivalent has been @@ -731,45 +737,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Locally_Muted" value="2"> - <tp:docstring> - The call has been muted by the local user, e.g. using the - <tp:dbus-ref namespace="ofdT.Call1.Interface" - >Mute</tp:dbus-ref> interface. This flag SHOULD only - be set if there is at least one Content, and all Contents - are locally muted (for the same reason as Locally_Held). - - <tp:rationale> - This flag exists to provide a simplified verson of <tp:dbus-ref - namespace="ofdT.Call1.Interface.Mute" - >MuteStateChanged</tp:dbus-ref>, - to reduce the number of signals that need to be - listened to by a simple UI. - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Locally_Ringing" value="4"> + <tp:flag suffix="Locally_Ringing" value="2"> <tp:docstring> This flag exists for observability of the <tp:member-ref>SetRinging</tp:member-ref> method (e.g. so that loggers can tell whether the call got as far as alerting the user, or whether something went wrong before then). It should be set when the SetRinging is called, and unset when the call leaves - <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. </tp:docstring> </tp:flag> - <tp:flag suffix="Locally_Queued" value="8"> + <tp:flag suffix="Locally_Queued" value="4"> <tp:docstring> This flag exists for observability of the <tp:member-ref>SetQueued</tp:member-ref> method. It should be set when the SetQueued is called, and unset when the call leaves - <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + <tp:value-ref type="Call_State">Initialising</tp:value-ref> or + <tp:value-ref type="Call_State">Initialised</tp:value-ref>. </tp:docstring> </tp:flag> - <tp:flag suffix="Forwarded" value="16"> + <tp:flag suffix="Forwarded" value="8"> <tp:docstring> The initiator of the call originally called a contact other than the current recipient of the call, but the call was then forwarded or @@ -779,7 +768,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Clearing" value="32"> + <tp:flag suffix="Clearing" value="16"> <tp:docstring> This flag only occurs when the CallState is Ended. The call with this flag set has ended, but not all resources corresponding to the @@ -842,6 +831,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The value of this key has the same units and scale as <tp:dbus-ref namespace="ofdT.Connection.Interface.Balance">AccountBalance</tp:dbus-ref>. </dd> + + <dt>forwarded-to - u</dt> + <dd>Optionally included when the + <tp:member-ref>CallStateReason</tp:member-ref> is + Forwarded. It indicates the handle to whom the Call was + forwarded.</dd> + + <dt>forwarded-to-id - s</dt> + <dd>The string that would result from inspecting the + <code>forwarded-to</code> key + (i.e. the contact's identifier in the IM protocol).</dd> </dl> </tp:docstring> </property> @@ -920,9 +920,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="Forwarded" value="3"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call was forwarded. If known, the handle of the contact - the call was forwarded to will be indicated by the Actor member - of a <tp:type>Call_State_Reason</tp:type> struct.</p> + <p>The call was forwarded. If known, the handle of the + contact the call was forwarded to will be indicated by the + "forwarded-to" member of a + <tp:member-ref>CallStateDetails</tp:member-ref> dictionnary + in the <tp:member-ref>CallStateChanged</tp:member-ref> + signal.</p> </tp:docstring> </tp:enumvalue> @@ -930,7 +933,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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:value-ref type="Call_State">Ringing</tp:value-ref> or + <tp:value-ref type="Call_State">Initialised</tp:value-ref> or <tp:value-ref type="Call_State">Ended</tp:value-ref> (or a content's direction changed) because it was rejected by the remote user.</p> <p>Corresponds to <tp:error-ref>Rejected</tp:error-ref></p> @@ -941,7 +944,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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:value-ref type="Call_State">Ringing</tp:value-ref> or + <tp:value-ref type="Call_State">Initialised</tp:value-ref> or <tp:value-ref type="Call_State">Ended</tp:value-ref> because the initiator ended the call before the receiver accepted it. With an incoming call this state change reason signifies a missed @@ -976,7 +979,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <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:value-ref type="Call_State">Ringing</tp:value-ref> + <tp:value-ref type="Call_State">Initialised</tp:value-ref> <tp:value-ref type="Call_State">Ended</tp:value-ref> because the receiver is busy (e.g. is already engaged in another call, and has not placed the initiator in a call-waiting queue).</p> @@ -1214,21 +1217,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Muted" value="4"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call member has muted their participation in this call. Note - that many protocols will not signal this flag, so clients should - not rely on it being set.</p> - - <tp:rationale> - <p>This is a flag per member, not a flag for the call as a whole, - because in conference calls, any member could mute their own - streams.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Conference_Host" value="8"> + <tp:flag suffix="Conference_Host" value="4"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> This contact has merged this call into a conference. Note that GSM provides a notification when the remote party merges a call into a diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml index ef9df3ee..129e6716 100644 --- a/spec/Connection_Interface_Addressing.xml +++ b/spec/Connection_Interface_Addressing.xml @@ -1,6 +1,6 @@ <?xml version="1.0" ?> <node name="/Connection_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2010 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2010-2012 Collabora Limited </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 @@ -16,12 +16,10 @@ 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.Addressing.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Addressing1"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> - <tp:added version="0.19.12">(as draft)</tp:added> - <tp:changed version="0.25.1">Both methods now return two dictionaries.</tp:changed> + <tp:added version="0.25.2">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface deals with the multiple address types that can refer to the same contact, such as vCard fields and URIs.</p> @@ -201,11 +199,20 @@ <tp:mapping name="VCard_Field_Address_Map" array-name=""> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping of vCard fields and addresses that repreent - the given contact.</p> + <p>A mapping of vCard fields and addresses equivalent to a + particular contact's protocol identifier. For instance, + on XMPP this would contain <code>x-jabber</code> for all + contacts, and <code>x-facebook-id</code> for contacts on + Facebook's server.</p> </tp:docstring> - <tp:member type="s" name="VCard_Field"/> - <tp:member type="s" name="Address"/> + <tp:member type="s" name="VCard_Field"> + <tp:docstring>A vCard field, such as + <code>x-jabber</code>.</tp:docstring> + </tp:member> + <tp:member type="s" name="Address"> + <tp:docstring>The value of that vCard field for the + contact.</tp:docstring> + </tp:member> </tp:mapping> <tp:contact-attribute name="addresses" type="a{ss}" diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index 033c64d1..7b9499ff 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -841,6 +841,35 @@ </tp:docstring> </property> + <property name="DownloadAtConnection" type="b" access="read" + tp:name-for-bindings="Download_At_Connection" + tp:is-connection-parameter='yes'> + <tp:added version="0.25.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the contact list is automatically downloaded at + connection. If false, the contact list is only downloaded + when requested explicitely with + <tp:member-ref>Download</tp:member-ref>.</p> + + <tp:rationale> + <p>Downloading the contact list uses bandwidth and is not always + necessary or desired. For example, a client could cache the + contact list from previous connections and accept less regular + updates, it could get the contact list from an out-of-band + protocol-specific way, or it could not need the contact list at + all.</p> + </tp:rationale> + + <p>Connection managers MUST default to true.</p> + + <tp:rationale> + <p>If a connection manager starts supporting this property but + defaults to false, it would break all existing clients that don't + call <tp:member-ref>Download</tp:member-ref>.</p> + </tp:rationale> + </tp:docstring> + </property> + <method name="AuthorizePublication" tp:name-for-bindings="Authorize_Publication"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -1080,6 +1109,21 @@ </tp:possible-errors> </method> + <method name="Download" tp:name-for-bindings="Download"> + <tp:added version="0.UNRELEASED"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Download the contact list from the server. If + <tp:member-ref>DownloadAtConnection</tp:member-ref> is true, + Download does nothing.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + </tp:possible-errors> + </method> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 10ade57e..9782db59 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -1,6 +1,6 @@ <?xml version="1.0" ?> <node name="/Connection_Manager" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2012 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> @@ -603,7 +603,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dd>ASCII decimal integer, optionally prefixed with "-"</dd> <dt>d (double-precision floating point)</dt> <dd>ASCII decimal number</dd> - <dt>as (array of string)</dt> + <dt>as (array of string), ao (array of object path)</dt> <dd>A sequence of UTF-8 strings each followed by a semicolon, with any semicolons they contain escaped with a backslash (the "localestrings" type from the Desktop Entry Specification)</dd> @@ -626,6 +626,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ CMs with no .manager file was not explicitly required.</tp:changed> <tp:changed version="0.17.16">Prior to version 0.17.16 the serialization of string arrays (signature 'as') was not defined</tp:changed> + <tp:changed version="0.25.2">Prior to version 0.25.2 the + serialization of object-path arrays (signature 'ao') was not + defined</tp:changed> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol.xml b/spec/Protocol.xml index f779492f..6cc10aa6 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -235,7 +235,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy both be represented by any single vCard field. Arbitrary handles/identifiers as vCard fields are represented through the Connection's - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Addressing.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Addressing1</tp:dbus-ref> contact attributes.</p> <tp:rationale> diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml index 0c62e1bd..55ee71cb 100644 --- a/spec/Protocol_Interface_Addressing.xml +++ b/spec/Protocol_Interface_Addressing.xml @@ -145,9 +145,9 @@ AddressableURISchemes=tel;sip; <dt><code>msnim</code></dt> <dd>For the purposes of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing1</tp:dbus-ref>, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing1</tp:dbus-ref>, the verb part is ignored, and SHOULD be <code>add</code>; the <code>contact</code> field in the query string is used to identify the contact. @@ -155,9 +155,9 @@ AddressableURISchemes=tel;sip; <dt><code>aim</code></dt> <dd>For the purposes of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing1</tp:dbus-ref>, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing1</tp:dbus-ref>, the verb part is ignored, and SHOULD be <code>addbuddy</code>; the <code>screenname</code> field in the query string is used to identify the contact. @@ -168,9 +168,9 @@ AddressableURISchemes=tel;sip; <dt><code>ymsgr</code></dt> <dd>For the purposes of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing</tp:dbus-ref>, - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing1</tp:dbus-ref>, and - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing1</tp:dbus-ref>, the verb part is ignored, and SHOULD be <code>addfriend</code>; the query string is used to identify the contact. For example: <code>ymsgr:addfriend?julien</code>.</dd> @@ -186,7 +186,7 @@ AddressableURISchemes=tel;sip; <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given vCard address. Where possible, this SHOULD return an address that would appear in the - <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses</code> + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing1/addresses</code> attribute for a contact on a connected <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. </p> @@ -247,7 +247,7 @@ AddressableURISchemes=tel;sip; <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Attempt to normalize the given contact URI. Where possible, this SHOULD return an address that would appear in the - <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris</code> + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing1/uris</code> attribute for a contact on a connected <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. </p> diff --git a/spec/all.xml b/spec/all.xml index 7e8c8342..9e99d705 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,9 +3,9 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.25.1</tp:version> +<tp:version>0.25.2</tp:version> -<tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright> +<tp:copyright>Copyright © 2005-2012 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright> <tp:copyright>Copyright © 2006 INdT</tp:copyright> @@ -168,6 +168,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Room.xml"/> <xi:include href="Channel_Interface_Room_Config.xml"/> <xi:include href="Channel_Interface_SASL_Authentication.xml"/> + <xi:include href="Channel_Interface_Captcha_Authentication.xml"/> <xi:include href="Channel_Interface_Credentials_Storage.xml"/> <xi:include href="Channel_Interface_Securable.xml"/> <xi:include href="Channel_Interface_Service_Point.xml"/> @@ -241,6 +242,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Call_Content.xml"/> <xi:include href="Call_Content_Interface_Media.xml"/> <xi:include href="Call_Interface_Mute.xml"/> + <xi:include href="Call_Content_Interface_DTMF.xml"/> <xi:include href="Call_Content_Interface_Video_Control.xml"/> <xi:include href="Call_Content_Interface_Audio_Control.xml"/> <xi:include href="Call_Content_Media_Description.xml"/> diff --git a/spec/errors.xml b/spec/errors.xml index 30c0b44c..bd3be022 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -637,6 +637,16 @@ </tp:docstring> </tp:error> + <tp:error name="Captcha Not Supported"> + <tp:added version="0.25.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Raised if the <tp:dbus-ref + namespace="ofdT.Channel.Interface">CaptchaAuthentication1</tp:dbus-ref> + Handler either has no UI to present captchas, or it does, but wasn't + able to answer any of the captchas given.</p> + </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/generic-types.xml b/spec/generic-types.xml index 014f8ada..2676e453 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -212,4 +212,12 @@ </tp:member> </tp:mapping> + <tp:simple-type name="Language_Tag" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A language tag as defined in + <a href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">IETF BCP 47</a>, + such as "en_US". + </tp:docstring> + </tp:simple-type> + </tp:generic-types> |