This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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
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).
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:
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']) ]
Can_Set
, and may only be passed fields conforming to
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.
A list of field specifications describing the kinds of fields which may
be passed to
For example, a protocol in which arbitrary vCards were stored as-is 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', ['type=home'], Parameters_Exact, 1), ('tel', ['type=cell'], Parameters_Exact, 1), ('adr', [], Parameters_Exact, 1), ('bday', [], Parameters_Exact, 1), ('email', ['type=internet'], Parameters_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', ['type=home', 'type=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 a large subset of vCard (such as XMPP's XEP-0054).
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.
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.
Indicates that this field will be overwritten when the user's alias
is changed with
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
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
If used, this flag typically appears on either the 'nickname' or 'fn' field.
An interface for requesting information about a contact on a given
connection. Information is represented as a list of
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
On protocols with the Push flag set, UIs can connect to
We don't want clients to accidentally cause a ridiculous amount of network traffic.
The same value that would be returned by