Update to spec 0.21.7

- Protocol.AuthenticationTypes
- Chan.I.SMS.SMSChannel and its change notification

5 files changed, 170 insertions, 20 deletions

diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index d773411eb..62e83846a 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -1005,7 +1005,12 @@ USA.</p>
       <arg direction="in" type="aa{sv}" tp:type="Message_Part[]"
         name="Message">
         <tp:docstring>
-          The message content, including any attachments or alternatives
+          The message content, including any attachments or alternatives.
+          This MUST NOT include the following headers, or any others that
+          do not make sense for a client to specify:
+          <code>message-sender</code>, <code>message-sender-id</code>,
+          <code>message-sent</code>, <code>message-received</code>,
+          <code>pending-message-id</code>.
         </tp:docstring>
       </arg>
       <arg direction="in" name="Flags" type="u"
@@ -1115,6 +1120,14 @@ USA.</p>
             part to generate a <tt>text/plain</tt> alternative which is also
             included in this signal argument.</p>
 
+          <p>The connection manager SHOULD include the
+            <code>message-sender</code>, <code>message-sender-id</code> and
+            <code>message-sent</code> headers in the representation of the
+            message that is signalled here. If the channel has
+            channel-specific handles, the <code>message-sender</code> and
+            <code>message-sender-id</code> SHOULD reflect the sender that
+            other contacts will see.</p>
+
           <p>If the connection manager can predict that the message will be
             altered during transmission, this argument SHOULD reflect what
             other contacts will receive, rather than being a copy of the
diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml
index b0dce6647..4cfe3f2f8 100644
--- a/spec/Channel_Interface_SMS.xml
+++ b/spec/Channel_Interface_SMS.xml
@@ -27,9 +27,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       documentation tidied up.</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface contains SMS-specific properties for text channels.
-        This currently only includes whether the SMSes received on the channel
-        should be displayed immediately to the user, without prompting.</p>
+      <p>This interface contains SMS-specific properties for text
+        channels.</p>
+
+      <p>The presence of this interface on a channel does not imply that
+        messages will be delivered via SMS.</p>
+
+      <p>This interface MAY appear in the
+        <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property
+        of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be
+        immutable and false. It SHOULD appear on channels where
+        <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and
+        also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is
+        mutable (i.e. channels that might fall back to sending SMS at any
+        time, such as on MSN).</p>
 
       <h4>Handler filters</h4>
 
@@ -51,7 +62,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     </tp:docstring>
 
     <property name="Flash" tp:name-for-bindings="Flash"
-      type="b" access="read" >
+      type="b" access="read" tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>If <code>True</code>, then this channel is exclusively for
           receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref
@@ -89,5 +100,80 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:rationale>
       </tp:docstring>
     </property>
