Update to spec 0.19.5

17 files changed, 579 insertions, 187 deletions

diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml
index 1d5e891d..3e585b49 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/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
index 8b9a17c8..2b3eb65d 100644
--- a/spec/Call_Content_Interface_Media.xml
+++ b/spec/Call_Content_Interface_Media.xml
@@ -61,7 +61,7 @@
         </tp:docstring>
       </tp:member>
 
-      <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map">
+      <tp:member name="Parameters" type="a{ss}">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           Extra parameters for this codec
         </tp:docstring>
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 223a612d..0fedf689 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 af3e627b..92d962d6 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
@@ -270,7 +270,7 @@
           invited into the new channel, as if they had been added with
           <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
             >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
-          <tp:member-ref>InvitationMessage</tp:member-ref> immediately after
+          <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after
           the channel was created.</p>
 
         <tp:rationale>
@@ -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 004df5b8..242c9528 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 c668067d..566e1166 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 4df99e40..dacf906b 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -557,7 +557,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         </tp:docstring>
       </arg>
 
-      <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason">
+      <arg name="Call_State_Reason" type="(uus)">
         <tp:docstring>
           The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
           property.
@@ -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_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 5f5bd4bf..195d97be 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -388,9 +388,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>An array of fields representing information about this
             contact, in the same format used in the <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
+              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo</tp:dbus-ref>
             interface. It is possible that a separate call to <tp:dbus-ref
-              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref>
             would return more information than this signal provides.</p>
 
           <p>This array SHOULD include the <code>x-telepathy-identifier</code>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index e4fa177a..4484b7ce 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 026db529..a2256a75 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
@@ -179,6 +180,43 @@ org.freedesktop.Telepathy.Channel.Requested b=true
       </tp:docstring>
     </property>
 
+    <property name="Recover" tp:name-for-bindings="Recover" type="b"
+      access="read">
+      <tp:added version="0.19.4">
+        When using telepathy-mission-control, version 5.4.0 or later is
+        needed for this property to be useful.
+      </tp:added>
+
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>If true, upon the startup of this observer, <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref>
+        will be called for every already existing channel matching
+        its <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
+
+        <p>When activatable client having this property disappears from the bus
+        and there are channels matching its ObserverChannelFilter,
+        ObserveChannels will be called immediately to reactivate it again.</p>
+        <tp:rationale>
+          <p>This means that if an activatable Observer crashes, it will
+            be restarted as soon as possible; while there is an unavoidable
+            possibility that it will miss some events during this process
+            (particularly <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+            messages), this window of event loss is kept to a minimum.</p>
+
+           <p>Non-activatable observers can't take advantage of this
+            mechanism, but setting this property on a non-activatable
+            observer does allow it to "catch up" on channels that are
+            currently active at the time that it starts up.</p>
+        </tp:rationale>
+
+        <p>When the ObserveChannels method is called due to observer recovery,
+        the "Observer_Info" dictionary will contain one extra item with key
+        "recovering" and boolean value of True.</p>
+      </tp:docstring>
+    </property>
+
     <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Called by the channel dispatcher when channels in which the
@@ -293,10 +331,23 @@ org.freedesktop.Telepathy.Channel.Requested b=true
 
       <arg name="Observer_Info" type="a{sv}" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Additional information about these channels. No keys are
-            currently defined.</p>
-
-          <p>If keys are defined for this dictionary, all will be optional;
+          <p>Additional information about these channels. Currently defined
+            keys are:</p>
+
+          <dl>
+            <dt><code>recovering</code> - b</dt>
+            <dd>True if ObserveChannels was called on existing channel due to
+              observer recovery, otherwise False.
+              <tp:rationale>
+                This allows observers to distinguish between new channels (the normal
+                case), and existing channels that were given to the observer in order
+                to catch up on previous events (perhaps after a previous instance of
+                the same observer crashed).
+              </tp:rationale>
+            </dd>
+          </dl>
+
+          <p>All defined keys for this dictionary are optional;
             observers MAY safely ignore any entry in this dictionary.</p>
         </tp:docstring>
       </arg>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 12cbeab8..3109670a 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.2">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.2">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 803ab06d..fb13c37d 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_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index d0854546..91a948e6 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -17,9 +17,8 @@ Lesser General Public License for more details.</p>
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
-  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT"
-    tp:causes-havoc="experimental">
-    <tp:added version="0.17.18">(as a draft)</tp:added>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">
+    <tp:added version="0.19.4">(as stable API)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
     <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List">
