Accessing the Address Book

There are two ways to get a copy of the address book. The preferred way is to use the ABAddressBook method addressBook. The address book object that it returns should only be used on the same thread that it was created on, and can be used with the ABPerson method initWithAddressBook:.

If you're just making one-off lookups and edits, the ABAddressBook method sharedAddressBook may be used. However, this method can cause a significant decrease in performance, especially in a tight loop.

For example, you can replace code such as the following:

for (id item in someDataStructure) {

    ABPerson* person = [[ABPerson alloc] init];

    // Populate the person from the item

}

[[ABAddressBook sharedAddressBook] save];

With code like the following, yielding a significant performance increase:

ABAddressBook* tempBook = [ABAddressBook addressBook];

for (id item in someDataStructure) {

    ABPerson* person = [[ABPerson alloc] initWithAddressBook:tempBook];

    // Populate the person from the item

}

[tempBook save];

Adding and Removing Person and Group Records

The ABAddressBook class provides methods for accessing, adding, and removing group and person records. For example, use the groups method to get an array of all the group records in the database, or the people method to get all the person records.

Adding a new person or group record takes the following steps:

• Get the address book. The preferred way to do this is with the ABAddressBook method addressBook.

• Create the person or group record . You must allocate and initialize the respective ABPerson or ABGroup object. The preferred initializer is initWithAddressBook:.

• Add the record to the Address Book using the ABAddressBook method addRecord:.

To remove a person or group, use the ABAddressBook method removeRecord:.

Managing Groups

The Address Book framework lets you add people and subgroups to groups, as well as find out all groups that a person or subgroup is in.

To add and remove people from a group, use the addMember: and removeMember: methods. A person record can only be added to a group after it has been saved to the address book. To get a list of all the groups a person is in, use the parentGroups methods.

You can also add groups to a group. For example, a user could have a group called Pet Lovers that contains the groups Dog Lovers and Cat Lovers. To add and remove groups from another group, use the addSubgroup: and removeSubgroup: methods. You cannot create a cycle. For example, if Dog Lovers is a subgroup of Pet Lovers, then Pet Lovers cannot be a subgroup of Dog Lovers, directly or indirectly. To get a list of all groups that another group is a subgroup of, use the parentGroups methods.

To get lists of what’s in a group, use the members and subgroups methods.

Accessing the User’s Record

The currently logged-in user can specify a record that contains information about himself or herself. That lets your application find the name, address, or phone number of the user, so you can use it when filling out forms, for example. To get the logged-in user’s record, use the ABAddressBook method me. To set the logged-in user’s record, use the ABAddressBook setMe: methods.

Saving Your Changes

When you modify the Address Book database, those changes are made in memory, and not to the database itself. Unless you save those changes, they will be lost.

To save your changes to the database, use the ABAddressBook method save or saveAndReturnError:. To test whether there are unsaved changes, use the ABAddressBook method hasUnsavedChanges.

Notification of Changes

The Address Book posts notifications if any application, including your own, makes changes to the database. Typically, you observe these notifications to update any dependent view or model objects in your application. The Address Book framework sends two notifications: kABDatabaseChangedNotification to indicate that the current process has made a change, and kABDatabaseChangedExternallyNotification to indicate that another process has made a change. Use NSNotificationCenter to register for the notifications you are interested in. Note that these notifications are not sent until after the sharedAddressBook method of the ABAddressBook class or the C function ABGetSharedAddressBook has been invoked.

If your application is using the shared address book object (returned by the sharedAddressBook method), the changes have already been merged in automatically and are available immediately when you receive the change notification. Non-shared address book objects (returned by theaddressBook method) are generally used only for short time, and do not process change notifications automatically.

An Example

This Objective-C example adds a person named John Doe to the current user’s address book. Take note of how the code accesses the shared address book and how it allocates a new ABPerson object. Also note the properties used (in this case, just first name and last name), and the final save, which sends the changes to the user’s address book:

ABAddressBook *addressBook;

ABPerson *newPerson;

addressBook = [ABAddressBook sharedAddressBook];

newPerson = [[ABPerson alloc] init];

[newPerson setValue:@"John"

        forProperty:kABFirstNameProperty];

[newPerson setValue:@"Doe"

        forProperty:kABLastNameProperty];

[addressBook addRecord:newPerson];

[addressBook save];