Update spec to 0.19.2

15 files changed, 410 insertions, 139 deletions

diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml
index 1d5e891df..3e585b49a 100644
--- a/spec/Call_Content.xml
+++ b/spec/Call_Content.xml
@@ -33,6 +33,20 @@
 
     </tp:docstring>
 
+    <method name="Remove" tp:name-for-bindings="Remove">
+      <tp:docstring>Remove the content from the call.</tp:docstring>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            Raised when a Call doesn't support removing contents (e.g. a Google Talk video call)
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
     <property name="Name" tp:name-for-bindings="Name" type="s" access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The name of the content.
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 223a612d0..0fedf6896 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -355,7 +355,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       access="read" tp:name-for-bindings="Initiator_Handle">
       <tp:added version="0.17.13">(as stable API)</tp:added>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The contact who initiated the channel. For channels requested by the
+        <p>The contact who initiated the channel; for instance, the contact
+          who invited the local user to a chatroom, or the contact who
+          initiated a call.</p>
+
+        <p>This does <em>not</em> necessarily represent the contact who
+          created the underlying protocol-level construct. For instance, if
+          Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
+          to join it, then Simon will see Will as the InitiatorHandle of the
+          channel representing the chatroom.</p>
+
+        <tp:rationale>
+          <p>The room creator is generally a less useful piece of information
+            than the inviter, is less likely to be available at invitation
+            time (i.e. can't necessarily be an immutable property), and is
+            less likely to be available at all. The creator of a chatroom
+            is not currently available via Telepathy; if added in future, it
+            is likely to be made available as a property on the Chatroom
+            interface (<a
+              href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
+        </tp:rationale>
+
+        <p>For channels requested by the
           local user, this MUST be the value of
           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
           at the time the channel was created (i.e. not a channel-specific
diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
index af3e627b9..2441a7d9e 100644
--- a/spec/Channel_Interface_Conference.xml
+++ b/spec/Channel_Interface_Conference.xml
@@ -61,7 +61,7 @@
           which returns a Conference channel.</p>
 
         <p>Either of the XMPP cases could work for Call channels, to
-          upgrade from 1-1 Jingle to multi-user Muji. Any of the XMPP cases
+          upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases
           could in principle work for link-local XMPP (XEP-0174).</p>
 
         <p>The underlying switchboard representing an MSN 1-1 conversation C1
@@ -279,9 +279,6 @@
             someone else to participate.</p>
         </tp:rationale>
 
-        <p>At most one of InitialInviteeHandles and InitialInviteeIDs may
-          appear in each request.</p>
-
         <p>If the local user was not the initiator of this channel, the
           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
             >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
@@ -289,6 +286,36 @@
           (if that information is known).</p>
 
         <p>This property is immutable.</p>
+
+        <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be
+          combined in a single request.</p>
+
+        <tp:rationale>
+          <p>For example, if you have a 1-1 channel C1 with Rob, and you want
+            to invite Sjoerd to join the discussion, you can do so by
+            requesting a channel with InitialChannels=[C1] and
+            InitialInviteeHandles=[sjoerd],
+            or InitialChannels=[C1] and
+            InitialInviteeIDs=["sjoerd@example.com"].</p>
+        </tp:rationale>
+
+        <p>If a request includes some combination of InitialInviteeHandles,
+          InitialInviteeIDs and InitialChannels, then the value of
+          InitialInviteeHandles on the resulting channel SHOULD be the union of
+          the handles from InitialInviteeHandles, the handles corresponding
+          to the InitialInviteeIDs, and the target handles of the
+          InitialChannels, with any duplicate handles removed. Because this
+          property is immutable, its value SHOULD be computed before the
+          channel is announced via the NewChannels signal.</p>
+
+        <tp:rationale>
+          <p>This simplifies identification of new channels in clients - they
+            only have to look at one of the properties, not both. For example,
+            after either of the requests mentioned above, the NewChannels
+            signal would announce the channel with InitialChannels=[C1],
+            InitialInviteeHandles=[rob, sjoerd], and
+            InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
+        </tp:rationale>
       </tp:docstring>
     </property>
 
@@ -299,16 +326,17 @@
         <p>A list of additional contacts invited to this conference when it
           was created.</p>
 
-        <p>This property SHOULD be requestable, as an alternative to
-          <tp:member-ref>InitialInviteeHandles</tp:member-ref>. Its semantics
-          are the same, except that it takes a list of the string
-          representations of contact handles.</p>
-
-        <p>At most one of InitialInviteeHandles and InitialInviteeIDs may
-          appear in each request.</p>
+        <p>This property SHOULD be requestable as an alternative to, or
+          combined with, <tp:member-ref>InitialInviteeHandles</tp:member-ref>.
+          Its semantics are the same, except that it takes a list of the
+          string representations of contact handles; invitations are sent to
+          any contact present in either or both of these properties.</p>
 
         <p>When a channel is created, the values of InitialInviteeHandles and
-          InitialInviteeIDs MUST correspond to each other.</p>
+          InitialInviteeIDs MUST correspond to each other. In particular, this
+          means that the value of InitialInviteeIDs will include the TargetID
+          of each channel in InitialChannels, and the ID corresponding to each
+          handle in InitialInviteeHandles.</p>
 
         <p>This property is immutable.</p>
       </tp:docstring>
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 004df5b8c..242c95284 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -152,39 +152,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
     </tp:property>
 
-    <tp:handler-capability-token name="gtalk-p2p">
+    <tp:hct name="gtalk-p2p">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
           property is <code>gtalk-p2p</code>.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="ice-udp">
+    <tp:hct name="ice-udp">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
           property is <code>ice-udp</code>.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="wlm-8.5">
+    <tp:hct name="wlm-8.5">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
           namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
           property is <code>wlm-8.5</code>.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="wlm-2009">
+    <tp:hct name="wlm-2009">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
           property is <code>wlm-2009</code>.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="video/h264" is-family="yes">
+    <tp:hct name="video/h264" is-family="yes">
       <tp:docstring>
         <p>The client supports media streaming with H264 (etc.).</p>
 
@@ -228,7 +228,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             known to the gatewaying process.</p>
         </tp:rationale>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
   </interface>
 </node>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index c668067d7..566e1166d 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -185,7 +185,7 @@ USA.</p>
           appears in isolation - messages are represented by a list of
           <tp:type>Message_Part</tp:type> mappings.</p>
 
-        <p>An example of how a message might
+        <p>An example of how a rich-text message, with an embedded image, might
           look, in a Python-like syntax:</p>
 
           <pre>
@@ -213,8 +213,26 @@ USA.</p>
     'size': 101000,
     'needs-retrieval': True,
   },
-]
-          </pre>
+]</pre>
+
+        <p>An example of how a non-text message — in particular, a vCard sent
+          via SMS as implemented by telepathy-ring on Nokia's Maemo 5 —
+          looks:</p>
+
+        <pre>
+[
+  {
+    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+    'message-sender': 42,
+    'message-sent': 1210067943,
+    'message-received': 1210067947,
+    'message-type': 0,              # = Channel_Text_Message_Type_Normal
+    'pending-message-id': 437,
+  },
+  { 'content-type': 'text/x-vcard',
+    'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
+  },
+]</pre>
 
         <div>
           <p>The first part of the message contains "headers" which refer
