Managing Address Book Records
You can manage the people and groups within a user’s address book. This article explains how to obtain the user’s address book, add and remove people and groups from that address book, manage groups, find the record that corresponds to the logged-in user, and save your changes.
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
methodaddressBook
.Create the person or group record . You must allocate and initialize the respective
ABPerson
orABGroup
object. The preferred initializer isinitWithAddressBook:
.Add the record to the Address Book using the
ABAddressBook
methodaddRecord:
.
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]; |
Copyright © 2002, 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-04-23