Merge branch 'undraft'

Reviewed-by: Guillaume Desmottes <guillaume.desmottes@collabora.co.uk>

3 files changed, 37 insertions, 24 deletions

diff --git a/extensions/Connection_Interface_Contact_Info.xml b/extensions/Connection_Interface_Contact_Info.xml
index e8681c939..91a948e6c 100644
--- a/extensions/Connection_Interface_Contact_Info.xml
+++ b/extensions/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">
@@ -221,7 +220,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           Integer handles for contacts.
         </tp:docstring>
       </arg>
-      <tp:added version="0.19.UNRELEASED"/>
       <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
@@ -308,7 +306,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:possible-errors>
     </method>
 
-    <tp:enum name="Contact_Info_Flags" 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.
@@ -317,22 +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>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>
@@ -410,8 +408,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the
           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
@@ -420,22 +418,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <pre>
 [
-  ('tel', ['home'], Parameters_Exact, 1),
-  ('tel', ['cell'], Parameters_Exact, 1),
+  ('tel', ['type=home'], Parameters_Exact, 1),
+  ('tel', ['type=cell'], Parameters_Exact, 1),
   ('adr', [], Parameters_Exact, 1),
   ('bday', [], Parameters_Exact, 1),
-  ('email', ['internet'], 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
diff --git a/extensions/Connection_Interface_Mail_Notification.xml b/extensions/Connection_Interface_Mail_Notification.xml
index 35678c2f9..c74dd59f8 100644
--- a/extensions/Connection_Interface_Mail_Notification.xml
+++ b/extensions/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/tests/twisted/constants.py b/tests/twisted/constants.py
index 00540b51f..1077002ba 100644
--- a/tests/twisted/constants.py
+++ b/tests/twisted/constants.py
@@ -97,7 +97,7 @@ CONN_IFACE_AVATARS = CONN + '.Interface.Avatars'
 CONN_IFACE_CAPS = CONN + '.Interface.Capabilities'
 CONN_IFACE_CONTACTS = CONN + '.Interface.Contacts'
 CONN_IFACE_CONTACT_CAPS = CONN + '.Interface.ContactCapabilities'
-CONN_IFACE_CONTACT_INFO = CONN + ".Interface.ContactInfo.DRAFT"
+CONN_IFACE_CONTACT_INFO = CONN + ".Interface.ContactInfo"
 CONN_IFACE_SIMPLE_PRESENCE = CONN + '.Interface.SimplePresence'
 CONN_IFACE_REQUESTS = CONN + '.Interface.Requests'
 CONN_IFACE_LOCATION = CONN + '.Interface.Location'