@@ -247,10 +265,40 @@ USA.</p>
 
           <dl>
             <dt>message-token (s)</dt>
-            <dd>An opaque, globally-unique identifier for the entire message.
-              This MAY be treated as if it were a MIME Message-ID, e.g. for
-              the mid: and cid: URI schemes. If omitted, there is no suitable
-              token.</dd>
+            <dd>
+              <p>An opaque, globally-unique identifier for the entire message.
+                This MAY be treated as if it were a MIME Message-ID, e.g. for
+                the mid: and cid: URI schemes. If omitted, there is no suitable
+                token; the protocol-token key SHOULD be provided if the protocol
+                identifies messages in some less unique way.</p>
+            </dd>
+
+            <dt>protocol-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>
+            <dd>
+              <p>An opaque token for the entire message, with whatever uniqueness
+                guarantee is provided by the underlying protocol. As described
+                for the Protocol_Message_Token type, this token is <em>not</em>
+                guaranteed to be unique between contacts, or even within the
+                scope of a Channel.</p>
+
+              <tp:rationale>
+                <p>In practice, in most protocols there is no token with the
+                  uniqueness guarantees demanded for message-token; the
+                  definition of message-token was inappropriate, but must now
+                  be preserved for the benefit of clients that rely on it, at
+                  least until Telepathy breaks backwards compatibility.</p>
+              </tp:rationale>
+
+              <p>The message-token and protocol-token SHOULD NOT both be present;
+                clients requiring an identifier with the semantics of the
+                protocol-token SHOULD look for the message-token first, falling
+                back to the protocol-token.</p>
+
+              <tp:rationale>
+                <p>This is for compatibility with CMs older than the
+                  protocol-token key.</p>
+              </tp:rationale>
+            </dd>
 
             <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt>
             <dd>The time the message was sent (if unavailable, the time
@@ -426,7 +474,33 @@ USA.</p>
                 There's no point in providing the size if you're already
                 providing all the content.
               </tp:rationale>
-              </dd>
+            </dd>
+
+            <dt>thumbnail (b)</dt>
+            <dd>
+              <p>This part is a thumbnail. To represent an image together with
+                its thumbnail in a single message, there should be one part for
+                the full image followed by a part for the thumbnail (following
+                the “more complete versions first” requirement), with the same
+                'alternative' value. For example:</p>
+
+              <pre>
+[ ... ,
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg',
+    'size': 150000,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  { 'alternative': 'catphoto',
+    'content-type': 'image/jpeg'
+    'size': 1024,
+    'thumbnail': True,
+    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+  },
+  ...
+]
+              </pre>
+            </dd>
 
             <dt>needs-retrieval (b)</dt>
             <dd>If false or omitted, the connection
@@ -504,7 +578,7 @@ USA.</p>
             <dd>The status of the message. All delivery reports MUST contain
               this key in the first Message_Part.</dd>
 
-            <dt>delivery-token (s - Sent_Message_Token)</dt>
+            <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>
 
             <dd>
               <p>An identifier for the message to which this delivery report
@@ -740,22 +814,27 @@ USA.</p>
       </tp:member>
     </tp:mapping>
 
-    <tp:simple-type type="s" name="Sent_Message_Token">
+    <tp:simple-type type="s" name="Protocol_Message_Token">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>An opaque token used to identify sent messages. As a special case,
-          the empty string indicates that there is no particular
-          identification for a message.</p>
+        <p>An opaque token used to identify messages in the underlying.
+          protocol. As a special case, the empty string indicates that there
+          is no particular identification for a message.</p>
 
         <p>CM implementations SHOULD use an identifier expected to be unique,
           such as a UUID, if possible.</p>
 
-        <p>Some protocols can only track a limited number of sent messages
-          in a small message-ID space. As a result, clients MUST NOT assume
-          that message tokens will not be re-used, and SHOULD use some
-          reasonable heuristic to assign delivery reports to messages, such
-          as matching on message content or timestamp (if available), or
-          assuming that the delivery report refers to the most recent message
-          with that ID.</p>
+        <p>Some protocols can only track a limited number of messages
+          in a small message-ID space (SMS messages are identified by a single
+          byte), and some implementations send non-unique identifiers (some
+          XMPP clients use very simple message IDs, such as an incrementing
+          integer that resets to 1 at the beginning of each connection). As a
+          result, clients MUST NOT assume that protocol tokens will not be
+          re-used.</p>
+
+        <p>In particular, clients SHOULD use a heuristic to assign delivery
+          reports to messages, such as matching on message content or
+          timestamp (if available), or assuming that the delivery report
+          refers to the most recent message with that ID.</p>
       </tp:docstring>
     </tp:simple-type>
 
@@ -774,7 +853,7 @@ USA.</p>
 
         <tp:rationale>
           <p>This means that the process sending the message is the first
-            to see the <tp:type>Sent_Message_Token</tp:type>, and can
+            to see the <tp:type>Protocol_Message_Token</tp:type>, and can
             relate the message to the corresponding
             <tp:member-ref>MessageSent</tp:member-ref> signal by comparing
             message tokens (if supported by the protocol).</p>
@@ -798,7 +877,7 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <arg direction="out" type="s" tp:type="Sent_Message_Token"
+      <arg direction="out" type="s" tp:type="Protocol_Message_Token"
         name="Token">
         <tp:docstring>
           An opaque token used to match any incoming delivery or failure
@@ -850,8 +929,9 @@ USA.</p>
         <p>Signals that a message has been submitted for sending. This
           MUST be emitted exactly once per emission of the <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
-          signal on the
-          Text interface.</p>
+          signal on the Text interface. This SHOULD be emitted as soon as
+          the CM determines it's theoretically possible to send the message
+          (e.g. the parameters are supported and correct).</p>
 
         <tp:rationale>
           <p>This signal allows a process that is not the caller of
@@ -889,7 +969,7 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <arg name="Message_Token" type="s" tp:type="Sent_Message_Token">
+      <arg name="Message_Token" type="s" tp:type="Protocol_Message_Token">
         <tp:docstring>
           An opaque token used to match any incoming delivery or failure
           reports against this message, or an empty string if the message
diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
index ac036e7b9..dacf906b1 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -737,26 +737,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
         <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale>
 
-        <p>Connection managers capable of signalling audio calls to contacts
-          SHOULD include a channel class in <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
-          with <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
-           <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Channel.Type">Call.DRAFT</tp:dbus-ref>
-          and <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
-          = Contact in the fixed properties dictionary, and InitialAudio
-          (and also InitialVideo, if applicable) in the allowed properties
-          list. Clients wishing to discover whether a connection manager
-          can signal audio and/or video calls SHOULD use this information.</p>
-
-        <tp:rationale>
-          <p>Not all protocols support signalling video calls, and it would be
-            possible (although unlikely) to have a protocol where only video,
-            and not audio, could be signalled.</p>
-        </tp:rationale>
-
         <p>Connection managers that support the <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
           interface SHOULD represent the capabilities of receiving audio
@@ -848,40 +828,52 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:docstring>
     </property>
 
-    <tp:handler-capability-token name="gtalk-p2p">
+    <tp:hct name="audio">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>This client supports audio calls.</p>
+      </tp:docstring>
+    </tp:hct>
+
+    <tp:hct name="video">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>This client supports video calls.</p>
+      </tp:docstring>
+    </tp:hct>
+
+    <tp:hct name="gtalk-p2p">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
           property is Stream_Transport_Type_GTalk_P2P.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="ice">
+    <tp:hct name="ice">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
           property is Stream_Transport_Type_ICE.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="wlm-8.5">
+    <tp:hct name="wlm-8.5">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
           property is Stream_Transport_Type_WLM_8_5.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="wlm-2009">
+    <tp:hct name="wlm-2009">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client can implement streaming for streams whose <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
           property is Stream_Transport_Type_WLM_2009.</p>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
-    <tp:handler-capability-token name="video/h264" is-family="yes">
-      <tp:docstring>
+    <tp:hct name="video/h264" is-family="yes">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The client supports media streaming with H264 (etc.).</p>
 
         <p>This handler capability token is a one of a family
@@ -904,15 +896,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             <code>video/h264</code> on Call channels.</p>
         </tp:rationale>
 
-        <p>For example, a client could advertise support for
-          Speex, Theora and H264 by having three
-          handler capability tokens,
-          <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code>,
-          <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code> and
-          <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code>,
-          in its <tp:dbus-ref
+        <p>For example, a client could advertise support for audio and video
+          calls using Speex, Theora and H264 by having five handler capability
+          tokens in its <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
-          property.</p>
+          property:</p>
+
+        <ul>
+          <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li>
+          <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li>
+          <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li>
+          <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li>
+          <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li>
+        </ul>
 
         <p>Clients MAY have media signalling abilities without explicitly
           supporting any particular codec, and connection managers SHOULD
@@ -924,7 +920,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
             known to the gatewaying process.</p>
         </tp:rationale>
       </tp:docstring>
-    </tp:handler-capability-token>
+    </tp:hct>
 
   </interface>
 </node>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index e4fa177aa..4484b7ce3 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -666,6 +666,54 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     handled by specialised hardware which is controlled directly by the
     connection manager), the signalling interface can be omitted and this
     channel type used simply to control the streams.</p>