+
+    <property name="SMSChannel"
+              tp:name-for-bindings="SMS_Channel"
+              type="b"
+              access="read" tp:requestable="yes" tp:immutable="sometimes">
+      <tp:added version="0.21.7"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If TRUE, messages sent and received on this channel are transmitted
+          via SMS.</p>
+
+        <p>If this property is included in the channel request, the
+          Connection Manager MUST return an appropriate channel (i.e. if TRUE
+          the channel must be for SMSes, if FALSE it must not), or else fail
+          to provide the requested channel with the
+          <tp:error-ref>NotCapable</tp:error-ref>
+          error.</p>
+
+        <p>For example, to explicitly request an SMS channel to a contact.
+          You might construct a channel request like:</p>
+
+        <blockquote><pre>{
+  Channel.Type: Channel.Type.Text,
+  Channel.TargetHandleType: Handle_Type_Contact,
+  Channel.TargetID: escher.cat,
+  Channel.Interface.SMS.SMSChannel: True,
+}</pre></blockquote>
+
+        <tp:rationale>
+          Some protocols allow us to send SMSes to a remote contact, without
+          knowing the phone number to which those SMSes will be sent. This
+          provides a mechanism to request such channels.
+        </tp:rationale>
+
+        <p>If this property is not included in the channel request, the
+          Connection Manager MAY return an SMS channel if that is the most
+          appropriate medium (i.e. if the channel target is a phone
+          number).</p>
+
+        <tp:rationale>
+          To some types of identifiers (i.e. phone numbers) it only makes
+          sense to return an SMS channel, this is what happens currently with
+          telepathy-ring. We don't want to break this behaviour when we are
+          not explicit about the type of channel we want. Alternatively, for
+          protocols where there is an SMS fallback for IM messages, it's
+          possible that we don't care what sort of channel we get, and simply
+          want notification of the transport.
+        </tp:rationale>
+
+        <p>Some protocols have a fallback to deliver IM messages via SMS.
+          On these protocols, the Connection Manager SHOULD set the property
+          value as appropriate, and notify its change with
+          <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p>
+
+        <tp:rationale>
+          Protocols such as MSN can fall back to delivering IM messages via
+          SMS. Where possible we want clients to be able to inform the user
+          that their messages are going to be redirected to the remote
+          contact's phone.
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <signal name="SMSChannelChanged"
+            tp:name-for-bindings="SMS_Channel_Changed">
+      <tp:added version="0.21.7"/>
+      <arg name="SMSChannel" type="b">
+        <tp:docstring>
+          The new value for <tp:member-ref>SMSChannel</tp:member-ref>.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        This signal indicates a change in the
+        <tp:member-ref>SMSChannel</tp:member-ref> property.
+      </tp:docstring>
+    </signal>
   </interface>
 </node>
diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml
index 9a92fa047..31343de68 100644
--- a/spec/Connection_Interface_Communication_Policy.xml
+++ b/spec/Connection_Interface_Communication_Policy.xml
@@ -146,13 +146,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:rationale>
       </tp:docstring>
       <tp:member type="as" tp:type="DBus_Interface[]"
-        name="Chanel_Types">
+        name="Channel_Types">
         <tp:docstring>
           A list of channel interfaces that support these policies.
         </tp:docstring>
       </tp:member>
       <tp:member type="au" tp:type="Access_Control_Type[]"
-        name="Supported Policies">
+        name="Supported_Policies">
         <tp:docstring>
           A list of supported policies.
         </tp:docstring>
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
index e37fe224d..5e2c9b197 100644
--- a/spec/Protocol.xml
+++ b/spec/Protocol.xml
@@ -65,6 +65,7 @@ RequestableChannelClasses=text;
 VCardField=x-example
 EnglishName=Example
 Icon=im-example
+AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication;
 
 [text]
 org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
@@ -74,11 +75,12 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
     </tp:docstring>
 
     <property name="Interfaces" tp:name-for-bindings="Interfaces"
-      access="read" type="as" tp:type="DBus_Interface[]">
+      access="read" type="as" tp:type="DBus_Interface[]"
+      tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A list of interfaces supported by this Protocol object.</p>
 
-        <p>This property is immutable, and should not be confused with
+        <p>This property should not be confused with
           <tp:member-ref>ConnectionInterfaces</tp:member-ref>,
           which refers to the interfaces of <em>connections</em> to this
           protocol.</p>
@@ -94,12 +96,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
     </property>
 
     <property name="Parameters" tp:name-for-bindings="Parameters"
