Update telepathy-spec to 0.17.18

1 files changed, 328 insertions, 36 deletions

diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index 4f8fd42d5..c29f9fe61 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -1,8 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Connection_Interface_Contact_Info" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2008 Nokia Corporation </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -18,66 +17,359 @@ 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"
-    tp:causes-havoc='obsolete'>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
-    <signal name="GotContactInfo" tp:name-for-bindings="Got_Contact_Info">
+
+    <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List">
+      <tp:member type="s" name="Field_Name">
+        <tp:docstring>
+          The name of the field; this is the lowercased name of a vCard field.
+          For example, a field representing a contact's address would be named
+          "adr".
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="as" name="Parameters">
+        <tp:docstring>
+          A list of (lowercased) vCard type parameters applicable to this field.
+          For example, a contact's preferred home address would have parameters
+          'home' and 'pref'.
+
+          <tp:rationale>
+            This is a list of strings rather than a bitwise OR of enum members
+            because vCard type parameters are essentially arbitrary strings.
+          </tp:rationale>
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="as" name="Field_Value">
+        <tp:docstring>
+          For unstructured vCard fields (such as 'fn', a formatted name
+          field), a single-element array containing the field's value; for
+          structured fields (such as 'adr', an address field), an array
+          corresponding to the semicolon-separated elements of the field (with
+          empty strings for empty elements).  A vCard field with multiple
+          comma-separated values should be represented by several
+          <tp:type>Contact_Info_Field</tp:type>s.  Characters which are
+          required to be escaped in vCard values, such as semi-colons, should
+          not be escaped in this list.
+
+          <tp:rationale>
+            An earlier draft of this interface split structured vCard fields
+            into multiple Telepathy-level fields; for example, 'n' became
+            'family-name', 'given-name', etc.  But under this representation,
+            omitting empty components leads to difficulty identifying where one
+            name ends and another begins.  Consider the fields ['given-name',
+            'honorific-suffixes', 'family-name', 'honorific-prefixes']: does
+            this represent two 'n' fields, or one with incorrect component
+            ordering?
+          </tp:rationale>
+        </tp:docstring>
+      </tp:member>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Represents one piece of information about a contact, as modelled by
+          a single vCard field. Of the fields defined in RFC 2426, common
+          examples include:</p>
+
+        <dl>
+          <dt>fn</dt>
+          <dd>The contact's full name, formatted to their liking</dd>
+
+          <dt>n</dt>
+          <dd>The contact's full name, divided into five parts: family name,
+            given name, additional names, honorific prefixes, and honorific
+            suffixes</dd>
+
+          <dt>org</dt>
+          <dd>The contact's organisation, divided into the organization's name
+            possibly followed by one or more organizational unit names.</dd>
+
+          <dt>adr</dt>
+          <dd>A street address for the contact, divided into seven components:
+            post office box, extended address, street address, locality (e.g.,
+            city), region (e.g., state or province), the postal code, and the
+            country name.</dd>
+
+          <dt>tel</dt>
+          <dd>A telephone number for the contact.</dd>
+
+          <dt>email</dt>
+          <dd>An email address for the contact.</dd>
+        </dl>
+
+        <p>For example, the following vCard:</p>
+
+        <pre>
+   BEGIN:vCard
+   VERSION:3.0
+   FN:Wee Ninja
+   N:Ninja;Wee;;;-san
+   ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
+   ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
+    ;CB2 1SJ;UK
+   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
+   URL:http://www.thinkgeek.com/geektoys/plush/8823/
+   END:vCard</pre>
+
+        <p>would be represented by (in Python-like syntax):</p>
+
+        <pre>
+[
+  ('fn', [], ['Wee Ninja']),
+  ('n', [], ['Ninja', 'Wee', '', '', '-san']),
+  ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
+  ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
+                                       'Cambridgeshire','CB2 1SJ','UK']),
+  ('tel', ['voice','work'], ['+44 1223 362967']),
+  ('tel', ['voice','work'], ['+44 7700 900753']),
+  ('email', ['internet','pref'], ['wee.ninja@collabora.co.uk']),
+  ('email', ['internet'], ['wee.ninja@example.com']),
+  ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+]</pre>
+      </tp:docstring>
+    </tp:struct>
+
+    <tp:mapping name="Contact_Info_Map" array-name="">
+      <tp:docstring>A dictionary whose keys are contact handles and whose
+        values are contact information..</tp:docstring>
+      <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+      <tp:member type="a(sasas)" tp:type="Contact_Info_Field[]"
+        name="Contact_Info"/>
+    </tp:mapping>
+
+    <signal name="ContactInfoChanged" tp:name-for-bindings="ContactInfoChanged">
       <arg name="Contact" type="u" tp:type="Contact_Handle">
         <tp:docstring>
-          An integer handle of the contact ID on the server
+          An integer handle for the contact whose info has changed.
         </tp:docstring>
       </arg>
-      <arg name="VCard" type="s">
-        <tp:docstring>
-          The XML string containing their vcard information
+      <arg name="ContactInfo" type="a(sasas)" tp:type="Contact_Info_Field[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          An array of fields representing information about this contact.
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Emitted when information has been received from the server with
-        the details of a particular contact.
+        Emitted when a contact's information has changed or been received for
+        the first time on this connection.
       </tp:docstring>
     </signal>