+
+    <h4>Handler filters</h4>
+
+    <p>For historical reasons, handlers must specify more than one filter if
+      they want to correctly advertise support for audio and/or video calls. If
+      they can handle channels using the <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+      interface, they should also advertise various
+      <tp:type>Handler_Capability_Token</tp:type>s to indicate which codecs and
+      transports they support. See <tp:member-ref>InitialAudio</tp:member-ref>
+      and <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling/video/h264</tp:dbus-ref>
+      for the gory details. In summary:</p>
+
+    <dl>
+      <dt>To advertise support for streamed media in general, include the
+        following filter in <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>:</dt>
+      <dd><pre>
+{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+}</pre></dd>
+
+      <dt>To advertise support for audio calls, also include the following
+        filter:</dt>
+      <dd><pre>
+{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+  '...Channel.Type.StreamedMedia.InitialAudio': True,
+}</pre></dd>
+
+      <dt>To advertise support for video calls, also include the following
+        filter:</dt>
+      <dd><pre>
+{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+  '...Channel.TargetHandleType': Contact,
+  '...Channel.Type.StreamedMedia.InitialVideo': True,
+}</pre></dd>
+
+      <dt>If you use telepathy-farsight, and have H.264 support, you probably
+        want these <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>:</dt>
+      <dd><pre>
+[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp",
+  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p",
+  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264",
+]</pre></dd>
+    </dl>
     </tp:docstring>
 
     <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u">
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 026db5290..35e6d91d5 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -147,15 +147,16 @@
 
         <p>For observers that have a .client file, the channel dispatcher
           may discover this property from keys of the form