@@ -110,6 +109,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             city), region (e.g., state or province), the postal code, and the
             country name.</dd>
 
+          <dt>label</dt>
+          <dd>A free-form street address for the contact, formatted as a
+            single value (with embedded newlines where necessary) suitable for
+            printing on an address label</dd>
+
           <dt>tel</dt>
           <dd>A telephone number for the contact.</dd>
 
@@ -124,9 +128,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    VERSION:3.0
    FN:Wee Ninja
    N;LANGUAGE=ja:Ninja;Wee;;;-san
-   ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
+   ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement
    ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
     ;CB2 1SJ;UK
+   LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ
    TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753
    EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
    EMAIL;TYPE=INTERNET:wee.ninja@example.com
@@ -140,9 +145,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 [
   ('fn', [], ['Wee Ninja']),
   ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
-  ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
+  ('org', [], ['Collabora, Ltd.', 'Management Division',
+    'Human Resources; Company Policy Enforcement']),
   ('adr', ['type=work','type=postal','type=parcel'],
    ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+  ('label', ['type=work','type=postal','type=parcel'],
+   ['''11 Kings Parade
+  Cambridge
+  Cambridgeshire
+  UK
+  CB2 1SJ''']),
   ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
   ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
   ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
@@ -162,7 +174,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         name="Contact_Info"/>
     </tp:mapping>
 
-    <signal name="ContactInfoChanged" tp:name-for-bindings="ContactInfoChanged">
+    <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed">
       <arg name="Contact" type="u" tp:type="Contact_Handle">
         <tp:docstring>
           An integer handle for the contact whose info has changed.
@@ -197,10 +209,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
         Request information on several contacts at once.  This SHOULD only
         return cached information, omitting handles for which no information is
-        cached from the returned map.  For contacts without cached information,
-        the information SHOULD be requested from the network, with the result
-        signalled later by <tp:member-ref>ContactInfoChanged</tp:member-ref>.
+        cached from the returned map.
+      </tp:docstring>
+    </method>
+
+    <method name="RefreshContactInfo"
+      tp:name-for-bindings="Refresh_Contact_Info">
+      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          Integer handles for contacts.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Retrieve information for the given contact, requesting it from the
+        network if an up-to-date version is not cached locally. This method
+        SHOULD return immediately, emitting
+        <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts'
+        updated contact information is returned.
+
+        <tp:rationale>
+          This method allows a client with cached contact information to
+          update its cache after a number of days.
+        </tp:rationale>
       </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+      </tp:possible-errors>
     </method>
 
     <method name="RequestContactInfo"
@@ -219,8 +254,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
         Retrieve information for a contact, requesting it from the network if
         it is not cached locally.
+
+        <tp:rationale>
+          This method is appropriate for an explicit user request to show
+          a contact's information; it allows a UI to wait for the contact
+          info to be returned.
+        </tp:rationale>
       </tp:docstring>
       <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
           <tp:docstring>
             The contact's information could not be retrieved.
@@ -262,7 +306,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:possible-errors>
     </method>
 
-    <tp:enum name="Contact_Info_Flag" value-prefix="Contact_Info_Flag"
+    <tp:flags name="Contact_Info_Flags" value-prefix="Contact_Info_Flag"
       type="u">
       <tp:docstring>
         Flags defining the behaviour of contact information on this protocol.
@@ -271,24 +315,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         and when it changes.
       </tp:docstring>
 
-      <tp:enumvalue suffix="Can_Set" value="1">
+      <tp:flag suffix="Can_Set" value="1">
         <tp:docstring>
           Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is
           supported on this connection.
         </tp:docstring>
-      </tp:enumvalue>
+      </tp:flag>
 
-      <tp:enumvalue suffix="Push" value="2">
+      <tp:flag suffix="Push" value="2">
         <tp:docstring>
           Indicates that the protocol pushes all contacts' information to the
           connection manager without prompting. If set,
-          <tp:member-ref>RequestContactInfo</tp:member-ref> will not cause a
-          network roundtrip and
           <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted
           whenever contacts' information changes.
         </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
+      </tp:flag>
+    </tp:flags>
 
     <tp:simple-type name="VCard_Field" type="s">
       <tp:docstring>
@@ -309,10 +351,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     </tp:simple-type>
 
     <property name="ContactInfoFlags" type="u" access="read"
-      tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags">
-      <tp:docstring>
-        An integer representing the bitwise-OR of flags on this connection.
-        This property should be constant over the lifetime of a connection.
+      tp:type="Contact_Info_Flags" tp:name-for-bindings="Contact_Info_Flags">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>An integer representing the bitwise-OR of flags on this
+          connection.</p>
+
+        <p>This property MAY change, without change notification, at any time
+          before the connection moves to status Connection_Status_Connected.
+          It MUST NOT change after that point.</p>
+
+        <tp:rationale>
+          <p>Some XMPP servers, like Facebook Chat, do not allow the vCard to
+            be changed (and so would not have the Can_Set flag). Whether the
+            user's server is one of these cannot necessarily be detected until
+            quite late in the connection process.</p>
+        </tp:rationale>
+
       </tp:docstring>
     </property>
 
@@ -328,8 +382,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]">
         <tp:docstring>The set of vCard type parameters which may be set on this
           field. If this list is empty and the
-          Contact_Info_Field_Flag_Parameters_Mandatory
-          flag is unset, any vCard type parameters may be used.</tp:docstring>
+          Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type
+          parameters may be used.</tp:docstring>
       </tp:member>
 
       <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags">
@@ -352,10 +406,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           list indicates that arbitrary vCard fields are permitted.  This
           property SHOULD be the empty list, and be ignored by clients, if
           <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the
-          Can_Set <tp:type>Contact_Info_Flag</tp:type>.</p>
+          Can_Set flag.</p>
 
-        <p>For example, an implementation of XEP-0054, which defines a mapping
-          of vCards to XML for use over XMPP, would set this property to the
+        <p>For example, a protocol in which arbitrary vCards were stored
+          as-is would set this property to the
           empty list. A protocol whose notion of contact information is one
           each of personal phone number, mobile phone number, location, email
           address and date of birth, with no attributes allowed on each piece
@@ -364,22 +418,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <pre>
 [
-  ('tel', ['home'], Parameters_Mandatory, 1),
-  ('tel', ['cell'], Parameters_Mandatory, 1),
-  ('adr', [], Parameters_Mandatory, 1),
-  ('bday', [], Parameters_Mandatory, 1),
-  ('email', ['internet'], Parameters_Mandatory, 1),
+  ('tel', ['type=home'], Parameters_Exact, 1),
+  ('tel', ['type=cell'], Parameters_Exact, 1),
+  ('adr', [], Parameters_Exact, 1),
+  ('bday', [], Parameters_Exact, 1),
+  ('email', ['type=internet'], Parameters_Exact, 1),
 ]</pre>
 
         <p>A protocol which allows users to specify up to four phone numbers,
           which may be labelled as personal and/or mobile, would set this
-          property to <code>[ ('tel', ['home', 'cell'], 0, 4), ]</code>.</p>
+          property to
+          <code>[ ('tel', ['type=home', 'type=cell'], 0, 4), ]</code>.</p>
 
         <tp:rationale>
           <p>Studying existing IM protocols shows that in practice protocols
             allow either a very restricted set of fields (such as MSN, which
-            seems to correspond roughly to the largest example above) or
-            something mapping 1-1 to vCard (such as XMPP).</p>
+            seems to correspond roughly to the largest example above), or
+            something mapping 1:1 to a large subset of vCard (such as XMPP's
+            XEP-0054).</p>
+        </tp:rationale>
+
+        <p>This property MAY change, without change notification, at any time
+          before the connection moves to status Connection_Status_Connected.
+          It MUST NOT change after that point.</p>
+
+        <tp:rationale>
+          <p>Some XMPP servers, like Google Talk, only allow a small subset of
+            the "vcard-temp" protocol. Whether the user's server is one of
+            these cannot be detected until quite late in the connection
+            process.</p>
         </tp:rationale>
       </tp:docstring>
     </property>
