[telepathy-gabble/master] Add ContactSearch draft.
Will Thompson
will.thompson at collabora.co.uk
Wed Aug 26 09:21:43 PDT 2009
Also add ContactInfo draft for the cross-referenced types.
---
extensions/Channel_Type_Contact_Search.xml | 284 ++++++++++++++++
extensions/Connection_Interface_Contact_Info.xml | 393 ++++++++++++++++++++++
extensions/all.xml | 3 +
3 files changed, 680 insertions(+), 0 deletions(-)
create mode 100644 extensions/Channel_Type_Contact_Search.xml
create mode 100644 extensions/Connection_Interface_Contact_Info.xml
diff --git a/extensions/Channel_Type_Contact_Search.xml b/extensions/Channel_Type_Contact_Search.xml
new file mode 100644
index 0000000..410db95
--- /dev/null
+++ b/extensions/Channel_Type_Contact_Search.xml
@@ -0,0 +1,284 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Contact_Search" 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: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.Channel.Type.ContactSearch.DRAFT"
+ tp:causes-havoc='experimental'>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for searching server-stored user directories. A new
+ channel should be requested by a client for each search attempt, and
+ closed when the search is completed or the required result has been
+ found in order to free unused handles.</p>
+
+ <p>The search can be cancelled at any time by calling the channel's
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method. Depending on the protocol, the connection manager may not be
+ able to prevent the server from sending further results; if this is the
+ case, it MUST ignore any further results.</p>
+
+ <p>Before searching, the
+ <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
+ inspected to determine the valid search keys which can be provided to
+ the <tp:member-ref>Search</tp:member-ref> method. A search request is
+ then started by providing some of these terms to the Search method, and
+ the <tp:member-ref>SearchState</tp:member-ref> will change from
+ Not_Started to In_Progress. As results are returned by the server, the
+ <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
+ for each contact found; when the search is complete, the search state
+ will be set to Completed.</p>
+ </tp:docstring>
+
+ <tp:enum name="Channel_Contact_Search_State" type="u">
+ <tp:enumvalue suffix="Not_Started" value="0">
+ <tp:docstring>The search has not started</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="In_Progress" value="1">
+ <tp:docstring>The search is in progress</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Completed" value="2">
+ <tp:docstring>The search has been completed</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="SearchState" tp:name-for-bindings="Search_State"
+ access="read" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>
+ The current state of this search channel object. Change notification
+ is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="SearchStateChanged"
+ tp:name-for-bindings="Search_State_Changed">
+ <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>The new search state</tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+ changes.
+ </tp:docstring>
+ </signal>
+
+ <tp:simple-type name="Contact_Search_Key" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Any of the following search keys, with the indicated result for
+ the search:</p>
+
+ <dl>
+ <dt>The empty string</dt>
+ <dd>Search for the search term in some implementation-dependent
+ set of fields, using an implementation-dependent algorithm
+ (e.g. searching for each word mentioned)
+ <tp:rationale>
+ The "one big search box" approach to searching, as is familiar
+ from Google. The Sametime plugin to Pidgin appears to search in
+ this way.
+ </tp:rationale>
+ </dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type></dt>
+ <dd>Search for the search term in fields matching that name (for
+ instance, <code>nickname</code> would search nicknames, and
+ <code>tel</code> would search any available phone number,
+ regardless of its work/home/mobile/... status).</dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type> followed by
+ "<code>;</code>" and a
+ <tp:type>VCard_Type_Parameter</tp:type> of the form
+ "<code>type=...</code>"</dt>
+ <dd>Search for the search term in fields of that name and type
+ only (for instance, <code>tel;type=mobile</code>).</dd>
+
+ <dt>x-telepathy-identifier</dt>
+ <dd>Search for contacts whose identifier in the IM protocol
+ matches the search term (e.g. contains it as a substring)
+ <tp:rationale>
+ Otherwise, starting a search by identifier would require the UI
+ to know the vCard field name corresponding to identifiers in
+ this protocol, which might be non-standard (like
+ <code>x-jabber</code>) or not exist at all.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-gender</code></dt>
+ <dd>For the search term "male" or "female", search only for contacts
+ listed as male or female, respectively. The results for other
+ search terms are undefined; it is likely that contacts with
+ unspecified gender will only be matched if this search key
+ is omitted from the request.
+ <tp:rationale>
+ Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
+ also supports limiting search results by gender.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-family</code></dt>
+ <dd>Search for the search term in contacts' family names
+ (the first component of the vCard field <code>n</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC seem to support this mode of searching.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-given</code></dt>
+ <dd>Search for the search term in contacts' given names
+ (the second component of the vCard field <code>n</code>).
+ <tp:rationale>
+ As for <code>x-n-family</code>.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-online</code></dt>
+ <dd>For the search term "yes", search only for contacts who are
+ currently online. The results for other search terms are undefined.
+ <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
+ </dd>
+
+ <dt><code>x-adr-locality</code></dt>
+ <dd>Search for the search term as a locality or city (the fourth
+ component of the vCard field <code>adr</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC appear to support this.
+ </tp:rationale>
+ </dd>
+ </dl>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="AvailableSearchKeys" type="as" access="read"
+ tp:name-for-bindings="Available_Search_Keys">
+ <tp:docstring>
+ The set of search keys supported by this channel. Example values
+ include [""] (for protocols where several address fields are
+ implicitly searched) or ["x-n-given", "x-n-family", "nickname"]
+ (for XMPP XEP-0055, without extensibility via Data Forms).
+ This property cannot change during the lifetime of a channel.
+
+ <tp:rationale>
+ It can be in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal for round-trip reduction.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Contact_Search_Map">
+ <tp:docstring>A map from search keys to search terms.</tp:docstring>
+ <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
+ <tp:docstring>
+ The search key to match against
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Term" type="s">
+ <tp:docstring>
+ The term or terms to be searched for in the search key; depending on
+ the protocol and the server implementation, this may be matched by
+ exact or approximate equality, substring matching, word matching
+ or any other matching algorithm
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="Search" tp:name-for-bindings="Search">
+ <arg direction="in" name="Terms"
+ type="a{ss}" tp:type="Contact_Search_Map">
+ <tp:docstring>
+ A dictionary mapping search key names to the desired values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Send a request to start a search for contacts on this connection. This
+ may only be called while the <tp:member-ref>SearchState</tp:member-ref>
+ is Not_Started; a valid search request will cause the
+ <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
+ with the state In_Progress.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is no longer
+ Not_Started, so this method is no longer available.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The search terms included something this connection manager cannot
+ search for.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="SearchResultReceived"
+ tp:name-for-bindings="Search_Result_Received">
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>An integer handle for the contact, which will remain
+ valid at least until this Channel closes</tp:docstring>
+ </arg>
+ <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring>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>
+ interface. It is possible that a separate call to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+ would return more information than this signal provides.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a search result is received from the server.
+ </tp:docstring>
+ </signal>
+
+ <property name="Server" tp:name-for-bindings="Server"
+ type="s" access="read">
+ <tp:docstring>
+ <p>For protocols which support searching for contacts on multiple
+ servers with different DNS names (like XMPP), the DNS name of the
+ server being searched by this channel, e.g.
+ "characters.shakespeare.lit". Otherwise, the empty string.</p>
+
+ <tp:rationale>
+ <p>XEP 0055 defines a mechanism for XMPP clients to search services
+ of their choice for contacts, such as users.jabber.org (the "Jabber
+ User Directory").</p>
+ </tp:rationale>
+
+ <p>This property cannot change during the lifetime of the channel.
+ This property SHOULD be in the Allowed_Properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> if and only if the
+ protocol supports querying multiple different servers;
+ implementations SHOULD use a sensible default if possible if this
+ property is not specified in a channel request.</p>
+
+ <tp:rationale>
+ <p>This allows a client to perform searches on a protocol it knows
+ nothing about without requiring the user to guess a valid server's
+ hostname.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Connection_Interface_Contact_Info.xml b/extensions/Connection_Interface_Contact_Info.xml
new file mode 100644
index 0000000..99d6d35
--- /dev/null
+++ b/extensions/Connection_Interface_Contact_Info.xml
@@ -0,0 +1,393 @@
+<?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>
+ 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 at collabora.co.uk
+ EMAIL;TYPE=INTERNET:wee.ninja at 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 at collabora.co.uk']),
+ ('email', ['internet'], ['wee.ninja at 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 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 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: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: -->
diff --git a/extensions/all.xml b/extensions/all.xml
index 203961c..dc32abd 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -46,6 +46,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
<xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
+<xi:include href="Channel_Type_Contact_Search.xml"/>
+<xi:include href="Connection_Interface_Contact_Info.xml"/>
+
<tp:generic-types>
<tp:external-type name="Contact_Handle" type="u"
from="Telepathy specification"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list