-          <code><em>propertyname</em>/<em>type</em></code>,
+          "<code><em>propertyname</em> <em>type</em></code>",
           in groups in the .client file whose name is the name of this
           interface followed by <code>.ObserverChannelFilter</code>,
           a space and an ASCII decimal number starting from 0.</p>
 
-        <p>Integers in the .client file are encoded in ASCII decimal, booleans
-          are encoded as "true" or "false", and strings are encoded in the usual
-          way for desktop files (including the C-style backslash escapes
-          documented in the Desktop Entry specification).</p>
+        <p>Values in the .client file are encoded in exactly the same way as
+          the <code>default-<em>p</em></code> keys in .manager files, as
+          described in the <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+            >ConnectionManager</tp:dbus-ref> interface (but note that not all
+          types supported in .manager files can appear in .client files).</p>
 
         <p>For instance, a .client file for an observer that is only interested
           in Text channels, with CONTACT or ROOM handles, that were requested by
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 12cbeab87..1347090b6 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -66,20 +66,14 @@ USA.</p>
       </tp:docstring>
     </method>
 
-    <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
-      <arg direction="out" type="as" tp:type="DBus_Interface[]"
-        name="Interfaces">
-        <tp:docstring>
-          An array of D-Bus interface names
-        </tp:docstring>
-      </arg>
-
+    <property name="Interfaces" tp:name-for-bindings="Interfaces"
+      access="read" type="as" tp:type="DBus_Interface[]">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Get the optional interfaces supported by this connection.
-          Before the connection status changes to CONNECTED, the return
-          from this method may change at any time, but it is guaranteed that
+        <p>The set of optional interfaces supported by this connection.
+          Before the connection status changes to CONNECTED,
+          this property may change at any time, but it is guaranteed that
           interfaces will only be added, not removed. After the connection