@@ -389,7 +456,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         Flags describing the behaviour of a vCard field.
       </tp:docstring>
-      <tp:flag suffix="Parameters_Mandatory" value="1">
+      <tp:flag suffix="Parameters_Exact" value="1">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>If present, exactly the parameters indicated must be set on this
             field; in the case of an empty list of parameters, this implies that
@@ -411,6 +478,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:type>Contact_Info_Field</tp:type>s forming a
         structured representation of a vCard (as defined by RFC 2426), using
         field names and semantics defined therein.</p>
+
+      <p>On some protocols, information about your contacts is pushed to you,
+        with change notification; on others, like XMPP, the client must
+        explicitly request the avatar, and has no way to tell whether it has
+        changed without retrieving it in its entirety. This distinction is
+        exposed by <tp:member-ref>ContactInfoFlags</tp:member-ref> containing
+        the Push flag.</p>
+
+      <p>On protocols with the Push flag set, UIs can connect to
+        <tp:member-ref>ContactInfoChanged</tp:member-ref>, call
+        <tp:member-ref>GetContactInfo</tp:member-ref> once at login for the set
+        of contacts they are interested in, and then be sure they will receive
+        the latest contact info. On protocols like XMPP, clients can do the
+        same, but will receive (at most) opportunistic updates if the info is
+        retrieved for other reasons. Clients may call
+        <tp:member-ref>RequestContactInfo</tp:member-ref> or
+        <tp:member-ref>RefreshContactInfo</tp:member-ref> to force a contact's
+        info to be updated, but MUST NOT do so unless this is either in
+        response to direct user action, or to refresh their own cache after a
+        number of days.</p>
+
+      <tp:rationale>
+        <p>We don't want clients to accidentally cause a ridiculous amount of
+          network traffic.</p>
+      </tp:rationale>
     </tp:docstring>
   </interface>
 </node>
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 92c80c80..cd769ceb 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="0.19.2">
+          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_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
index 35678c2f..c74dd59f 100644
--- a/spec/Connection_Interface_Mail_Notification.xml
+++ b/spec/Connection_Interface_Mail_Notification.xml
@@ -353,17 +353,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>If <tt>Thread_Based</tt> appears in the
           <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property
           counts the number of threads, not the number of mails.</p>
