Merge branch 'master' into next

Conflicts:
	README
	spec/Account_Manager.xml
	spec/Call1_Content.xml
	spec/Call1_Content_Interface_Audio_Control1.xml
	spec/Call1_Content_Interface_Media.xml
	spec/Call1_Content_Interface_Video_Control1.xml
	spec/Call1_Content_Media_Description.xml
	spec/Call1_Content_Media_Description_Interface_RTCP_Extended_Reports1.xml
	spec/Call1_Content_Media_Description_Interface_RTP_Header_Extensions1.xml
	spec/Call1_Interface_Mute.xml
	spec/Call1_Stream.xml
	spec/Call1_Stream_Endpoint.xml
	spec/Call1_Stream_Interface_Media.xml
	spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml
	spec/Channel_Interface_DTMF1.xml
	spec/Channel_Type_Call1.xml
	spec/Connection_Interface_Addressing1.xml
	spec/Connection_Manager.xml
	spec/all.xml

25 files changed, 946 insertions, 120 deletions

diff --git a/NEWS b/NEWS
index 5d63cec8..b22c856e 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,63 @@ This file contains the same edited highlights as the announcement emails.
 For full details, see the ChangeLog in tarballs, or "git log" in Git
 checkouts.
 
+telepathy-spec 0.25.3 (UNRELEASED)
+==================================
+
+...
+
+telepathy-spec 0.25.2 (2012-02-20)
+==================================
+
+The "you know what they said? Well, some of it was true" release.
+
+New stable API:
+
+• The Call1 family of interfaces (except for the Mute interface) is now
+  considered stable, with significant changes since 0.25.1:
+
+  · Content.Removed signal removed, use Call1.ContentRemoved instead
+  · Content.I.DTMF added; this supersedes everything in Channel.I.DTMF
+    except the InitialTones property
+  · Various redundant contact handles removed from Content.I.Media
+  · MediaDescription.Reject has an "in" argument, not a nonsensical "out"
+    argument
+  · Stream.I.Media no longer has Pending_Pause or Paused states
+  · The Ringing state has been renamed to Initialising to avoid confusion
+    with the Ringing flag
+  · Call1.AddContent takes an initial direction as its new last parameter
+  · Call_Flag_Locally_Muted has been removed and the other Call_Flags
+    have been renumbered
+  · Call_Member_Flag_Ringing has been removed and the other Call_Member_Flags
+    have been renumbered
+  · The destination of a forwarded call is published in the CallStateDetails,
+    rather than abusing the Actor member of CallStateReason
+
+• Connection.I.Addressing1 is now stable, and identical to
+  Connection.I.Addressing.DRAFT in 0.25.1 except for its name
+
+• Account.Supersedes has been added
+
+• Connection.I.ContactList.DownloadAtConnection has been added, together with
+  the Download method
+
+• A serialization has been defined for arrays of object path in .manager
+  files (and by extension, anything sharing that format)
+
+Clarifications:
+
+• Account.Service should also be used for IRC networks
+
+• Channel.I.DTMF.InitialTones should only be used in conjunction with
+  InitialAudio=TRUE
+
+• The policy for versioned interfaces is now documented
+
+Changes to experimental API:
+
+• Channel.I.Addressing1 is the new name for Channel.I.Addressing.DRAFT,
+  but is still considered experimental
+
 telepathy-spec 0.25.1 (2011-11-23)
 ==================================
 
diff --git a/spec/Account.xml b/spec/Account.xml
index fa9f4777..b700b8fa 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
@@ -278,6 +278,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="imt1.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 c6a7e8a8..7a281951 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -145,7 +145,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             <tp:dbus-ref
               namespace="im.telepathy1.Account">ConnectAutomatically</tp:dbus-ref>,
             <tp:dbus-ref
-              namespace="im.telepathy1.Account">RequestedPresence</tp:dbus-ref>
+              namespace="im.telepathy1.Account">RequestedPresence</tp:dbus-ref>,
+            <tp:dbus-ref
+              namespace="imt1.Account">Supersedes</tp:dbus-ref>
             and
             <tp:dbus-ref
               namespace="im.telepathy1.Account.Interface.Avatar1">Avatar</tp:dbus-ref>.