-      access="read" type="a(susv)" tp:type="Param_Spec[]">
+      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. This property is immutable.</p>
+          given protocol.</p>
 
         <p>Connection managers with a <code>.manager</code> file
           (as described as part of the
@@ -115,7 +118,8 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
 
     <property name="ConnectionInterfaces"
       tp:name-for-bindings="Connection_Interfaces"
-      access="read" type="as" tp:type="DBus_Interface[]">
+      access="read" type="as" tp:type="DBus_Interface[]"
+      tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A list of interface names which might be in the
           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection"
@@ -125,7 +129,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
           will have all, some or none of these interfaces depends on server
           capabilities.</p>
 
-        <p>This property is immutable, and should not be confused with
+        <p>This property should not be confused with
           <tp:member-ref>Interfaces</tp:member-ref>.</p>
 
         <p>Connection managers with a <code>.manager</code> file
@@ -138,7 +142,8 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
 
     <property name="RequestableChannelClasses"
       tp:name-for-bindings="Requestable_Channel_Classes"
-      access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+      access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
+      tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A list of channel classes which might be requestable from a
           <tp:dbus-ref namespace="org.freedesktop.Telepathy"
@@ -152,8 +157,6 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
           similarly, individual contacts are not guaranteed to support
           all of these channel classes.</p>
 
-        <p>This property is immutable.</p>
-
         <p>Connection managers with a <code>.manager</code> file
           MUST cache this property in the protocol's section of the
           <code>.manager</code> file, using the key
@@ -206,7 +209,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
     </property>
 
     <property name="VCardField" tp:name-for-bindings="VCard_Field"
-      access="read" type="s">
+      access="read" type="s" tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The name of the most common vCard field used for this protocol's
           contact identifiers, normalized to lower case, or the empty string
@@ -251,7 +254,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
     </property>
 
     <property name="EnglishName" tp:name-for-bindings="English_Name"
-      access="read" type="s">
+      access="read" type="s" tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The name of the protocol in a form suitable for display to users,
           such as "AIM" or "Yahoo!", or the empty string if none is
@@ -285,7 +288,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
     </property>
 
     <property name="Icon" tp:name-for-bindings="Icon"
-      access="read" type="s">
+      access="read" type="s" tp:immutable="yes">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The name of an icon in the system's icon theme, such as "im-msn", or
           the empty string.</p>
@@ -429,6 +432,54 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy
       </tp:possible-errors>
     </method>
 
+    <property name="AuthenticationTypes"
+      tp:name-for-bindings="Authentication_Types" access="read" type="as"
+      tp:type="DBus_Interface[]" tp:immutable="yes">
+      <tp:added version="0.21.7"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A list of D-Bus interfaces which provide information as to
+          what kind of authentication channels can possibly appear
+          before the connection reaches the CONNECTED state.</p>
+
+        <p>These can either be channel types, or where the channel
+          type isn't enough information to be useful, interfaces
+          indicating a specific use of a channel type. For example,
+          <tp:dbus-ref namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref>
+          channels are obviously about TLS certificates so the channel
+          type would appear in this list. However, a
+          <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+          channel type alone does not explain enough about the authentication type
+          in use as it is merely a base for the channel interfaces that appear in
+          said channels. In this case, CMs should use the value of the
+          <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>
+          property in this list.</p>
+
+        <p>For example, if a protocol's
+          <tp:member-ref>AuthenticationTypes</tp:member-ref> contains
+          two values:</p>
+
+        <blockquote>
+          <pre>
+[ ...<tp:dbus-ref namespace="ofdT">Channel.Type.ServerTLSConnection</tp:dbus-ref>,
+  ...<tp:dbus-ref namespace="ofdT">Channel.Interface.SASLAuthentication</tp:dbus-ref> ]</pre></blockquote>
+
+        <p>This tells a client that before the connection status
+          reached CONNECTED, a <tp:dbus-ref
+          namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref>
+          could appear carrying a TLS certificate. It also tells the
+          client that before the connection status reaches CONNECTED, a
+          <tp:dbus-ref
+          namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+          channel could also appear, where <tp:dbus-ref
+          namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>=<tp:dbus-ref
+          namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>. A
+          hypothetical future Channel.Interface.Captcha interface would
+          also appear in this list if the CM might require the user
+          solve a captcha before connecting.</p>
+
+      </tp:docstring>
+    </property>
+
  </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 94f0a34ff..61a97c795 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.21.6</tp:version>
+<tp:version>0.21.7</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>