Update to spec 0.19.4 (Observer.Recover)

6 files changed, 198 insertions, 43 deletions

diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
index 2441a7d9e..92d962d69 100644
--- a/spec/Channel_Interface_Conference.xml
+++ b/spec/Channel_Interface_Conference.xml
@@ -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>
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 5f5bd4bf1..195d97be7 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/Client_Observer.xml b/spec/Client_Observer.xml
index 35e6d91d5..a2256a753 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -180,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
@@ -294,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_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index d08545466..b77293514 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:enum name="Contact_Info_Flags" value-prefix="Contact_Info_Flag"
       type="u">
       <tp:docstring>
         Flags defining the behaviour of contact information on this protocol.
@@ -282,8 +326,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <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>
@@ -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_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
index 35678c2f9..c74dd59f8 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/all.xml b/spec/all.xml
index 0ec47089a..9ae5b3db7 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.3</tp:version>
+<tp:version>0.19.4</tp:version>
 
 <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>