Update to spec 0.19.9.

3 files changed, 110 insertions, 40 deletions

diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 7bd225dfe..31cf47194 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -626,8 +626,9 @@ USA.</p>
             <dt>content-type (s)</dt>
             <dd>
               <p>The MIME type of this part. See the documentation
-                for ReceivedMessage for notes on the special status of
-                "text/plain" parts.</p>
+                for <tp:member-ref>MessageReceived</tp:member-ref> and
+                <tp:member-ref>MessageSent</tp:member-ref> for notes on the
+                special status of "text/plain" parts.</p>
 
               <p>Connection managers MUST NOT signal parts without a
                 'content-type' key; if a protocol provides no way to determine
@@ -942,7 +943,11 @@ USA.</p>
       <arg direction="in" name="Flags" type="u"
         tp:type="Message_Sending_Flags">
         <tp:docstring>
-          Flags affecting how the message is sent.
+          Flags affecting how the message is sent. The channel MAY ignore some
+          or all flags, depending on
+          <tp:member-ref>DeliveryReportingSupport</tp:member-ref>; the flags
+          that were handled by the CM are provided in
+          <tp:member-ref>MessageSent</tp:member-ref>.
         </tp:docstring>
       </arg>
 
@@ -971,7 +976,9 @@ USA.</p>
       type="u">
       <tp:docstring>
         Flags altering the way a message is sent. The "most usual" action
-        should always be to have these flags unset.
+        should always be to have these flags unset. Some indication of which
+        flags are supported is provided by the
+        <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property.
       </tp:docstring>
 
       <tp:flag suffix="Report_Delivery" value="1">
@@ -991,6 +998,24 @@ USA.</p>
             messages.</p>
         </tp:docstring>
       </tp:flag>
+
+      <tp:flag suffix="Report_Read" value="2">
+        <tp:added version="0.19.9"/>
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Provide a delivery report when the message is read by the
+            recipient, even if this is not the default for this protocol.
+            Ignored if read reports are not possible on this protocol.</p>
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:flag suffix="Report_Deleted" value="4">
+        <tp:added version="0.19.9"/>
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Provide a delivery report when the message is deleted by the
+            recipient, even if this is not the default for this protocol.
+            Ignored if such reports are not possible on this protocol.</p>
+        </tp:docstring>
+      </tp:flag>
     </tp:flags>
 
     <signal name="MessageSent" tp:name-for-bindings="Message_Sent">
@@ -1151,7 +1176,12 @@ USA.</p>
 
       <arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          The message content, including any attachments or alternatives
+          <p>The message content, including any attachments or alternatives. If
+            the incoming message contains formatted text without a plain text
+            alternative, the connection manager MUST generate a
+            <tt>text/plain</tt> alternative from the formatted text, and
+            include it in this message (both here, and in the
+            <tp:member-ref>PendingMessages</tp:member-ref> property).</p>
         </tp:docstring>
       </arg>
     </signal>
@@ -1224,28 +1254,49 @@ USA.</p>
           </tp:rationale>
         </tp:docstring>
       </tp:enumvalue>
+
+      <tp:enumvalue suffix="Read" value="5">
+        <tp:added version="0.19.9"/>
+        <tp:docstring>
+          The message has been read by the intended recipient.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Deleted" value="6">
+        <tp:added version="0.19.9"/>
+        <tp:docstring>
+          The message has been deleted by the intended recipient. This MAY be
+          signalled on its own if the message is deleted without being read, or
+          after <code>Read</code> if the message was read before being deleted.
+        </tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
 
     <tp:flags name="Delivery_Reporting_Support_Flags"
       value-prefix="Delivery_Reporting_Support_Flag" type="u">
       <tp:docstring>
         Flags indicating the level of support for delivery reporting on this
-        channel. Any future flags added to this set will conform to the
+        channel, as found on the
+        <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. Any
+        future flags added to this set will conform to the
         convention that the presence of an extra flag implies that
-        more operations will succeed.
+        more operations will succeed. Note that CMs may always provide more
+        reports than are requested in the
+        <tp:type>Message_Sending_Flags</tp:type> passed to
+        <tp:member-ref>SendMessage</tp:member-ref>.
+
+        <tp:rationale>
+          If senders want delivery reports, they should ask for them.  If they
+          don't want delivery reports, they can just ignore them, so there's no
+          need to have capability discovery for what will happen if a delivery
+          report isn't requested.
+        </tp:rationale>
       </tp:docstring>
 
       <tp:flag suffix="Receive_Failures" value="1">
         <tp:docstring>
           Clients MAY expect to receive negative delivery reports if
           Message_Sending_Flag_Report_Delivery is specified when sending.
-
-          <tp:rationale>
-            If senders want delivery reports, they should ask for them.
-            If they don't want delivery reports, they can just ignore them,
-            so there's no need to have capability discovery for what will
-            happen if a delivery report isn't requested.
-          </tp:rationale>
         </tp:docstring>
       </tp:flag>
 
