Interface org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

GetContactInfo (au: Contacts) → a{ua(sasas)}: ContactInfo
RefreshContactInfo (au: Contacts) → nothing
RequestContactInfo (u: Contact) → a(sasas): Contact_Info
SetContactInfo (a(sasas): ContactInfo) → nothing

Signals

ContactInfoChanged (u: Contact, a(sasas): ContactInfo)

Properties

ContactInfoFlags u (Contact_Info_Flags) Read only
SupportedFields a(sasuu) (Field_Specs) Read only

Types

VCard_Field Simple Type s
VCard_Type_Parameter Simple Type s
Contact_Info_Flags Enum u
Contact_Info_Field_Flags Flags u
Contact_Info_Map Mapping a{ua(sasas)}
Contact_Info_Field Struct (sasas)
Field_Spec Struct (sasuu)
WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.17.18. (as a draft)
Objects implementing this interface must also implement:

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.

On some protocols, information about your contacts is pushed to you, with change notification; on others, like XMPP, the client must explicitly request the avatar, and has no way to tell whether it has changed without retrieving it in its entirety. This distinction is exposed by ContactInfoFlags containing the Push flag.

On protocols with the Push flag set, UIs can connect to ContactInfoChanged, call GetContactInfo once at login for the set of contacts they are interested in, and then be sure they will receive the latest contact info. On protocols like XMPP, clients can do the same, but will receive (at most) opportunistic updates if the info is retrieved for other reasons. Clients may call RequestContactInfo or RefreshContactInfo to force a contact's info to be updated, but MUST NOT do so unless this is either in response to direct user action, or to refresh their own cache after a number of days.

We don't want clients to accidentally cause a ridiculous amount of network traffic.

Methods

(Permalink)

GetContactInfo (au: Contacts) → a{ua(sasas)}: ContactInfo

Parameters

Returns

  • ContactInfo — a{ua(sasas)} (Contact_Info_Map)
    • A dictionary mapping contact handles to information, whose keys are the subset of the requested list of handles for which information was cached.
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.
(Permalink)

RefreshContactInfo (au: Contacts) → nothing

Added in 0.19.UNRELEASED.

Parameters

Retrieve information for the given contact, requesting it from the network if an up-to-date version is not cached locally. This method SHOULD return immediately, emitting ContactInfoChanged when the contacts' updated contact information is returned.
This method allows a client with cached contact information to update its cache after a number of days.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
(Permalink)

RequestContactInfo (u: Contact) → a(sasas): Contact_Info

Parameters

Returns

Retrieve information for a contact, requesting it from the network if it is not cached locally.
This method is appropriate for an explicit user request to show a contact's information; it allows a UI to wait for the contact info to be returned.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Not Available
    • The contact's information could not be retrieved.
(Permalink)

SetContactInfo (a(sasas): ContactInfo) → nothing

Parameters

Set new contact information for this connection, replacing existing information. This method is only suppported if ContactInfoFlags contains Can_Set, and may only be passed fields conforming to SupportedFields.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Permission Denied
    • The user is not permitted to perform the requested operation.
  • Not Available
    • Raised when the requested functionality is temporarily unavailable.
  • Not Implemented
    • Setting your own information is not supported on this protocol.
  • Invalid Argument
    • The supplied fields do not match the restrictions specified by SupportedFields.

Signals

(Permalink)

ContactInfoChanged (u: Contact, a(sasas): ContactInfo)

Parameters

  • Contact — u (Contact_Handle)
    • An integer handle for the contact whose info has changed.
  • ContactInfo — a(sasas) (Contact_Info_Field_List)
    • An array of fields representing information about this contact.
Emitted when a contact's information has changed or been received for the first time on this connection.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

ContactInfoFlags — u (Contact_Info_Flags)

Read only

An integer representing the bitwise-OR of flags on this connection.

This property MAY change, without change notification, at any time before the connection moves to status Connection_Status_Connected. It MUST NOT change after that point.

Some XMPP servers, like Facebook Chat, do not allow the vCard to be changed (and so would not have the Can_Set flag). Whether the user's server is one of these cannot necessarily be detected until quite late in the connection process.

(Permalink)

SupportedFields — a(sasuu) (Field_Specs)

Read only

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 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'], Params_Exact, 1),
  ('tel', ['cell'], Params_Exact, 1),
  ('adr', [], Params_Exact, 1),
  ('bday', [], Params_Exact, 1),
  ('email', ['internet'], Params_Exact, 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).

This property MAY change, without change notification, at any time before the connection moves to status Connection_Status_Connected. It MUST NOT change after that point.

Some XMPP servers, like Google Talk, only allow a small subset of the "vcard-temp" protocol. Whether the user's server is one of these cannot be detected until quite late in the connection process.

Types

Simple Type (Permalink)

VCard_Field — s

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.
Simple Type (Permalink)

VCard_Type_Parameter — s

A type parameter as defined by RFC 2426, such as "type=cell" or "language=en".
Enum (Permalink)

Contact_Info_Flags — u

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.
  • 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.
Flags (Permalink)

Contact_Info_Field_Flags — u

Flags describing the behaviour of a vCard field.
  • Params_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.

Mapping (Permalink)

Contact_Info_Map — a{ua(sasas)}

A dictionary whose keys are contact handles and whose values are contact information..
Struct (Permalink)

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.
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'])
]
  • 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'.

    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.

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

    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?
Struct (Permalink)

Field_Spec — (sasuu)

A struct describing a vCard field, with parameters, that may be passed to SetContactInfo on this Connection.
  • 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_Params_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.