diff --git a/spec/Call1_Content.xml b/spec/Call1_Content.xml
index 52b75bf6..1926e491 100644
--- a/spec/Call1_Content.xml
+++ b/spec/Call1_Content.xml
@@ -20,9 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Content"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.19.0">(draft 1)</tp:added>
+  <interface name="im.telepathy1.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
diff --git a/spec/Call1_Content_Interface_Audio_Control1.xml b/spec/Call1_Content_Interface_Audio_Control1.xml
index 2531fdb1..c7f441cf 100644
--- a/spec/Call1_Content_Interface_Audio_Control1.xml
+++ b/spec/Call1_Content_Interface_Audio_Control1.xml
@@ -19,9 +19,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Content.Interface.AudioControl1"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.25.1">(draft 1)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.Interface.AudioControl1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Content.Interface.Media"/>
     <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
 
diff --git a/spec/Call1_Content_Interface_DTMF1.xml b/spec/Call1_Content_Interface_DTMF1.xml
new file mode 100644
index 00000000..594ecf31
--- /dev/null
+++ b/spec/Call1_Content_Interface_DTMF1.xml
@@ -0,0 +1,229 @@
+<?xml version="1.0" ?>
+<node name="/Call1_Content_Interface_DTMF1" 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="im.telepathy1.Call1.Content.Interface.DTMF1">
+    <tp:requires interface="im.telepathy1.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="im.telepathy1.Error.NetworkError" />
+        <tp:error name="im.telepathy1.Error.InvalidArgument">
+          <tp:docstring>
+	    The event id was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.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="im.telepathy1.Error.NetworkError" />
+        <tp:error name="im.telepathy1.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="im.telepathy1.Error.NetworkError" />
+        <tp:error name="im.telepathy1.Error.InvalidArgument">
+          <tp:docstring>
+            The supplied Tones string was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.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/Call1_Content_Interface_Media.xml b/spec/Call1_Content_Interface_Media.xml
index 1b959e8d..4b2f30ae 100644
--- a/spec/Call1_Content_Interface_Media.xml
+++ b/spec/Call1_Content_Interface_Media.xml
@@ -20,10 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface
-      name="im.telepathy1.Call1.Content.Interface.Media"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.23.4">(draft 2)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.Interface.Media">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Content"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -327,11 +325,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>
diff --git a/spec/Call1_Content_Interface_Video_Control1.xml b/spec/Call1_Content_Interface_Video_Control1.xml
index 8545a1a5..130ec829 100644
--- a/spec/Call1_Content_Interface_Video_Control1.xml
+++ b/spec/Call1_Content_Interface_Video_Control1.xml
@@ -19,9 +19,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Content.Interface.VideoControl1"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.21.10">(draft 1)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.Interface.VideoControl1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Content.Interface.Media"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Call1_Content_Media_Description.xml b/spec/Call1_Content_Media_Description.xml
index e29631db..ae6e9d50 100644
--- a/spec/Call1_Content_Media_Description.xml
+++ b/spec/Call1_Content_Media_Description.xml
@@ -20,9 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Content.MediaDescription"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.23.4">(draft 1)</tp:added>
+  <interface name="im.telepathy1.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
diff --git a/spec/Call1_Content_Media_Description_Interface_RTCP_Extended_Reports1.xml b/spec/Call1_Content_Media_Description_Interface_RTCP_Extended_Reports1.xml
index b1ee89bd..bd6c7f15 100644
--- a/spec/Call1_Content_Media_Description_Interface_RTCP_Extended_Reports1.xml
+++ b/spec/Call1_Content_Media_Description_Interface_RTCP_Extended_Reports1.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="im.telepathy1.Call1.Content.MediaDescription.Interface.RTCPExtendedReports1"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.23.4">(draft version, not API-stable)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.MediaDescription.Interface.RTCPExtendedReports1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires
     interface="im.telepathy1.Call1.Content.MediaDescription"/>
 
diff --git a/spec/Call1_Content_Media_Description_Interface_RTCP_Feedback1.xml b/spec/Call1_Content_Media_Description_Interface_RTCP_Feedback1.xml
index 9c32bbdb..e9dbf226 100644
--- a/spec/Call1_Content_Media_Description_Interface_RTCP_Feedback1.xml
+++ b/spec/Call1_Content_Media_Description_Interface_RTCP_Feedback1.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="im.telepathy1.Call1.Content.MediaDescription.Interface.RTCPFeedback1"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.23.4">(draft version, not API-stable)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.MediaDescription.Interface.RTCPFeedback1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Content.MediaDescription"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Call1_Content_Media_Description_Interface_RTP_Header_Extensions1.xml b/spec/Call1_Content_Media_Description_Interface_RTP_Header_Extensions1.xml
index 62f8936f..4f50eb7a 100644
--- a/spec/Call1_Content_Media_Description_Interface_RTP_Header_Extensions1.xml
+++ b/spec/Call1_Content_Media_Description_Interface_RTP_Header_Extensions1.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="im.telepathy1.Call1.Content.MediaDescription.Interface.RTPHeaderExtensions1"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.23.4">(draft version, not API-stable)</tp:added>
+  <interface name="im.telepathy1.Call1.Content.MediaDescription.Interface.RTPHeaderExtensions1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Content.MediaDescription"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Call1_Interface_Mute.xml b/spec/Call1_Interface_Mute.xml
index d8b0c058..d1a7766d 100644
--- a/spec/Call1_Interface_Mute.xml
+++ b/spec/Call1_Interface_Mute.xml
@@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   </tp:license>
 
   <interface name="im.telepathy1.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="im.telepathy1.Channel.Type.Call1"/>
       <tp:requires interface="im.telepathy1.Call1.Content"/>
