< Previous PageNext Page > Hide TOC

Managing Address Book Records

You can manage the people and groups within a user’s Address Book. This document explains how get 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.

Contents:

Accessing the Address Book
Adding and Removing People and Groups
Managing Groups
Accessing the User’s Record
Saving Your Changes
An Example

Accessing the Address Book

To get the address book for the currently logged-in user, use the ABAddressBook method sharedAddressBook. If you call these procedures more than once or try to create a new address book, you get a pointer to the shared address book.

Adding and Removing People and Groups

Adding a new person or group takes two steps: creating the appropriate record and then adding it to the user’s address book.

First, create the person or group. You must allocate and initialize the respective ABPerson or ABGroup object.

Second, add the person or group 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 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 methods addMember: and removeMember:. To get a list of all the groups a person is in, use the method parentGroups.

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 methods addSubgroup: and removeSubgroup:. The Address Book will not let you create a circular dependency. For example, if “Dog Lovers” is a subgroup of “Pet Lovers,” then “Pet Lovers” cannot be a subgroup of “Dog Lovers.” To get a list of all groups that another group is a subgroup of, use the method parentGroups.

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

Accessing the User’s Record

The 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 logged-in 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 method setMe:.

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 address book, use the ABAddressBook method save. To test whether there are unsaved changes to the address book, use the ABAddressBook method hasUnsavedChanges.

An Example

This brief 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 our subject’s first name and last), and the final save, which sends the changes to the address book:

ABAddressBook *addressBook;

ABPerson *newPerson;

addressBook = [ABAddressBook sharedAddressBook];

newPerson = [[[ABPerson alloc] init] autorelease];

[newPerson setValue:@”John”

    forProperty:kABFirstNameProperty];

[newPerson setValue:@"Doe"

        forProperty:kABLastNameProperty];

[addressBook addRecord:newPerson];

[addressBook save];

< Previous PageNext Page > Hide TOC