The address book is an ABAddressBookRef obtained by calling ABAddressBookCreateWithOptions. This method is new in iOS 6. There are in fact no options to pass, so the first parameter is always nil. The important thing is the second parameter, a pointer to a CFErrorRef; if the result is nil, the CFErrorRef describes the error. The reason there can be an error is that the user can now deny your app access to the address book:

CFErrorRef err = nil;
ABAddressBookRef adbk = ABAddressBookCreateWithOptions(nil, &err);
if (nil == adbk) {
    NSLog(@"error: %@", err);
    return;
}

The very first time your app tries to access the address book, a system alert will appear, prompting the user to grant your app permission to access the user’s Contacts. You can modify the body of this alert by setting the “Privacy — Contacts Usage Description” key (NSContactsUsageDescription) in your app’s Info.plist to tell the user why you want to access the address book. This is a kind of “elevator pitch”; you need to persuade the user in very few words.

You can learn beforehand whether access has been explicitly denied by calling ABAddressBookGetAuthorizationStatus:

ABAuthorizationStatus stat = ABAddressBookGetAuthorizationStatus();
if (stat==kABAuthorizationStatusDenied ||
    stat==kABAuthorizationStatusRestricted) {
    NSLog(@"%@", @"no access");
    return;
}

If the user has denied your app access, you can’t make the system alert appear again. You can, of course, use some other interface to request that the user grant access in the Settings app, under Privacy → Contacts.

Another new iOS 6 function, ABAddressBookRequestAccessWithCompletion, is pointless, and I don’t recommend using it. If the user has already denied your app access, this function won’t make the system alert appear again; if the user has already granted your app access, this function is needless; and if the user has never seen the app before, the system alert will appear anyway when you try to access the address book. Thus this function does nothing that you can’t accomplish by a combination of ABAddressBookGetAuthorizationStatus and ABAddressBookCreateWithOptions.

Assuming that access has been granted, ABAddressBookCreateWithOptions returns an actual ABAddressBookRef object. This method’s name contains “Create,” so you must CFRelease the ABAddressBookRef when you’re finished with it, as discussed in Chapter 12. (But don’t release it until you are finished with it!) The address book’s data starts out exactly the same as the user’s Contacts data. If you make any changes to the data, they are not written through to the user’s real address book until you call ABAddressBookSave.

The primary constituent record of the address book database is the ABPerson. You’ll typically extract persons from the address book by using these functions:

The result of the latter two is a CFArrayRef. Their names contain “Copy,” so you must CFRelease the array when you’re finished with it. (I’m going to stop reminding you about memory management from here on.)

An ABPerson doesn’t formally exist as a type; it is actually an ABRecord (ABRecordRef), and by virtue of this has an ID, a type, and properties with values. To fetch the value of a property, you’ll call ABRecordCopyValue, supplying a property identifier to specify the property that interests you. ABPerson properties, as you might expect, include things like first name, last name, and email.

Working with a property value is a little tricky because the way you treat it depends on what type of value it is. You can learn a property value’s type dynamically by calling ABPersonGetTypeOfProperty, but usually you’ll know in advance. Some values are simple, but some are not. For example, a last name is a string, which is straightforward. But a person can have more than one email, so an email value is a “multistring.” To work with it, you’ll treat it as an ABMultiValue (ABMultiValueRef). This is like an array of values where each value also has a label and an identifier. The label categorizes (for example, a Home email as opposed to a Work email) but is not a unique specifier (because a person might have, say, two or more Work emails); the identifier is the unique specifier.

A person’s address is even more involved because not only is it an ABMultiValue (a person can have more than one address), but also a particular address is itself a dictionary (a CFDictionary). Each dictionary may have a key for street, city, state, country, and so on.

There is a lot more to parsing address book information, but that’s enough to get you started. We are now ready to illustrate by an example. Assume we have successfully obtained a reference to the address book, adbk, as I showed earlier. Now I’ll fetch my own record out of the address book database on my device and detect that I’ve got two email addresses:

ABRecordRef moi = nil;
CFArrayRef matts =
    ABAddressBookCopyPeopleWithName(adbk, (CFStringRef)@"Matt");
// might be multiple matts, but let's find the one with last name Neuburg
for (CFIndex ix = 0; ix < CFArrayGetCount(matts); ix++) {
    ABRecordRef matt = CFArrayGetValueAtIndex(matts, ix);
    CFStringRef last = ABRecordCopyValue(matt, kABPersonLastNameProperty);
    if (last && CFStringCompare(last, (CFStringRef)@"Neuburg", 0) == 0)
        moi = matt;
    if (last) CFRelease(last);
}
if (nil == moi) {
    NSLog(@"Couldn't find myself");
    if (matts) CFRelease(matts);
    if (adbk) CFRelease(adbk);
    return;
}
// parse my emails
ABMultiValueRef emails = ABRecordCopyValue(moi, kABPersonEmailProperty);
for (CFIndex ix = 0; ix < ABMultiValueGetCount(emails); ix++) {
    CFStringRef label = ABMultiValueCopyLabelAtIndex(emails, ix);
    CFStringRef value = ABMultiValueCopyValueAtIndex(emails, ix);
    NSLog(@"I have a %@ address: %@", label, value);
    if (label) CFRelease(label);
    if (value) CFRelease(value);
}
if (emails) CFRelease(emails);
if (matts) CFRelease(matts);
/*
output:
I have a _$!<Home>!$_ address: matt@tidbits.com
I have a _$!<Work>!$_ address: mattworking@tidbits.com
*/

You can also modify an existing record, add a new record (ABAddressBookAddRecord), and delete a record (ABAddressBookRemoveRecord). In this example, I’ll create a person called Snidely Whiplash with a Home email snidely@villains.com, add him to the database, and save the database:

ABRecordRef snidely = ABPersonCreate();
ABRecordSetValue(snidely, kABPersonFirstNameProperty, @"Snidely", nil);
ABRecordSetValue(snidely, kABPersonLastNameProperty, @"Whiplash", nil);
ABMutableMultiValueRef addr =
    ABMultiValueCreateMutable(kABStringPropertyType);
ABMultiValueAddValueAndLabel(addr, @"snidely@villains.com",
                             kABHomeLabel, nil);
ABRecordSetValue(snidely, kABPersonEmailProperty, addr, nil);
ABAddressBookAddRecord(adbk, snidely, nil);
ABAddressBookSave(adbk, nil);
if (addr) CFRelease(addr);
if (snidely) CFRelease(snidely);

Sure enough, if we then check the state of the database through the Contacts app, the new person exists (Figure 31.1).

Figure 31.1. A contact created programmatically

There are also groups (ABGroup); a group, like a person, is a record (ABRecord), so you can add a new group, delete an existing group, add a person to a group, and remove a person from a group (which is more than the Contacts app allows the user to do!). A group doesn’t own a person, nor a person a group; they are independent, and a person can be associated with multiple groups just as a group is associated with multiple persons. At an even higher level, there are sources (yet another kind of ABRecord): a person or group might be on the device, but it might instead come from an Exchange server or a CardDAV server. In this case the source really does, in a sense, own the group or person; a person can’t belong to two sources. A complicating factor, however, is that the same real person might appear in two different sources as two different ABPersons; to deal with this, it is possible for multiple persons to be linked, indicating that they are the same person. For a practical introduction to groups and sources, see Apple’s ABUIGroups sample code.

The Address Book UI framework puts a user interface, similar to the Contacts app, in front of common tasks involving the address book database. This is a great help, because designing your own interface to do the same thing would be tedious and involved. The framework provides four UIViewController subclasses:

These view controllers operate coherently with respect to the question of whether your app has access to the address book. For example, if the user has never granted or denied your app access to the address book, attempting to use ABPeoplePickerNavigationController will cause the system alert to appear, requesting access. If the user has denied your app access to the address book, the ABPeoplePickerNavigationController’s view will appear, but it will be empty (like Figure 30.2). ABNewPersonViewController, similarly, will lack interface for saving into the database if your app has been denied access, and the user’s only option will be to back out of the view controller. On the other hand, you can’t even get started usefully with ABPersonViewController if you don’t already have access, so if you lack access, you’ll discover that fact beforehand.

ABPeoplePickerNavigationController* picker =
    [ABPeoplePickerNavigationController new];
picker.peoplePickerDelegate = self; // note: not merely "delegate"
[self presentViewController:picker animated:YES completion:nil];

picker.displayedProperties = @[@(kABPersonEmailProperty)];

- (BOOL)peoplePickerNavigationController:
        (ABPeoplePickerNavigationController *)peoplePicker
        shouldContinueAfterSelectingPerson:(ABRecordRef)person
        property:(ABPropertyID)property
        identifier:(ABMultiValueIdentifier)identifier {
    ABMultiValueRef emails = ABRecordCopyValue(person, property);
    CFIndex ix = ABMultiValueGetIndexForIdentifier(emails, identifier);
    CFStringRef email = ABMultiValueCopyValueAtIndex(emails, ix);
    NSLog(@"%@", email); // do something with the email here
    if (email) CFRelease(email);
    if (emails) CFRelease(emails);
    [self dismissViewControllerAnimated:YES completion:nil];
    return NO;
}

CFErrorRef err = nil;
ABAddressBookRef adbk = ABAddressBookCreateWithOptions(nil, &err);
if (nil == adbk) {
    NSLog(@"error: %@", err);
    return;
}
CFArrayRef snides =
    ABAddressBookCopyPeopleWithName(adbk, (CFStringRef)@"Snidely Whiplash");
if (CFArrayGetCount(snides) < 1) {
    NSLog(@"%@", @"No Snidely!");
    return;
}
ABRecordRef snidely = CFArrayGetValueAtIndex(snides, 0);
ABPersonViewController* pvc = [ABPersonViewController new];
pvc.displayedPerson = snidely;
pvc.personViewDelegate = self;
[self.navigationController pushViewController:pvc animated:YES];
if (snides) CFRelease(snides);
if (adbk) CFRelease(adbk);

ABNewPersonViewController* npvc = [ABNewPersonViewController new];
npvc.newPersonViewDelegate = self;
UINavigationController* nc =
    [[UINavigationController alloc] initWithRootViewController:npvc];
[self presentViewController:nc animated:YES completion:nil];

- (void)newPersonViewController:
            (ABNewPersonViewController*)newPersonViewController
        didCompleteWithNewPerson:(ABRecordRef)person {
    if (nil != person) {
        // if we didn't have access, we wouldn't be here!
        ABAddressBookRef adbk = ABAddressBookCreateWithOptions(nil, nil);
        ABAddressBookRemoveRecord(adbk, person, nil);
        ABAddressBookSave(adbk, nil);
        CFStringRef name = ABRecordCopyCompositeName(person);
        NSLog(@"I have a person named %@", name);
        // do something with new person
        if (name) CFRelease(name);
        if (adbk) CFRelease(adbk);
    }
    [self dismissViewControllerAnimated:YES completion:nil];
}

ABUnknownPersonViewController* unk =
    [ABUnknownPersonViewController new];
unk.alternateName = @"Johnny Appleseed";
unk.message = @"Person who really knows trees";
unk.allowsAddingToAddressBook = YES;
ABRecordRef person = ABPersonCreate();
ABMutableMultiValueRef addr =
    ABMultiValueCreateMutable(kABStringPropertyType);
ABMultiValueAddValueAndLabel(addr, @"johnny@seeds.com",
                             kABHomeLabel, nil);
ABRecordSetValue(person, kABPersonEmailProperty, addr, nil);
unk.displayedPerson = person;
unk.unknownPersonViewDelegate = self;
[self.navigationController pushViewController:unk animated:YES];
if (person) CFRelease(person);
if (addr) CFRelease(addr);