-          status changes to CONNECTED, the return from this method cannot
+          status changes to CONNECTED, this property cannot
           change further.</p>
 
         <p>There is no explicit change notification; reasonable behaviour
@@ -97,6 +91,24 @@ USA.</p>
             interfaces for the remainder of the Connection's lifetime.</p>
         </tp:rationale>
       </tp:docstring>
+      <tp:added version="0.19.UNRELEASED">Clients SHOULD fall back
+        to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this
+        property is not supported.</tp:added>
+    </property>
+
+    <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
+      <arg direction="out" type="as" tp:type="DBus_Interface[]"
+        name="Interfaces">
+        <tp:docstring>
+          The value of the <tp:member-ref>Interfaces</tp:member-ref> property
+        </tp:docstring>
+      </arg>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Returns the set of optional interfaces supported by this
+          connection. See <tp:member-ref>Interfaces</tp:member-ref> for more
+          details.</p>
+      </tp:docstring>
 
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
@@ -178,11 +190,28 @@ USA.</p>
       </tp:possible-errors>
     </method>
 
+    <property name="Status" tp:name-for-bindings="Status"
+      access="read" type="u" tp:type="Connection_Status">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The current status of the connection. Change notification is via
+          the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p>
+
+        <p>If retrieval of property succeeds and yields the value Disconnected,
+          this indicates that the connection has not yet been established.
+          If connection has been attempted and failed, the Connection object
+          SHOULD be removed from the bus entirely, meaning that retrieval of
+          this property SHOULD fail.</p>
+      </tp:docstring>
+      <tp:added version="0.19.UNRELEASED">Clients SHOULD fall back
+        to calling <tp:member-ref>GetStatus</tp:member-ref> if this
+        property is not supported.</tp:added>
+    </property>
+
     <method name="GetStatus" tp:name-for-bindings="Get_Status">
       <arg direction="out" type="u" tp:type="Connection_Status"
         name="Status">
         <tp:docstring>
