Methods
GetContactInfo | (au: Contacts) | → | a{ua(sasas)}: ContactInfo | |
RequestContactInfo | (u: Contact) | → | a(sasas): Contact_Info | |
SetContactInfo | (a(sasas): ContactInfo) | → | nothing |
Signals
ContactInfoChanged | (u: Contact, a(sasas): ContactInfo) |
Properties
ContactInfoFlags | u (Contact_Info_Flag) | Read only | |
SupportedFields | a(sasuu) (Field_Specs) | Read only |
Types
VCard_Field | Simple Type | s | |
VCard_Type_Parameter | Simple Type | s | |
Contact_Info_Flag | Enum | u | |
Contact_Info_Field_Flags | Flags | u | |
Contact_Info_Map | Mapping | a{ua(sasas)} | |
Contact_Info_Field | Struct | (sasas) | |
Field_Spec | Struct | (sasuu) |
Description
An interface for requesting information about a contact on a given connection. Information is represented as a list of Contact_Info_Fields forming a structured representation of a vCard (as defined by RFC 2426), using field names and semantics defined therein.
Methods
GetContactInfo (au: Contacts) → a{ua(sasas)}: ContactInfo
Parameters
- Contacts — au (Contact_Handle_List)
Returns
- ContactInfo — a{ua(sasas)} (Contact_Info_Map)
RequestContactInfo (u: Contact) → a(sasas): Contact_Info
Parameters
- Contact — u (Contact_Handle)
Returns
- Contact_Info — a(sasas) (Contact_Info_Field_List)
Possible Errors
- Not Available
SetContactInfo (a(sasas): ContactInfo) → nothing
Parameters
- ContactInfo — a(sasas) (Contact_Info_Field_List)
Can_Set
, and may only be passed fields conforming to
SupportedFields.
Possible Errors
- Disconnected
- Network Error
- Permission Denied
- Not Available
- Not Implemented
- Invalid Argument
Signals
ContactInfoChanged (u: Contact, a(sasas): ContactInfo)
Parameters
- Contact — u (Contact_Handle)
- ContactInfo — a(sasas) (Contact_Info_Field_List)
Properties
ContactInfoFlags — u (Contact_Info_Flag)
SupportedFields — a(sasuu) (Field_Specs)
A list of field specifications describing the kinds of fields which may be passed to SetContactInfo. The empty list indicates that arbitrary vCard fields are permitted. This property SHOULD be the empty list, and be ignored by clients, if ContactInfoFlags does not contain the Can_Set Contact_Info_Flag.
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):
[ ('tel', ['home'], Parameters_Mandatory, 1), ('tel', ['cell'], Parameters_Mandatory, 1), ('adr', [], Parameters_Mandatory, 1), ('bday', [], Parameters_Mandatory, 1), ('email', ['internet'], Parameters_Mandatory, 1), ]
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 [ ('tel', ['home', 'cell'], 0, 4), ]
.
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).
Types
VCard_Field — s
VCard_Type_Parameter — s
Contact_Info_Flag — u
- Can_Set (1)
- Push (2)
Contact_Info_Field_Flags — u
- Parameters_Mandatory (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.
Contact_Info_Map — a{ua(sasas)}
- Handle — u (Contact_Handle)
- Contact_Info — a(sasas) (Contact_Info_Field_List)
Contact_Info_Field — (sasas)
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.
- tel
- A telephone number for the contact.
- 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.;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
would be represented by (in Python-like syntax):
[ ('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']) ]
- Field_Name — s
- Parameters — as
- Field_Value — 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'.
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.
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).
Field_Spec — (sasuu)
- Name — s (VCard_Field)
- Parameters — as (VCard_Type_Parameter_List)
- Flags — u (Contact_Info_Field_Flags)
- Max — u