@@ -1253,13 +1304,26 @@ USA.</p>
         <tp:docstring>
           Clients MAY expect to receive positive delivery reports if
           Message_Sending_Flag_Report_Delivery is specified when sending.
+        </tp:docstring>
+      </tp:flag>
 
-          <tp:rationale>
-            Same rationale as Receive_Failures.
-          </tp:rationale>
+      <tp:flag suffix="Receive_Read" value="4">
+        <tp:added version="0.19.9"/>
+        <tp:docstring>
+          Clients MAY expect to receive <tp:type>Delivery_Status</tp:type>
+          <code>Read</code> reports if Message_Sending_Flag_Report_Read
+          is specified when sending.
         </tp:docstring>
       </tp:flag>
 
+      <tp:flag suffix="Receive_Deleted" value="8">
+        <tp:added version="0.19.9"/>
+        <tp:docstring>
+          Clients MAY expect to receive <tp:type>Delivery_Status</tp:type>
+          <code>Deleted</code> reports if Message_Sending_Flag_Report_Deleted
+          is specified when sending.
+        </tp:docstring>
+      </tp:flag>
     </tp:flags>
 
     <property name="DeliveryReportingSupport" access="read"
diff --git a/spec/Connection_Interface_Balance.xml b/spec/Connection_Interface_Balance.xml
index 1042bec2c..76f9040e9 100644
--- a/spec/Connection_Interface_Balance.xml
+++ b/spec/Connection_Interface_Balance.xml
@@ -35,41 +35,45 @@
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>An amount of money in a specified currency. For example,
           3.21 British pounds would conventionally be represented by
-          (Amount = 321, Scale = 2, Currency = "GBP"), but could be
-          represented by (Amount = 3210, Scale = 3, Currency = "GBP")
-          in a service that records balance in units of 0.001 pounds.</p>
+          (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>,
+          <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by
+          (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>,
+          <var>Currency</var> = <tt>"GBP"</tt>) in a service that records
+          balance in units of 0.001 pounds.</p>
 
-        <p>As a special case, if Amount = 0, Scale = 2**32 - 1 (i.e.
-          the largest possible 32-bit unsigned integer) and Currency = "",
-          this indicates an unknown amount.</p>
+        <p>As a special case, if <var>Amount</var> = <tt>0</tt>,
+          <var>Scale</var> = <tt>2**32 - 1</tt> (i.e.  the largest possible
+          32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this
+          indicates an unknown amount.</p>
       </tp:docstring>
 
       <tp:member type="i" name="Amount">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The amount, expressed as a fixed-point number with decimal scale
-            defined by the Scale property; for instance, an Amount value of
-            1234 with Scale of 2 represents 12.34 in the currency unit given
-            by the Currency.</p>
+            defined by the <var>Scale</var> field; for instance, an
+            <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of
+            <tt>2</tt> represents 12.34 in the currency unit given by the
+            <var>Currency</var> field.</p>
         </tp:docstring>
       </tp:member>
       <tp:member type="u" name="Scale">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The decimal scale for the fixed point value of the Amount
-            property, defining the number of rightmost decimal digits from
-            the integer value which form the fractional part of the resulting
-            currency value.</p>
+          <p>The decimal scale for the fixed point value of the
+            <var>Amount</var> field, defining the number of rightmost decimal
+            digits from the integer value which form the fractional part of the
+            resulting currency value.</p>
 
-          <p>As well as defining the interpretation of Amount, user interfaces
-            may use this value to determine the precision with which to display
-            the amount.</p>
+          <p>As well as defining the interpretation of <var>Amount</var>, user
+            interfaces may use this value to determine the precision with which
+            to display the amount.</p>
         </tp:docstring>
       </tp:member>
       <tp:member type="s" name="Currency">
         <tp:docstring>
           The currency code represented by this amount, which SHOULD be an
-          international currency code such as "EUR", "USD", or "JPY" if
-          possible. An empty string can be used to indicate that the currency
-          is not known.
+          international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>,
+          or <tt>"JPY"</tt> if possible. An empty string can be used to
+          indicate that the currency is not known.
         </tp:docstring>
       </tp:member>
     </tp:struct>
@@ -77,13 +81,15 @@
     <property name="AccountBalance" tp:name-for-bindings="Account_Balance"
       access="read" type="(ius)" tp:type="Currency_Amount">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>The user's balance on the account corresponding to this Connection.
+        <p>The user's balance on the account corresponding to this <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
           A negative amount may be possible on some services, and indicates
           that the user owes money to the service provider.</p>
 
         <p>On initial connection, this property may have an unknown
-          value, represented by Amount = 0, Scale = 2**32 - 1 (the largest
-          possible 32-bit unsigned integer) and Currency = "".</p>
+          value, represented by <var>Amount</var> = <tt>0</tt>,
+          <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit
+          unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/all.xml b/spec/all.xml
index 44d65347b..e77f63405 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.19.8</tp:version>
+<tp:version>0.19.9</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>