+
+        <p>Note that this count MAY be bigger than the number of items in
+          <tp:member-ref>UnreadMails</tp:member-ref>. See
+          <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p>
       </tp:docstring>
     </property>
 
     <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]"
       tp:name-for-bindings="Unread_Mails" access="read">
       <tp:docstring>
-        A array of unread <tp:type>Mail</tp:type>s. Change notification is via
-        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property is
-        only useful if <tt>Supports_Unread_Mails</tt> is set in
-        <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it MUST be
-        an empty list.
+        <p>An array of unread <tp:type>Mail</tp:type>s. Change notification is
+          via <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property
+          is only useful if <tt>Supports_Unread_Mails</tt> is set in
+          <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it
+          MUST be an empty list.</p>
+        <p>The array size MAY be shorter than
+          <tp:member-ref>UnreadMailCount</tp:member-ref>.</p>
+        <tp:rationale>
+          <p>Some servers may limits the amount of detailed e-mails sent. This
+            can significantly reduce the network traffic for large inbox. For
+            this reason, it is normal that
+            <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal
+            to the size of this array.</p>
+          </tp:rationale>
       </tp:docstring>
     </property>
 
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 8cc1191b..c4fecd6f 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/all.xml b/spec/all.xml
index c87e89cb..a5ea1c4d 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.5</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"/> -->