Basic Concepts

To be able to use contact features in your application, you must first understand how the basic concepts of contact and person are related, and how the contact information is stored in the Contacts database using records and views.

Contacts and Persons

The contact and person are 2 different concepts:

  • A contact object is a collection of information related to a physical person, such as their name, phone numbers, addresses, email addresses, birthday, and organizations. A contact object is always associated with a specific address book. When a contact is successfully added, a contact ID, which is unique within the address book, is given to the contact.

  • A person object is an aggregation of 1 or more contacts associated with the same physical person. A person is created automatically when a contact record is inserted in the Contacts database. A person record cannot be created directly, and every contact must be linked to at least 1 person.

The following figure illustrates the contact structure. The example shows 3 instances of the same contact stored in different address books. Person1 is an aggregation of all 3 instances (Contact1, Contact2, and Contact3).

Figure: Contact structure

Contact structure

Records and Views

Records and views are important concepts in the Contacts API. Although a record represents an actual record in the internal database, you can consider it a piece of information, like an address, a phone number, or a group of contacts. A record can be a complex set of data, containing other data. For example, an address record contains country, region, and street information.

Records contain properties of basic types:

  • integer
  • string
  • boolean
  • long integer
  • long long integer (lli)
  • double

The following table lists the functions for setting and getting different record property types.

Table: Functions for specific record property types

Property type Setter function Getter function
string contacts_record_set_str() contacts_record_get_str()
integer contacts_record_set_int() contacts_record_get_int()
boolean contacts_record_set_bool() contacts_record_get_bool()
long long integer contacts_record_set_lli() contacts_record_get_lli()
double contacts_record_set_double() contacts_record_get_double()

A view is a structure describing the record properties, where the property elements have their data types and names. For example, the _contacts_contact view describes the properties of the contact record, part of which is listed in the following table.

Table: Some contact record properties

Property ID Type Description
uri string Identifier of this contact view
id integer Database record ID of the contact
display_name string Display name of the contact
is_favorite boolean boolean value indicating whether the contact is a favorite
name Record _contacts_name child record containing the contact name details
company Record _contacts_company child record containing the contact’s company details
address Record _contacts_address child record containing the contact address details

Every view has a special field (_uri) that uniquely identifies the view. In many cases, you must provide the _uri value to indicate what type of record you want to operate on. The following example code creates a contact record and obtains the record handle using the _contacts_contact._uri property:

contacts_record_h contact = NULL;

contacts_record_create(_contacts_contact._uri, &contact);