Interacting Directly with the Address Book Database

Although many common Address Book database tasks depend on user interaction, in some cases appropriate for the application needs to interact with the Address Book database directly. There are several functions in the Address Book framework that provide this ability.

In order to provide a uniform user experience, it is important to use these functions only when they are appropriate. Rather than using these functions to create new view or navigation controllers, your program should call the provided view or navigation controllers whenever possible. For more information, see “Interacting Using UI Controllers.”

Remember that the Address Book database is ultimately owned by the user, so applications must be careful not to make unexpected changes to it. Generally, changes should be initiated or confirmed by the user. This is especially true for groups, because there is no interface on the device for the user to manage groups and undo your application’s changes.

Using Record Identifiers

Every record in the Address Book database has a unique record identifier. This identifier always refers to the same record, unless that record is deleted or the MobileMe sync data is reset. Record identifiers can be safely passed between threads. They are not guaranteed to remain the same across devices.

The recommended way to keep a long-term reference to a particular record is to store the first and last name, or a hash of the first and last name, in addition to the identifier. When you look up a record by ID, compare the record’s name to your stored name. If they don’t match, use the stored name to find the record, and store the new ID for the record.

To get the record identifier of a record, use the function ABRecordGetRecordID. To find a person record by identifier, use the function ABAddressBookGetPersonWithRecordID. To find a group by identifier, use the function ABAddressBookGetGroupWithRecordID. To find a person record by name, use the function ABAddressBookCopyPeopleWithName.

Working with Person Records

You can add and remove records from the Address Book database using the functions ABAddressBookAddRecord and ABAddressBookRemoveRecord. There are two ways to find a person in the Address Book database: by name, using the function ABAddressBookCopyPeopleWithName, and by record identifier, using the function ABAddressBookGetPersonWithRecordID.

To search for a person record in the Address Book database, use the function ABAddressBookCopyPeopleWithName. The framework only provides functionality to search by name. To accomplish other kinds of searches, you can use the functionABAddressBookCopyArrayOfAllPeople and then filter the results using the NSArray method filteredArrayUsingPredicate:.

To sort an array of people, use the function CFArraySortValues with the function ABPersonComparePeopleByName as the comparator and a context of the type ABPersonSortOrdering. The user‚Äôs desired sort order, as returned by ABPersonGetSortOrdering, is generally the preferred context.

The following code listing shows an example of sorting the entire Address Book database:

ABAddressBookRef addressBook = ABAddressBookCreate();

CFArrayRef people = ABAddressBookCopyArrayOfAllPeople(addressBook);

CFMutableArrayRef peopleMutable = CFArrayCreateMutableCopy(

                                          kCFAllocatorDefault,

                                          CFArrayGetCount(people),

                                          people

                                  );

 CFArraySortValues(

        peopleMutable,

        CFRangeMake(0, CFArrayGetCount(peopleMutable)),

        (CFComparatorFunction) ABPersonComparePeopleByName,

        (void*) ABPersonGetSortOrdering()

);

CFRelease(addressBook);

CFRelease(people);

CFRelease(peopleMutable);

Working with Group Records

You can find a specific group by record identifier using the function ABAddressBookGetGroupWithRecordID. You can also retrieve an array of all the groups in an address book using ABAddressBookCopyArrayOfAllGroups, and get a count of how many groups there are in an address book using the function ABAddressBookGetGroupCount.

You can modify the members of a group programatically. To add a person to a group, use the function ABGroupAddMember; to remove a person from a group, use the function ABGroupRemoveMember. Before a person record can be added to a group, it must already be saved to the Address Book database. If you need to add a new person record to a group and to the database at the same time, you must first add them to the address book database, save the database, and then add the person record to the group.