VCard_Field — s

VCard_Type_Parameter — s

Contact_Info_Flags — u

• Can_Set (1)
Indicates that SetContactInfo is supported on this connection.
• Push (2)
Indicates that the protocol pushes all contacts' information to the connection manager without prompting. If set, ContactInfoChanged will be emitted whenever contacts' information changes.

Contact_Info_Field_Flags — u

• Parameters_Exact (1)

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.

If absent, and the list of allowed parameters is non-empty, any (possibly empty) subset of that list may be used.

If absent, and the list of allowed parameters is empty, any parameters may be used.

• Overwritten_By_Nickname (2)

Indicates that this field will be overwritten when the user's alias is changed with SetAliases or when the Account's Nickname is updated. Clients that allow the editing of the Alias and the ContactInfo in the same location should hide fields with this flag.

Rationale:

If a client allowed the user to edit both the nickname and the ContactInfo field at the same time, the user could set them to two different values even though they map to the same property. This would result in surprising behavior where the second value would win over the first.

In addition to hiding this field when editing ContactInfo together with the user's nickname, it is recommended that clients call SetContactInfo before setting the user's nickname.

Rationale:

This ensures that if the user changes the nickname, the correct value will get set even if the stale nickname is mistakenly sent along with SetContactInfo.

If used, this flag typically appears on either the 'nickname' or 'fn' field.

Contact_Info_Map — a{ua(sasas)}

• Handle — u (Contact_Handle)
• Contact_Info — a(sasas) (Contact_Info_Field_List)

Contact_Info_Field — (sasas)

   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

[
  ('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'])
]

• Field_Name — s
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".
• Parameters — as

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

Rationale:

The type parameter 'type' is likely to be the most common, but there can be others, such as 'language=en'.

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.

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.
• Field_Value — as

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

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

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?

Field_Spec — (sasuu)

• Name — s (VCard_Field)
A vCard field name, such as 'tel'.
• Parameters — as (VCard_Type_Parameter_List)
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_Exact flag is not set, any vCard type parameters may be used.
• Flags — u (Contact_Info_Field_Flags)
Flags describing the behaviour of this field.
• Max — u
Maximum number of instances of this field which may be set. MAXUINT32 is used to indicate that there is no limit.