[Telepathy-commits] [telepathy-spec/master] ContactInfo2: document vCard -> a(sasas) mapping in more detail
Will Thompson
will.thompson at collabora.co.uk
Fri Jan 16 08:03:16 PST 2009
---
spec/Connection_Interface_Contact_Info2.xml | 128 ++++++++++++++++++---------
1 files changed, 87 insertions(+), 41 deletions(-)
diff --git a/spec/Connection_Interface_Contact_Info2.xml b/spec/Connection_Interface_Contact_Info2.xml
index 80c4db6..1b39eff 100644
--- a/spec/Connection_Interface_Contact_Info2.xml
+++ b/spec/Connection_Interface_Contact_Info2.xml
@@ -22,10 +22,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List">
- <tp:docstring>
- Represents one piece of information about a contact, as modelled by a
- single vCard field.
- </tp:docstring>
<tp:member type="s" name="Field_Name">
<tp:docstring>
The name of the field; this is the lowercased name of a vCard field.
@@ -35,20 +31,97 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
<tp:member type="as" name="Field_Flags">
<tp:docstring>
- A list of vCard field types applicable to this field. For example, a
- contact's preferred home address would have flags 'home' and 'pref'.
+ A list of (lowercased) vCard field types applicable to this field.
+ For example, a contact's preferred home address would have flags
+ 'home' and 'pref'.
</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. A vCard field with
- multiple comma-separated values should be represented by several
+ 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.
+
+ <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
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
+ ;CB2 1SJ;UK
+ TEL;TYPE=VOICE,WORK:+44 1223 362967
+ 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']),
+ ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
+ 'Cambridgeshire','CB2 1SJ','UK']),
+ ('tel', ['voice','work'], ['+44 1223 362967']),
+ ('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>
<signal name="GotContactInfo" tp:name-for-bindings="Got_Contact_Info">
@@ -132,36 +205,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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 list of fields, where
- each fields represented by a triple with a field name, field type
- modifiers and field value.</p>
-
- <p>The set of well-known field names is as follows:</p>
- <dl>
- <dt>fn</dt><dd></dd>
- <dt>family-name</dt><dd></dd>
- <dt>given-name</dt><dd></dd>
- <dt>additional-names</dt><dd></dd>
- <dt>honorific-prefixes</dt><dd>?</dd>
- <dt>honorific-suffixes</dt><dd>?</dd>
- <dt>nickname</dt><dd></dd>
- <dt>bday</dt><dd></dd>
- <dt>tel</dt><dd></dd>
- <dt>email</dt><dd></dd>
- <dt>geo</dt><dd></dd>
- <dt>title</dt><dd></dd>
- <dt>role</dt><dd></dd>
- <dt>org</dt><dd></dd>
- <dt>note</dt><dd></dd>
- <dt>url</dt><dd></dd>
- <dt>post-office</dt><dd></dd>
- <dt>extended-address</dt><dd></dd>
- <dt>street-address</dt><dd></dd>
- <dt>locality</dt><dd></dd>
- <dt>region</dt><dd></dd>
- <dt>postal-code</dt><dd></dd>
- <dt>country</dt><dd></dd>
- </dl>
+ connection. Information is represented as a list of fields forming a
+ structured representation of a vCard (as defined by RFC 2426), using
+ field names and semantics defined therein.</p>
</tp:docstring>
</interface>
</node>
--
1.5.6.5
More information about the Telepathy-commits
mailing list