diff --git a/spec/Call1_Stream.xml b/spec/Call1_Stream.xml
index 635427a1..7751c7b8 100644
--- a/spec/Call1_Stream.xml
+++ b/spec/Call1_Stream.xml
@@ -20,9 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Stream"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.19.0">(draft 1)</tp:added>
+  <interface name="im.telepathy1.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/Call1_Stream_Endpoint.xml b/spec/Call1_Stream_Endpoint.xml
index 3708d9e7..8c705b8f 100644
--- a/spec/Call1_Stream_Endpoint.xml
+++ b/spec/Call1_Stream_Endpoint.xml
@@ -20,9 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Stream.Endpoint"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.19.0">(draft 1)</tp:added>
+  <interface name="im.telepathy1.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
diff --git a/spec/Call1_Stream_Interface_Media.xml b/spec/Call1_Stream_Interface_Media.xml
index 048fb59d..09d1e0c4 100644
--- a/spec/Call1_Stream_Interface_Media.xml
+++ b/spec/Call1_Stream_Interface_Media.xml
@@ -20,9 +20,8 @@
       02110-1301, USA.</p>
   </tp:license>
 
-  <interface name="im.telepathy1.Call1.Stream.Interface.Media"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.19.0">(draft 1)</tp:added>
+  <interface name="im.telepathy1.Call1.Stream.Interface.Media">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
     <tp:requires interface="im.telepathy1.Call1.Stream"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -80,18 +79,6 @@
           data, and everything is going swimmingly.
         </tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="Pending_Mute" value="4">
-        <tp:docstring>
-          The streaming implementation has been told to mute sending,
-          but it has not yet indicated that it has done so.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Muted" value="5">
-        <tp:docstring>
-          The streaming implementation has successfully muted sending,
-          and the local user's privacy is protected.
-        </tp:docstring>
-      </tp:enumvalue>
     </tp:enum>
 
     <property name="SendingState" tp:name-for-bindings="Sending_State"
@@ -102,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>.
@@ -427,6 +414,16 @@
           and then set the lowest priority candidate as the Raw UDP candidate.
         </tp:rationale>
       </tp:docstring>
+
+      <tp:possible-errors>
+        <tp:error name="im.telepathy1.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_Interface_Captcha_Authentication1.xml b/spec/Channel_Interface_Captcha_Authentication1.xml
new file mode 100644
index 00000000..bba0cb2c
--- /dev/null
+++ b/spec/Channel_Interface_Captcha_Authentication1.xml
@@ -0,0 +1,505 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Captcha_Authentication1"
+      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="im.telepathy1.Channel.Interface.CaptchaAuthentication1">
+    <tp:added version="0.25.2">(version 1)</tp:added>
+    <tp:requires interface="im.telepathy1.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="imt1.Channel.Type">ServerAuthentication1</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="imt1.Channel.Type"
+        >ServerAuthentication1</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="imt1">ChannelDispatcher</tp:dbus-ref>,
+        only the channel's <tp:dbus-ref
+          namespace="imt1.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="imt1.Channel.Type">ServerAuthentication1</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="imt1">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="imt1">Connection.ConnectionError</tp:dbus-ref>.</p>
+
+        <p>If this interface appears on a <tp:dbus-ref
+            namespace="imt1.Channel.Type">ServerAuthentication1</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="imt1">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="im.telepathy1.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="im.telepathy1.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="im.telepathy1.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="im.telepathy1.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="im.telepathy1.Error.NotAvailable">
+          <tp:docstring>
+            The state is not in Local_Pending.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.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="imt1.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="im.telepathy1.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="imt1.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="imt1.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="imt1.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="imt1.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="imt1.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="imt1.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="imt1.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_DTMF1.xml b/spec/Channel_Interface_DTMF1.xml
index b0da4c80..0222dd7a 100644
--- a/spec/Channel_Interface_DTMF1.xml
+++ b/spec/Channel_Interface_DTMF1.xml
@@ -20,11 +20,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </tp:license>
   <interface name="im.telepathy1.Channel.Interface.DTMF1">
     <tp:requires interface="im.telepathy1.Channel.Type.Call1"/>
