Update to spec 0.22.1.

8 files changed, 256 insertions, 24 deletions

diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
index 045d41693..e1474c5ac 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -836,6 +836,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             normally be localized or suitable for display to users, and is only
             applicable when the call state is
             <tp:type>Call_State</tp:type>_Ended.</dd>
+
+          <dt>balance-required - i</dt>
+          <dd>Optionally included when a call cannot be connected because
+            there is <tp:error-ref>InsufficientBalance</tp:error-ref>,
+            indicating what the required balance would be to place this call.
+            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>
         </dl>
       </tp:docstring>
     </property>
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index fefa77a26..98789ab40 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -31,12 +31,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <p>A channel type for searching server-stored user directories. A new
         channel should be requested by a client for each search attempt, and
         closed when the search is completed or the required result has been
-        found. Channels of this type should have <tp:dbus-ref
+        found.</p>
+
+      <p>Connections that support contact search channels SHOULD have an entry
+        in <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
+          >RequestableChannelClasses</tp:dbus-ref> with the <tp:dbus-ref
+          namespace='ofdT.Channel'>ChannelType</tp:dbus-ref> fixed to this
+        interface, and no other fixed properties. That requestable
+        channel class MAY also have the Server and Limit properties in its
+        list of allowed properties, depending on the protocol.</p>
+
+      <tp:rationale>
+        <p>The requestable channel class would normally also have <tp:dbus-ref
+            namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> fixed to
+          <code>None</code>, but the initial implementation of ContactSearch
+          (in telepathy-gabble) didn't do this.</p>
+      </tp:rationale>
+
+      <p>All channels of this type should have <tp:dbus-ref
         namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
         <code>None</code> (and hence <tp:dbus-ref
         namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and
         <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>
-        <code>""</code>). Requests for channels of this type need only
+        <code>""</code>).</p>
+
+      <p>Requests for channels of this type need only
         optionally specify the <tp:member-ref>Server</tp:member-ref> property
         (if it is an allowed property in the connection's <tp:dbus-ref
         namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 2f233fa53..c8dc32804 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -486,7 +486,10 @@
           <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
           and
           <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
-          </p>
+          (One exception is that <tp:dbus-ref namespace="ofdT.Channel.Type"
+            >ContactSearch</tp:dbus-ref> channels do not have TargetHandleType
+          <code>None</code> in their requestable channel classes, for
+          historical reasons.)</p>
       </tp:docstring>
 
       <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 3683fcadf..10ade57e8 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -196,11 +196,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Get a list of the parameters which must or may be provided to the
-        <tp:member-ref>RequestConnection</tp:member-ref> method when connecting
-        to the given protocol,
-        or registering (the boolean &quot;register&quot; parameter is available,
-        and set to true).
+        Get a list of the parameters which may be specified in the
+        <tp:dbus-ref namespace='ofdT.Account'>Parameters</tp:dbus-ref> of an
+        <tp:dbus-ref namespace='ofdT'>Account</tp:dbus-ref> (or, for
+        specialised applications which do not use the account manager, passed
+        to <tp:member-ref>RequestConnection</tp:member-ref>). Some parameters
+        are mandatory, and some parameters only make sense when registering new
+        accounts with the server; see the <tp:type>Param_Spec</tp:type>
+        documentation for more details.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
@@ -323,6 +326,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref>
           method.</p>
 
+        <p><strong>Most applications should not use this method</strong>: they
+          should instead use the the <tp:dbus-ref
+          namespace='ofdT.Account'>Connection</tp:dbus-ref> property on an
+          <tp:dbus-ref namespace='ofdT'>Account</tp:dbus-ref> object obtained
+          from the <tp:dbus-ref
+          namespace='ofdT'>AccountManager</tp:dbus-ref>. This method is used
+          internally by the account manager to create connections when
+          needed.</p>
+
         <p>The parameters which must and may be provided in the parameters
         dictionary can be discovered with the
         <tp:member-ref>GetParameters</tp:member-ref> method. These
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index 123ea8be7..dbcaf816e 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -20,6 +20,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Media.StreamHandler">
 
+    <tp:docstring>
+    Handles signalling the information pertaining to a specific media stream.
+    A client should provide information to this handler as and when it is
+    available.
+    </tp:docstring>
+
     <tp:struct name="Media_Stream_Handler_Candidate"
       array-name="Media_Stream_Handler_Candidate_List">
       <tp:member type="s" name="Name"/>
@@ -533,7 +539,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
         Signal emitted when the connection manager wishes to inform the
         client of the codecs supported by the remote end.
-	If these codecs are compatible with the remote codecs, then the client
+        If these codecs are compatible with the remote codecs, then the client
         must call <tp:member-ref>SupportedCodecs</tp:member-ref>,
         otherwise call <tp:member-ref>Error</tp:member-ref>.
       </tp:docstring>
@@ -581,16 +587,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
      <arg name="Codec_ID" type="u">
         <tp:docstring>
           The payload type to use when sending events. The value 0xFFFFFFFF
-	  means to send with the already configured event type instead of using
-	  the specified one.
+          means to send with the already configured event type instead of using
+          the specified one.
         </tp:docstring>
       </arg>
       <tp:docstring>
         Request that a telephony event (as defined by RFC 4733) is transmitted
         over this stream until StopTelephonyEvent is called. This differs from
         StartTelephonyEvent in that you force the event to be transmitted
-	as a RFC 4733 named event, not as sound. You can also force a specific
-	Codec ID.
+        as a RFC 4733 named event, not as sound. You can also force a specific
+        Codec ID.
       </tp:docstring>
     </signal>
     <signal name="StartSoundTelephonyEvent"
@@ -605,7 +611,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Request that a telephony event (as defined by RFC 4733) is transmitted
         over this stream until StopTelephonyEvent is called. This differs from
         StartTelephonyEvent in that you force the event to be transmitted
-	as sound instead of as a named event.
+        as sound instead of as a named event.
       </tp:docstring>
     </signal>
     <signal name="StopTelephonyEvent"
@@ -715,11 +721,175 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:added version="0.17.3"/>
     </method>
 
-    <tp:docstring>
-    Handles signalling the information pertaining to a specific media stream.
-    A client should provide information to this handler as and when it is
-    available.
-    </tp:docstring>
+    <tp:struct name="RTCP_Feedback_Message_Properties">
+      <tp:added version="0.22.1"/>
+      <tp:member type="u" name="RTCPMinimumInterval">
+        <tp:docstring>
+          The minimum interval between two regular RTCP packets in
+          milliseconds for this content. If no special value is desired, one
+          should put MAXUINT (0xFFFFFFFF).
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="a(sss)" tp:type="RTCP_Feedback_Message[]"
+                 name="Messages">
+        <tp:docstring>
+          The RTCP feedback messages for this codec.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="RTCP_Feedback_Message"
+               array-name="RTCP_Feedback_Message_List">
+      <tp:added version="0.22.1"/>
+      <tp:docstring>
+        A struct defining an RTCP feedback message.
+      </tp:docstring>
+      <tp:member type="s" name="Type">
+        <tp:docstring>
+          Feedback type, for example "ack", "nack", or "ccm".
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Subtype">
+        <tp:docstring>
+          Feedback subtype, according to the Type, can be an empty string (""),
+          if there is no subtype.
+          For example, generic nack is Type="nack" Subtype="".
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Parameters">
+        <tp:docstring>
+          Feedback parameters as a string. Format is defined in the relevant RFC
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:mapping name="RTCP_Feedback_Message_Map">
+      <tp:added version="0.22.1"/>
+      <tp:docstring>
+        A map of codec and its feedback properties.
+      </tp:docstring>
+      <tp:member type="u" name="Codec_Identifier">
+        <tp:docstring>
+          Numeric identifier for the codec. This will be used as the
+          PT in the SDP or content description.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="(ua(sss))" tp:type="RTCP_Feedback_Message_Properties"
+                 name="Properties">
+        <tp:docstring>
+          The RTCP feedback properties for this codec.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <signal name="SetRemoteFeedbackMessages"
+            tp:name-for-bindings="Set_Remote_Feedback_Messages">
+      <tp:added version="0.22.1"/>
+      <arg name="Messages" type="a{u(ua(sss))}"
+           tp:type="RTCP_Feedback_Message_Map">
+        <tp:docstring>
+          Remote Feedback messages desired by the remote side
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Signal emitted when the connection manager wishes to inform the
+        client of the feedback messages supported by the remote end.
+        This signal is emitted before
+        <tp:member-ref>SetRemoteCodecs</tp:member-ref>. If the client
+        supports any of these messages, it must call
+        <tp:member-ref>SupportedFeedbackMessages</tp:member-ref> before calling
+        <tp:member-ref>SupportedCodecs</tp:member-ref>.
+      </tp:docstring>
+    </signal>
+
+    <method name="SupportedFeedbackMessages"
+            tp:name-for-bindings="Supported_Feedback_Messages">
+      <tp:added version="0.22.1"/>
+      <arg name="Messages" direction="in" type="a{u(ua(sss))}"
+           tp:type="RTCP_Feedback_Message_Map">
+        <tp:docstring>
+          Locally supported feedback messages.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Inform the connection manager of the supported feedback messages
+        for this session.
+        This is called a before calling
+        <tp:member-ref>SupportedCodecs</tp:member-ref>,
+        <tp:member-ref>Ready</tp:member-ref> or
+        <tp:member-ref>CodecsUpdated</tp:member-ref> to indicate the local,
+        or negotiated feedback messages.
+      </tp:docstring>
+    </method>
+
+    <tp:struct name="RTP_Header_Extension"
+      array-name="RTP_Header_Extensions_List">
+      <tp:added version="0.22.1"/>
+      <tp:docstring>
+        A struct defining a RTP Header extension
+      </tp:docstring>
+      <tp:member type="u" name="ID">
+        <tp:docstring>
+          Identifier to be negotiated
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="u" tp:type="Media_Stream_Direction"  name="Direction">
+        <tp:docstring>
+          Direction in which the Header Extension is negotiated.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="URI">
+        <tp:docstring>
+          URI defining the extension
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Parameters">
+        <tp:docstring>
+          Feedback parameters as a string. Format is defined in the relevant RFC
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <signal name="SetRemoteHeaderExtensions"
+            tp:name-for-bindings="Set_Remote_Header_Extensions">
+      <tp:added version="0.22.1"/>
+      <arg name="Header_Extensions" type="a(uuss)"
+           tp:type="RTP_Header_Extension[]">
+        <tp:docstring>
+          Header extensions desired by the remote side
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Signal emitted when the connection manager wishes to inform the
+        client of the RTP header extensions supported by the remote end.
+        This signal is emitted before
+        <tp:member-ref>SetRemoteCodecs</tp:member-ref>. If the client
+        supports any of these messages, it must call
+        <tp:member-ref>SupportedHeaderExtensions</tp:member-ref> before calling
+        <tp:member-ref>SupportedCodecs</tp:member-ref>.
+      </tp:docstring>
+    </signal>
+
+    <method name="SupportedHeaderExtensions"
+            tp:name-for-bindings="Supported_Header_Extensions">
+      <tp:added version="0.22.1"/>
+      <arg name="Header_Extensions" direction="in" type="a(uuss)"
+           tp:type="RTP_Header_Extension[]">
+        <tp:docstring>
+          Locally supported RTP header extensions.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Inform the connection manager of the supported RTP header extensions
+        for this session.
+        This is called before calling
+        <tp:member-ref>SupportedCodecs</tp:member-ref>,
+        <tp:member-ref>Ready</tp:member-ref> or
+        <tp:member-ref>CodecsUpdated</tp:member-ref> to indicate the local
+        or negotiated RTP header extensions.
+      </tp:docstring>
+    </method>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
index 5e2c9b197..e987a638d 100644
--- a/spec/Protocol.xml
+++ b/spec/Protocol.xml
@@ -99,10 +99,15 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
       access="read" type="a(susv)" tp:type="Param_Spec[]"
       tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The parameters which must or may be provided to the
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
-            >RequestConnection</tp:dbus-ref> method when connecting to the
-          given protocol.</p>
+        <p>The parameters which may be specified in the
+          <tp:dbus-ref namespace='ofdT.Account'>Parameters</tp:dbus-ref> of an
+          <tp:dbus-ref namespace='ofdT'>Account</tp:dbus-ref> (or, for
+          specialised applications which do not use the account manager, passed
+          to <tp:dbus-ref
+          namespace='ofdT.ConnectionManager'>RequestConnection</tp:dbus-ref>).
+          Some parameters are mandatory, and some parameters only make sense
+          when registering new accounts with the server; see the
+          <tp:type>Param_Spec</tp:type> documentation for more details.</p>
 
         <p>Connection managers with a <code>.manager</code> file
           (as described as part of the
diff --git a/spec/all.xml b/spec/all.xml
index a5644a90f..bf15a903e 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.22.0</tp:version>
+<tp:version>0.22.1</tp:version>
 
 <tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>
diff --git a/spec/errors.xml b/spec/errors.xml
index d63662edb..6753301f8 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -581,6 +581,21 @@
     </tp:docstring>
   </tp:error>
 
+  <tp:error name="Insufficient Balance">
+    <tp:added version="0.22.1"/>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>Raised if the user has insufficient
+        <tp:dbus-ref namespace="ofdT.Connection.Interface">Balance</tp:dbus-ref>
+        to place a call.</p>
+
+      <p>The key 'balance-required' MAY be included in
+        <tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT">CallStateDetails</tp:dbus-ref>
+        (with the same units and scale as
+        <tp:dbus-ref namespace="ofdT.Connection.Interface.Balance">AccountBalance</tp:dbus-ref>)
+        to indicate how much credit is required to make this call.</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">