5.1.3 Contact Object

A Contact object represents a live view into the state of a single contact in the database. You can access the fields either with a contact's numeric field ID as contact[fieldid], or using the find method. Attempting to modify a contact while it has been locked for editing in another application will raise the exception ContactBusy.

class Contact

Contact objects have the following attributes:

id

The unique ID of this Contact. Read-only.

title

The title of this Contact. Read-only.

last_modified

The date/time when this Contact object was last modified. Read-only.

is_group

Returns 1 if this contact is a contact group. Returns 0 if normal contact entry. Read-only.

Contact objects have the following methods:

begin( )

Locks the contact for editing. This prevents other applications from modifying the contact for as long as the lock is held. This method will raise the exception ContactBusy if the contact has already been locked.

commit( )

Releases the lock and commits the changes made into the database.

rollback( )

Releases the lock and discards all changes that were made. The contact remains in the state it was before begin.

as_vcard( )

Returns the contact as a string in vCard format.

add_field( type [, value [, label=field_label][, location=location_spec]])

Adds a new field into this Contact. This method raises ContactBusy if the contact has been locked by some other application. type can be one of the supported field types as a string.

The following field types can be added:

city
company_name
country
date
dtmf_string
email_address
extended_address
fax_number
first_name
job_title
last_name
mobile_number
note
pager_number
phone_number
po_box
postal_address
postal_code
state
street_address
url
video_number
picture
second_name
voip
sip_id
personal_ringtone
share_view
prefix
suffix
push_to_talk
locationid_indication

The following field types are recognized but cannot be created at present:

first_name_reading
last_name_reading
speed_dial
thumbnail_image
voice_tag
wvid

All supported field types are passed as strings or Unicode strings, except for 'date' which is a float that represents Unix time. For more information on Unix time, see Section , Date and Time.

field_label is the name of the field shown to the user. If you do not pass a label, the default label for the field type is used.

location_spec, if given, must be 'home' or 'work'. Note that not all combinations of type and location are valid. The settings of the current contacts database in use determine which ones are valid.

find( [type=field_type][, location=field_location])

Finds the fields of this contact that match the given search specifications. If no parameters are given, all fields are returned.

__delitem__( fieldindex)

Deletes the given field from this contact. Note that since this will change the indices of all fields that appear after this field in the contact, and since the ContactField objects refer to the fields by index, old ContactField objects that refer to fields after the deleted field will refer to different fields after this operation.

See About this document... for information on suggesting changes.