-          An integer representing the current status
+          The value of the <tp:member-ref>Status</tp:member-ref> property
         </tp:docstring>
       </arg>
 
@@ -657,20 +686,25 @@ USA.</p>
     <tp:enum name="Connection_Status" plural="Connection_Statuses" type="u">
       <tp:enumvalue suffix="Connected" value="0">
         <tp:docstring>
-            The connection is alive and all methods are available.
+          The connection is fully connected and all methods are available.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Connecting" value="1">
         <tp:docstring>
-            The connection has not yet been established, or has been
-            severed and reconnection is being attempted. Some methods may fail
-            until the connection has been established.
+          <tp:member-ref>Connect</tp:member-ref> has been called but the
+          connection has not yet been established. Some methods may fail
+          until the connection has been established.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Disconnected" value="2">
         <tp:docstring>
-            The connection has been severed and no method calls are
-            valid. The object may be removed from the bus at any time.
+          If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or
+          <tp:member-ref>Status</tp:member-ref>, it indicates that connection
+          has not yet been attempted. If seen in a
+          <tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates
+          that the connection has failed; the Connection object SHOULD be
+          removed from D-Bus immediately, and all subsequent method calls
+          SHOULD fail.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
index 803ab06d8..fb13c37d7 100644
--- a/spec/Connection_Interface_Contact_Capabilities.xml
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -161,7 +161,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <method name="GetContactCapabilities"
             tp:name-for-bindings="Get_Contact_Capabilities">
-      <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
+      <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>An array of contact handles for this connection.</p>
 
@@ -171,15 +171,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <arg direction="out" type="a{ua(a{sv}as)}"
            tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          An array of structures containing:
-          <ul>
-            <li>a dictionary mapping the channel properties to their values.</li>
-            <li>an array of additional allowed properties</li>
-          </ul>
+          <p>A map from contact handles to lists of requestable channel
+            classes, representing the channel requests that are expected
+            to succeed for that contact.</p>
+
+          <p>Contacts listed among Handles whose capabilities are unknown
+            SHOULD be omitted from this map; contacts known to have an empty
+            set of capabilities SHOULD be included in the keys of this map,
+            with an empty array as the corresponding value.</p>
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Returns an array of enhanced capabilities for the given contact handles.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Returns an array of requestable channel classes for the given
+          contact handles, representing the channel requests that are
+          expected to succeed.</p>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 92c80c801..c6d9a5b70 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -111,16 +111,18 @@
             interfaces, whose values can be obtained without additional network
             activity, will be in the reply.</p>
 
-          <p>It is an error to request interfaces that are not supported by
-            this Connection (i.e. mentioned in the
+          <p>Connection managers SHOULD ignore interfaces requested which they
+            do not support (i.e. those not mentioned in the
             <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>
-            property).</p>
+            property.)</p>
 
           <tp:rationale>
