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