+
+    <method name="GetContactInfo"
+      tp:name-for-bindings="Get_Contact_Info">
+      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          An array of handles representing contacts.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="ContactInfo" type="a{ua(sasas)}"
+        tp:type="Contact_Info_Map">
+        <tp:docstring>
+          A dictionary mapping contact handles to information, whose keys are
+          the subset of the requested list of handles for which information was
+          cached.
+        </tp:docstring>
+      </arg>
+      <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>.
+      </tp:docstring>
+    </method>
+
     <method name="RequestContactInfo"
       tp:name-for-bindings="Request_Contact_Info">
       <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
         <tp:docstring>
-          An integer handle for the contact to request info for
+          An integer handle for a contact.
         </tp:docstring>
       </arg>
+      <arg direction="out" name="Contact_Info" type="a(sasas)"
+        tp:type="Contact_Info_Field[]">
+        <tp:docstring>
+          Information about that contact.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Retrieve information for a contact, requesting it from the network if
+        it is not cached locally.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The contact's information could not be retrieved.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <method name="SetContactInfo" tp:name-for-bindings="Set_Contact_Info">
       <tp:docstring>
-        Request information for a given contact. The function will return
-        after a GotContactInfo signal has been emitted for the contact, or
-        an error returned.
+        Set new contact information for this connection, replacing existing
+        information.  This method is only suppported if
+        <tp:member-ref>ContactInfoFlags</tp:member-ref> contains
+        <code>Can_Set</code>, and may only be passed fields conforming to
+        <tp:member-ref>SupportedFields</tp:member-ref>.
       </tp:docstring>
+      <arg direction="in" name="ContactInfo" type="a(sasas)"
+        tp:type="Contact_Info_Field[]">
+        <tp:docstring>
+          The new information to be set.
+        </tp:docstring>
+      </arg>
       <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.PermissionDenied"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            Setting your own information is not supported on this protocol.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The supplied fields do not match the restrictions specified by
+            <tp:member-ref>SupportedFields</tp:member-ref>.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
-    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. A new version
-        will be proposed in the 0.13 specification branch.</p>
 
+    <tp:enum name="Contact_Info_Flag" value-prefix="Contact_Info_Flag"
+      type="u">
+      <tp:docstring>
+        Flags defining the behaviour of contact information on this protocol.
+        Some protocols provide no information on contacts without an explicit
+        request; others always push information to the connection manager as
+        and when it changes.
+      </tp:docstring>
+
+      <tp:enumvalue 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:enumvalue 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>
+
+    <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 channel. This
+        property should be constant over the lifetime of a connection.
+      </tp:docstring>
+    </property>
+
+    <tp:struct name="Field_Spec" array-name="Field_Specs">
+      <tp:docstring>A struct describing a vCard field, with parameters, that
+        may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this
+        Connection.</tp:docstring>
+
+      <tp:member type="s" name="Name">
+        <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring>
+      </tp:member>
+
+      <tp:member type="as" name="Parameters">
+        <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>
+      </tp:member>
+
+      <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags">
+        <tp:docstring>Flags describing the behaviour of this
+          field.</tp:docstring>
+      </tp:member>
+
+      <tp:member type="u" name="Max">
+        <tp:docstring>Maximum number of instances of this field which may be
+          set.  MAXUINT32 is used to indicate that there is no
+          limit.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <property name="SupportedFields" type="a(sasuu)" tp:type="Field_Spec[]"
+      access="read" tp:name-for-bindings="Supported_Fields">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A list of field specifications describing the kinds of fields which may
+          be passed to <tp:member-ref>SetContactInfo</tp:member-ref>.  The empty
+          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>
+
+        <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
+          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
+          of information, would set this property to (in Python-like
+          syntax):</p>
+
+        <pre>
+[
+  ('tel', ['home'], Parameters_Mandatory, 1),
+  ('tel', ['cell'], Parameters_Mandatory, 1),
+  ('adr', [], Parameters_Mandatory, 1),
+  ('bday', [], Parameters_Mandatory, 1),
+  ('email', ['internet'], Parameters_Mandatory, 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>
+
+        <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>
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <tp:flags name="Contact_Info_Field_Flags"
+      value-prefix="Contact_Info_Field_Flag" type="u">
+      <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: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
+            parameters may not be used.</p>
+
+          <p>If absent, and the list of allowed parameters is non-empty,
+            any (possibly empty) subset of that list may be
+            used.</p>
+
+          <p>If absent, and the list of allowed parameters is empty,
+            any parameters may be used.</p>
+        </tp:docstring>
+      </tp:flag>
+    </tp:flags>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An interface for requesting information about a contact on a given
-    connection. Information is returned as a vCard represented as an XML
-    string, in the format defined by JEP-0054: vcard-temp specifiation
-    from the Jabber Software Foundation (this is derived from the
-    aborted IETF draft draft-dawson-vcard-xml-dtd-01).</p>
-
-    <p>Implementations using PHOTO or SOUND elements should use the URI encoding
-    where possible, and not provide base64 encoded data to avoid unnecessary
-    bus traffic. Clients should not implement support for these encoded forms.
-    A separate interface will be provided for transferring user avatars.</p>
-
-    <p>The following extended element names are also added to represent
-      information from other systems which are not based around vCards:</p>
-    <dl>
-      <dt>USERNAME</dt><dd>the username of the contact on their local system (used on IRC for example)</dd>
-      <dt>HOSTNAME</dt><dd>the fully qualified hostname, or IPv4 or IPv6 address of the contact in dotted quad or colon-separated form</dd>
-    </dl>
+        connection. Information is represented as a list of
+        <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>
     </tp:docstring>
   </interface>
 </node>