1. Person and Group Records
Creating a new person record is simple. You use the function ABPersonCreate to create a new ABRecordRef. After that, you set its properties and add it to the address book object using ABAddressBookAddRecord function which we will discuss shortly.
To create a group, you use the ABGroupCreate
function. You set its properties (only one is defined) and add it to
the address book object as you would add any record using the ABAddressBookAddRecord function. You can add a person as a member to this group by using the ABGroupAddMember function. This function is declared as follows:
bool
ABGroupAddMember(ABRecordRef group,ABRecordRef person,CFErrorRef* error)
You can retrieve all members of a given group using the function ABGroupCopyArrayOfAll-Members which is declared as follows:
CFArrayRef ABGroupCopyArrayOfAllMembers(ABRecordRef group)
Each person has an image. You can retrieve that image using the function ABPersonCopyImageData which is declared as follows:
CFDataRef ABPersonCopyImageData(ABRecordRef person);
The previous function returns an NSData object containing the image data. You can then use the UIImage imageWithData: method to build a UIImage object from it.
To set the photo of a person, use the ABPersonSetImageData function which is declared as follows:
bool ABPersonSetImageData(ABRecordRef person, CFDataRef imageData,
CFErrorRef* error);
2. Address Book
In the previous sections, we
mostly covered records. In order to modify the actual database, however,
you need to use the address book.
You usually start by
creating an address book and initialize it with references to existing
records. You modify, add, and delete records. After that, you save the
address book.
To create an address book object, you use the function ABAddressBookCreate. This will return a reference to an address book, ABAddressBookRef, which we will discuss shortly.
ABAddressBookRef addressBook = ABAddressBookCreate();
To save an address book back to the database, you use the ABAddressBookSave function as shown below.
ABAddressBookSave(addressBook, NULL);
After finishing with an address book, you need to release it as follows:
CFRelease(addressBook);
Remember that all your
changes to the records are in memory. To persist these changes, you'll
need to save the address book object.
The following are some of the useful functions that operate on an address book object:
ABAddressBookGetPersonCount. This function returns the number of person records in the address book. The function is declared as follows:
CFIndex ABAddressBookGetPersonCount(ABAddressBookRef addressBook);
CFIndex is basically a signed long.
ABAddressBookGetGroupCount. This function returns the number of groups in the address book and it is declared as follows:
CFIndex ABAddressBookGetGroupCount(ABAddressBookRef addressBook);
ABAddressBookCopyArrayOfAllPeople. This function returns an array of all person records. The function is declared as follows:
CFArrayRef
ABAddressBookCopyArrayOfAllPeople(ABAddressBookRef addressBook);
Again, you need to release this array after you are finished with it.
ABAddressBookCopyArrayOfAllGroups. This function returns an array of all groups in the address book and is declared as follows:
CFArrayRef
ABAddressBookCopyArrayOfAllGroups(ABAddressBookRef addressBook);
ABAddressBookCopyPeopleWithName.
This function is actually pretty useful. You specify a query string and
it will return all person records matching this query. The function is
declared as follows:
CFArrayRef
ABAddressBookCopyPeopleWithName(ABAddressBookRef addressBook,
CFStringRef name);
ABAddressBookHasUnsavedChanges. This function will return YES if and only if there are changes to the address book that need saving. The function is declared as follows:
bool ABAddressBookHasUnsavedChanges(ABAddressBookRef addressBook);
ABAddressBookAddRecord.
This function is used to add a record (either person or group record)
to the address book. The function is declared as follows:
bool ABAddressBookAddRecord(ABAddressBookRef addressBook,
ABRecordRef record, CFErrorRef* error);
ABAddressBookRemoveRecord. This function is used to remove a record from the address book database. The function is declared as follows:
bool ABAddressBookRemoveRecord(ABAddressBookRef addressBook,
ABRecordRef record,CFErrorRef *error)
ABAddressBookRevert.
Using this function will discard all your modifications to the address
book. After calling this function, the address book will be refreshed
from the database. Also, after calling this function, you can see the
changes that other threads have committed after your last save. The
function is declared as follows:
ABAddressBookRevert(ABAddressBookRef addressBook);
If a record has been removed from the database before reverting, all properties of this record will return NULL.
3. Multithreading and Identifiers
Every record has a unique
identifier. This identifier should be used to communicate records
between threads. To retrieve the identifier of a person or a group
record, use the function ABRecordGetRecordID which is declared as follows:
ABRecordID ABRecordGetRecordID(ABRecordRef record);
We mentioned before that, in
multi-value properties, each value has a unique identifier. You retrieve
these values using an index. Moreover, if you need to store references
to specific entries, you need to store the unique identifier of that
value rather than its index. The function ABMultiValueGetIndexForIdentifier is used to retrieve the index for the value using its unique identifier. This function is declared as follows:
CFIndex ABMultiValueGetIndexForIdentifier(ABMultiValueRef multiValue,
ABMultiValueIdentifier identifier);
To retrieve the unique identifier of a value using its index, use the function ABMultiValueGetIdentifierAtIndex, which is declared as follows:
ABMultiValueIdentifier
ABMultiValueGetIdentifierAtIndex(ABMultiValueRef multiValue,
CFIndex index)