+
+    <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 Stream_IDs in this
-      interface should now be ignored by CMs. This is primarily to allow this
-      interface to be used with <tp:dbus-ref
-      namespace='imt1.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
@@ -206,7 +209,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,
@@ -214,6 +217,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_Call1.xml b/spec/Channel_Type_Call1.xml
index db9f2f87..548b79ce 100644
--- a/spec/Channel_Type_Call1.xml
+++ b/spec/Channel_Type_Call1.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="im.telepathy1.Channel.Type.Call1"
-      tp:causes-havoc="experimental">
-    <tp:added version="0.19.0">(draft 1)</tp:added>
+  <interface name="im.telepathy1.Channel.Type.Call1">
+    <tp:added version="0.25.2">(as stable API)</tp:added>
 
     <tp:requires interface="im.telepathy1.Channel"/>
     <tp:requires
@@ -512,6 +511,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
@@ -741,25 +746,7 @@ 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="imt1.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="imt1.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
@@ -770,7 +757,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </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
@@ -780,7 +767,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </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
@@ -790,7 +777,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
@@ -853,6 +840,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="imt1.Connection.Interface.Balance1">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>
@@ -931,9 +929,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>
 
@@ -1225,21 +1226,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_Addressing1.xml b/spec/Connection_Interface_Addressing1.xml
index 6bec6d66..8e359f66 100644
--- a/spec/Connection_Interface_Addressing1.xml
+++ b/spec/Connection_Interface_Addressing1.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" ?>
 <node name="/Connection_Interface_Addressing1" 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,14 +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="im.telepathy1.Connection.Interface.Addressing1"
-             tp:causes-havoc="experimental">
+  <interface name="im.telepathy1.Connection.Interface.Addressing1">
     <tp:requires interface="im.telepathy1.Connection"/>
     <tp:requires interface="im.telepathy1.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:changed version="0.25.UNRELEASED">Replaced DRAFT with a version number
-      (still keeping the causes-havoc annotation)</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>
@@ -189,11 +185,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_List1.xml b/spec/Connection_Interface_Contact_List1.xml
index 895bbbbc..72ace7cf 100644
--- a/spec/Connection_Interface_Contact_List1.xml
+++ b/spec/Connection_Interface_Contact_List1.xml
@@ -800,7 +800,7 @@
     <property name="DownloadAtConnection" type="b" access="read"
       tp:name-for-bindings="Download_At_Connection"
       tp:is-connection-parameter='yes'>
-      <tp:added version="0.UNRELEASED"/>
+      <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
@@ -1066,7 +1066,7 @@
     </method>
 
     <method name="Download" tp:name-for-bindings="Download">
-      <tp:added version="0.UNRELEASED"/>
+      <tp:added version="0.25.2"/>
       <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,
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 2b8f5240..abcdae7d 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">
@@ -562,7 +562,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>
@@ -585,6 +585,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>
     <tp:changed version="0.UNRELEASED">GetParameters and ListProtocols
       have been removed in favour of the
       <tp:member-ref>Protocols</tp:member-ref> property.</tp:changed>
diff --git a/spec/all.xml b/spec/all.xml
index f1147267..a792a09f 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.1</tp:version>
+<tp:version>0.25.2.1</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>
 
@@ -153,6 +153,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
    <xi:include href="Channel_Interface_Addressing1.xml"/>
    <xi:include href="Channel_Interface_Anonymity1.xml"/>
+   <xi:include href="Channel_Interface_Captcha_Authentication1.xml"/>
    <xi:include href="Channel_Interface_Destroyable1.xml"/>
    <xi:include href="Channel_Interface_File_Transfer_Metadata1.xml"/>
    <xi:include href="Channel_Interface_Group1.xml"/>
@@ -219,6 +220,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Call1_Content.xml"/>
    <xi:include href="Call1_Content_Interface_Media.xml"/>
    <xi:include href="Call1_Interface_Mute.xml"/>
+   <xi:include href="Call1_Content_Interface_DTMF1.xml"/>
    <xi:include href="Call1_Content_Interface_Video_Control1.xml"/>
    <xi:include href="Call1_Content_Interface_Audio_Control1.xml"/>
    <xi:include href="Call1_Content_Media_Description.xml"/>
diff --git a/spec/errors.xml b/spec/errors.xml
index facfa481..747dbe88 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -638,6 +638,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="imt1.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 11ef6667..4e68f318 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>