-            <p>This makes it possible to distinguish between interfaces for
-              which the Connection has nothing to say (e.g. we don't know the
-              avatar tokens of any of the contacts, so we omitted them all),
-              and interfaces for which this API isn't supported.</p>
+            <p>This simplifies client-side code. Clients which care may
+              distinguish between unsupported interfaces (e.g. this Connection
+              does not support Avatars), and interfaces on which no information
+              is known for these contacts (e.g. we don't know the avatar tokens
+              of any of the contacts, so we omitted them all) by inspecting
+              <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>.</p>
           </tp:rationale>
 
           <p>Attributes from the interface
@@ -141,6 +143,12 @@
             attributes.
           </tp:rationale>
         </tp:docstring>
+        <tp:changed version="UNRELEASED">
+          requesting information for interfaces not mentioned in
+          <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> is no
+          longer an error. Be aware that older connection managers may still
+          consider this an error.
+        </tp:changed>
       </arg>
 
       <arg direction="in" name="Hold" type="b">
@@ -173,12 +181,6 @@
 
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          <tp:docstring>
-            One of the requested interfaces is not supported (mentioned in
-            <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>).
-          </tp:docstring>
-        </tp:error>
       </tp:possible-errors>
     </method>
   </interface>
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 8cc1191bb..c4fecd6fa 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -318,6 +318,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             pings.</dd>
         </dl>
 
+        <p>Connection manager authors SHOULD avoid introducing parameters
+          whose default values would not be serializable in a
+          <code>.manager</code> file.</p>
+
+        <tp:rationale>
+          <p>The same serialization format is used in Mission Control
+            to store accounts.</p>
+        </tp:rationale>
+
         <p>Every successful RequestConnection call will cause the emission of a
         <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly
         created connection. The
@@ -462,7 +471,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <dd>The object path as an ASCII string</dd>
       <dt>b (boolean)</dt>
         <dd>"true" (case-insensitively) or "1" means True, "false"
-          (case-insensitively) or "0" means False</dd>
+          (case-insensitively) or "0" means False; when writing a file,
+          "true" and "false" SHOULD be used</dd>
       <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt>
         <dd>ASCII decimal integer</dd>
       <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index 093224395..91f378c3a 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -70,4 +70,5 @@ EXTRA_DIST = \
     generic-types.xml \
     Media_Session_Handler.xml \
     Media_Stream_Handler.xml \
-    Properties_Interface.xml
+    Properties_Interface.xml \
+    template.xml
diff --git a/spec/all.xml b/spec/all.xml
index c87e89cbb..c4c9e21f5 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,10 +3,10 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.19.1</tp:version>
+<tp:version>0.19.2</tp:version>
 
-<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
-<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+<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">
@@ -189,8 +189,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 <xi:include href="Connection_Interface_Forwarding.xml"/> -->
 <!-- Never implemented, vague
 <xi:include href="Connection_Interface_Privacy.xml"/> -->
-<!-- Never implemented, can't be implemented with current dbus-glib, vague
-<xi:include href="Channel_Type_Contact_Search.xml"/> -->
 <!-- Causes havoc, never implemented, unclear requirements
 <xi:include href="Channel_Interface_Transfer.xml"/> -->
 
diff --git a/spec/template.xml b/spec/template.xml
new file mode 100644
index 000000000..d752d721c
--- /dev/null
+++ b/spec/template.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" ?>
+<node name="/Foo"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>This library is free software; you can redistribute it and/or
+      modify it under the terms of the GNU Lesser General Public
+      License as published by the Free Software Foundation; either
+      version 2.1 of the License, or (at your option) any later version.</p>
+
+    <p>This library is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+      Lesser General Public License for more details.</p>
+
+    <p>You should have received a copy of the GNU Lesser General Public
+      License along with this library; if not, write to the Free Software
+      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+      02110-1301, USA.</p>
+  </tp:license>
+
+  <interface name="org.freedesktop.Telepathy.Foo.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:added version="0.19.UNRELEASED">(draft 1)</tp:added>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>Foo.</p>
+    </tp:docstring>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->