Tp::ContactInfoField Struct Reference [Structure types]

#include <TelepathyQt4/Types>

List of all members.

Public Attributes

• QString fieldName
• QStringList parameters
• QStringList fieldValue

---

Detailed Description

Structure type generated from the specification.

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:

fn

The contact's full name, formatted to their liking

n

The contact's full name, divided into five parts: family name, given name, additional names, honorific prefixes, and honorific suffixes

org

The contact's organisation, divided into the organization's name possibly followed by one or more organizational unit names.

adr

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.

label

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

tel

A telephone number for the contact.

email

An email address for the contact.

For example, the following vCard:

    BEGIN:vCard
    VERSION:3.0
    FN:Wee Ninja
    N;LANGUAGE=ja:Ninja;Wee;;;-san
    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
    URL:http://www.thinkgeek.com/geektoys/plush/8823/
    NICKNAME:HR Ninja,Enforcement Ninja
    END:vCard

would be represented by (in Python-like syntax):

 [
   ('fn', [], ['Wee Ninja']),
   ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
   ('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']),
   ('email', ['type=internet'], ['wee.ninja@example.com']),
   ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
   ('nickname', [], ['HR Ninja']),
   ('nickname', [], ['Enforcement Ninja'])
 ]

---

Member Data Documentation

QString Tp::ContactInfoField::fieldName

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".

QStringList Tp::ContactInfoField::parameters

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'.

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

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.

<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>

QStringList Tp::ContactInfoField::fieldValue

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, such as 'nickname', 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 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).

<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>