path: root/spec/Connection_Interface_Contact_Info.xml

<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_Info" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <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
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
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>
    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>

    <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 xmlns="http://www.w3.org/1999/xhtml">
          <p>A list of vCard type parameters applicable to this field, with their
            values. The type parameter names, and any values that are
            case-insensitive in vCard, MUST be in lower case. For example, a
            contact's preferred home address would have parameters
            'type=home' and 'type=pref'.</p>

          <tp:rationale>
            The type parameter 'type' is likely to be the most common, but
            there can be others, such as 'language=en'.
          </tp:rationale>

          <p>Characters which are required to be escaped in vCard type
            parameters should not be escaped in this list. For instance,
            a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become
            ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p>

          <tp:rationale>
            This avoids Telepathy UIs having to understand the escaping and
            unescaping rules for vCards. The type parameter name is not
            allowed (by RFC 2425) to contain an '=' character, so no ambiguity
            is introduced.
          </tp:rationale>
        </tp:docstring>
      </tp:member>
      <tp:member type="as" name="Field_Value">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>For unstructured vCard fields (such as 'fn', a formatted name
            field), a single-element array containing the field's value.</p>

          <p>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).</p>

          <p>A vCard field with multiple comma-separated values, such as
            'nickname', should be represented by several
            <tp:type>Contact_Info_Field</tp:type>s.</p>

          <p>Characters which are required to be escaped in vCard values, such as
            semi-colons and newlines, should not be escaped in this list (e.g. if
            a value contains a newline, the data passed over D-Bus should
            contain a literal newline character).</p>

          <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;LANGUAGE=ja: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/
   NICKNAME:HR Ninja,Enforcement Ninja
   END:vCard</pre>

        <p>would be represented by (in Python-like syntax):</p>

        <pre>
[
  ('fn', [], ['Wee Ninja']),
  ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
  ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
  ('adr', ['type=work','type=postal','type=parcel'],
   ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
  ('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']),
  ('email', ['type=internet'], ['wee.ninja@example.com']),
  ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
  ('nickname', [], ['HR Ninja']),
  ('nickname', [], ['Enforcement Ninja'])
]</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 for the contact whose info has changed.
        </tp:docstring>
      </arg>
      <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 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 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>
        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.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: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>

    <tp:simple-type name="VCard_Field" type="s">
      <tp:docstring>
        A string naming a field in a vCard, such as "fn" or "adr". Although
        these are case-insensitive in RFC 2425, in Telepathy they MUST be
        normalized to lower case. In the terminology of RFC 2425 this is
        called a "type name", and corresponds to the "name" production given
        in the ABNF.
      </tp:docstring>
    </tp:simple-type>

    <tp:simple-type name="VCard_Type_Parameter" type="s">
      <tp:docstring>
        A type parameter as defined by RFC 2426, such as "type=cell" or
        "language=en".
      </tp:docstring>
    </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: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:type="VCard_Field">
        <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring>
      </tp:member>

      <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>
      </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 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>
<!-- vim:set sw=2 sts=2 et ft=xml: -->