iOS Components and Frameworks: Understanding the Advanced Features of the iOS SDK (2014)

---

Reading Multivalues from the Address Book

Often, you will encounter Address Book objects that can store multiple values, such as phone numbers, email addresses, or street addresses. These are all accessed using ABMultiValueRefs. The process is similar to that for single values with one additional level of complexity.

The first thing you need to do when working with multivalues, such as phone numbers, is copy the value of the multivalue property. In the following code example, use kABPersonPhoneProperty from the record that was set in the previous section. This provides you with anABMultiValueRef called phoneNumbers.

A check is then needed to make sure that the contact has at least one phone number using the ABMultiValueGetCount function. Here, you can either loop through all the phone numbers or pull the first one you find (as in the example). Additionally, you will want to handle the “no phone number found” case. From here, you need to create a new string and store the value of the phone number into it. This is done using the ABMultiValueCopyValueAtIndex call, the first parameter of the ABMultiValueRef followed by the index number.

ABMultiValueRef phoneNumbers = ABRecordCopyValue(record, kABPersonPhoneProperty);

if (ABMultiValueGetCount(phoneNumbers) > 0)
{
CFStringRef phoneNumber = ABMultiValueCopyValueAtIndex(phoneNumbers, 0);

NSLog(@"Phone Number: %@", phoneNumber);

CFRelease(phoneNumber);
}

CFRelease(phoneNumbers);

Understanding Address Book Labels

In the preceding section, you retrieved a phone number from the contact database; however, you know it only by its index number. Although this is helpful to developers, it is next to useless for users. You will want to retrieve the label that was used in the contact database. In the next code snippet, the example from the preceding section will be expanded on.

The first step to attaining a label for a multivalue reference is to call ABMultiValueCopyLabelAtIndex. Call this function with the same parameters you used to get the value of the multivalue object. This function will return a nonlocalized string, such as "_$!<Mobile>!$_". Although this is much more helpful than a raw index number, it is still not ready for user presentation.

You will need to run the returned label through a localizer to get a human-readable string. Do so using the ABAddressBookCopyLocalizedLabel using the raw value CFStringRef that was just set. In the example this will now return Mobile.

ABMultiValueRef phoneNumbers = ABRecordCopyValue(record, kABPersonPhoneProperty);

if (ABMultiValueGetCount(phoneNumbers) > 0)
{
CFStringRef phoneNumber = ABMultiValueCopyValueAtIndex(phoneNumbers, 0);

CFStringRef phoneTypeRawString = ABMultiValueCopyLabelAtIndex(phoneNumbers, 0);

NSString *localizedPhoneTypeString = (NSString *)ABAddressBookCopyLocalizedLabel(phoneTypeRawString);

NSLog(@"Phone %@ [%@]", phoneNumber, localizedPhoneTypeString);

CFRelease(phoneNumber);
CFRelease(phoneTypeRawString);
CFRelease(localizedPhoneTypeString);
}

Look back at the example in Figure 5.1—you now have the skill set to fully implement this functionality.

Working with Addresses

In the preceding two sections, you saw how to access single-value information and then how to access multivalue data. In this section, you will work with a bit of both as you learn how to handle street addresses that you encounter in the contact database. If you launch the sample app and tap the toggle button in the navigation bar, you will see that the addresses are now shown instead of phone numbers in the table cells (see Figure 5.2).

Figure 5.2 The sample app showing addresses pulled from the contact database.

You will begin working with addresses in the same manner as you did for the phone multivalues. First attain an ABMultiValueRef for the kABPersonAddressProperty. Then you will need to make sure that at least one valid address was found. When you query the multivalue object with an index value, instead of getting back a single CFStringRef, you are returned a dictionary containing the address components. After you have the dictionary, you can pull out specific information using the address constants shown in Table 5.2.

ABMultiValueRef streetAddresses = ABRecordCopyValue(record,
kABPersonAddressProperty);

if (ABMultiValueGetCount(streetAddresses) > 0)
{
NSDictionary *streetAddressDictionary = (NSDictionary *)ABMultiValueCopyValueAtIndex(streetAddresses, 0);

NSString *street = [streetAddressDictionary objectForKey: (NSString *)kABPersonAddressStreetKey];

NSString *city = [streetAddressDictionary objectForKey: NSString *)kABPersonAddressCityKey];

NSString *state = [streetAddressDictionary objectForKey: (NSString *)kABPersonAddressStateKey];

NSString *zip = [streetAddressDictionary objectForKey: (NSString *)kABPersonAddressZIPKey];

NSLog(@"Address: %@ %@, %@ %@", street, city, state, zip);

CFRelease(streetAddressDictionary);
}

Table 5.2 Address Components

Address Book Graphical User Interface

As mentioned in the beginning of this chapter, user interfaces are provided as part of the Address Book framework. In this section, a look is taken at those interfaces and how they can save an incredible amount of implementation time. Whether it is editing an existing contact, creating a new contact, or allowing your user to pick a contact from a list, Apple has you covered.

People Picker

You will undoubtedly want your user to be able to simply select a contact from a list. For example, let’s say you are writing an app that allows you to send a vCard over Bluetooth to another user; you will need to let your user select which contact card she wants to send. This task is easily accomplished using ABPeoplePickerNavigationController. You can turn on this functionality in the sample app by uncommenting line 63 ([self showPicker: nil];) in the RootViewController.m class.

Your class will first need to implement ABPeoplePickerNavigationControllerDelegate. You can then create a new picker controller using the following code snippet:

ABPeoplePickerNavigationController *picker = [[ABPeoplePickerNavigationController alloc] init];

picker.peoplePickerDelegate = self;
[self presentViewController:picker animated:YES completion:nil];
[picker release];

This displays a people picker to the user (see Figure 5.3).

Figure 5.3 The built-in people picker.

You will also need to implement three delegate methods to handle callbacks from the user interacting with the people picker. The first method you need handles the Cancel button being tapped by a user; if you do not dismiss the modal in this method, the user has no way to dismiss the view.

- (void)peoplePickerNavigationControllerDidCancel:(ABPeoplePickerNavigationController *)peoplePicker
{
[self dismissViewControllerAnimated:YES completion:nil];
}

When picking people, there are two sets of data you might be concerned with. The first is the contact itself, and by extension all the contact information. The second is a specific property, such as a specific phone number or email address from a contact. You can handle both of these cases. The first step will look at selecting an entire person’s contact information.

- (BOOL)peoplePickerNavigationController: (ABPeoplePickerNavigationController *)peoplePicker shouldContinueAfterSelectingPerson: (ABRecordRef)person
{
NSLog(@"You have selected: %@", person);

[self dismissViewControllerAnimated:YES completion:nil];

return NO;
}

In this code snippet, NO is returned for peoplePickerNavigationController:shouldContinueAfterSelectingPerson:. This informs the picker that you do not intend to drill deeper into the contact and you only want to select an ABRecordRef for a person. As with the previous example, you must dismiss the modal view controller when you are done with it. If you do want to dive deeper, you will need to return YES here and implement the following delegate method. Do not forget to remove thedismissModalViewControllerAnimated:completion call from the previous method if you intend to drill deeper.

- (BOOL)peoplePickerNavigationController: (ABPeoplePickerNavigationController *)peoplePicker shouldContinueAfterSelectingPerson:(ABRecordRef)person property:(ABPropertyID)property identifier:(ABMultiValueIdentifier)identifier
{

NSLog(@"Person: %@\nProperty:%i\nIdentifier:%i", person,property, identifier);

[self dismissViewControllerAnimated:YES completion:nil];

return NO;
}

Customizing the People Picker

There might be times when you want to allow the picker to choose only from phone numbers or street addresses and ignore the other information. You can do so by modifying the previous method of creating the people picker to match the following example, which will show only phone numbers.

ABPeoplePickerNavigationController *picker = [[ABPeoplePickerNavigationController alloc] init];

picker.displayedProperties = [NSArray arrayWithObject:[NSNumber numberWithInt:kABPersonPhoneProperty]];

picker.peoplePickerDelegate = self;
[self presentViewController:picker animated:YES completion:nil];

You also can specify a specific address book for the picker using the addressBook property. If you do not set this, a new address book is created for you when the people picker is presented.

Editing and Viewing Existing Contacts Using ABPersonViewController

Most of the time, you will want to simply display or edit an existing contact using the built-in Address Book user interfaces. In the sample app, this is the default action when a table cell is selected. You first create a new instance of ABPersonViewController and set the delegate and the person to be displayed, which is an instance of ABRecordRef. This approach will display the contact, as shown in Figure 5.4.

ABPersonViewController *personViewController = [[ABPersonViewController alloc] init];

personViewController.personViewDelegate = self;

personViewController.displayedPerson = personToDisplay;

[self.navigationController pushViewController:personViewController animated:YES];

[personViewController release];

Figure 5.4 The built-in contact viewer.

If you want to allow editing of the contact, you simply add another property to the code snippet.

personViewController.allowsEditing = YES;

If you want to allow actions in the contact, such as Send Text Message or FaceTime buttons, you can add an additional allowsActions property.

personViewController.allowsActions = YES;

In addition to the steps you have already implemented, you need to be aware of one required delegate method, personViewController:shouldPerformDefaultActionForPerson:property:identifier. This is called when the user taps on a row such as a street address or a phone number. If you would like the app to perform the default action, such as call or open Maps.app, return YES; if you would like to override these behaviors, return NO.

- (BOOL)personViewController:(ABPersonViewController *)personViewController shouldPerformDefaultActionForPerson:(ABRecordRef)person property:(ABPropertyID)property identifier:(ABMultiValueIdentifier)identifierForValue
{

return YES;
}

Creating New Contacts Using ABNewPersonViewController

When you want to create a new contact, the sample app has a plus button in the navigation bar that allows you to create a new contact using the built-in user interfaces, shown in Figure 5.5. The next code snippet is straightforward with one caveat: The ABNewPersonViewControllermust be wrapped inside of a UINavigationController to function properly.

ABNewPersonViewController *newPersonViewController = [[ABNewPersonViewController alloc] init];

UINavigationController *newPersonNavigationController = [[UINavigationController alloc] initWithRootViewController:newPersonViewController];

[newPersonViewController setNewPersonViewDelegate: self];

[self presentViewController:newPersonNavigationController animated:YES completion:nil];

[newPersonNavigationController release];
[newPersonViewController release];

Figure 5.5 The built-in new person view controller.

There is also a single delegate method that is called when the user saves the contact. After you verify that you have a valid person object being returned, you need to call ABAddressBookAddRecord with the address book you want to add the person into, followed byABAddressBookSave. If you have an array populated with the address book entries like the sample app, you will need to repopulate that array to see the changes.

- (void)newPersonViewController:(ABNewPersonViewController *)newPersonViewController didCompleteWithNewPerson:(ABRecordRef)person
{
if(person)
{
CFErrorRef error = NULL;

ABAddressBookAddRecord(addressBook, person, &error);
ABAddressBookSave(addressBook, &error);
if (error != NULL)
{
NSLog(@"An error occurred");
}
}

[self dismissViewControllerAnimated:YES completion:nil];

}

Programmatically Creating Contacts

What if you want to programmatically create a new contact instead of using the built-in graphical interface? Think about a contact-sharing app again. You don’t want to have to put the user through an interface when you can have the contact information entered programmatically.

In the sample project, uncomment line 66 ([self programmaticallyCreatePerson];) of the RootViewController.m and run it; you will notice that a new person appears in the contact list. The first step you will need to take in creating a new person is to generate a new empty ABRecordRef. You do this with the ABPersonCreate() method. You will also want to create a new NULL pointed CFErrorRef.

ABRecordRef newPersonRecord = ABPersonCreate();

CFErrorRef error = NULL;

Setting single-value properties is very straightforward, achieved by calling ABRecordSetValue with the new ABRecordRef as the first parameter, followed by the property constant, then the value, followed by the address of the CFErrorRef.

ABRecordSetValue(newPersonRecord, kABPersonFirstNameProperty, @"Tyler", &error);

ABRecordSetValue(newPersonRecord, kABPersonLastNameProperty, @"Durden", &error);

ABRecordSetValue(newPersonRecord, kABPersonOrganizationProperty, @"Paperstreet Soap Company", &error);

ABRecordSetValue(newPersonRecord, kABPersonJobTitleProperty, @"Salesman", &error);

Setting the phone number multivalue is slightly more complex than with a single-value object. You first need to create a new ABMutableMultiValueRef using the ABMultiValueCreateMutable() method with the type of multivalue property you are creating; in this instance, the phone property.

In the sample app, three different phone numbers are created, each with a different label property. After you finish adding new phone number values, you will need to call ABRecordSetValue with the new person record, the multivalue constant you are setting, and the mutable multivalue reference you just populated. Don’t forget to release the memory when you are done.

ABMutableMultiValueRef multiPhoneRef = ABMultiValueCreateMutable(kABMultiStringPropertyType);

ABMultiValueAddValueAndLabel(multiPhoneRef, @"1-800-555-5555", kABPersonPhoneMainLabel, NULL);

ABMultiValueAddValueAndLabel(multiPhoneRef, @"1-203-426-1234", kABPersonPhoneMobileLabel, NULL);

ABMultiValueAddValueAndLabel(multiPhoneRef, @"1-555-555-0123", kABPersonPhoneIPhoneLabel, NULL);

ABRecordSetValue(newPersonRecord, kABPersonPhoneProperty, multiPhoneRef, nil);

CFRelease(multiPhoneRef);

Email addresses are handled in the same manner as phone numbers. An example of an email entry is shown in the sample app. Street addresses are handled slightly differently, however.

You will still create a new mutable multivalue reference, but in this step, you also create a new mutable NSDictionary. Set an object for each key of the address that you want to set (refer to Table 5.2 for a complete list of values). Next, you need to add a label for this street address. In the code sample that follows, kABWorkLabel is used. When done, save the data in the same fashion as the phone or email entry.

ABMutableMultiValueRef multiAddressRef = ABMultiValueCreateMutable(kABMultiDictionaryPropertyType);

NSMutableDictionary *addressDictionary = [[NSMutableDictionary alloc] init];

[addressDictionary setObject:@"152 Paper Street" forKey:(NSString *) kABPersonAddressStreetKey];

[addressDictionary setObject:@"Delaware" forKey:(NSString *)kABPersonAddressCityKey];

[addressDictionary setObject:@"MD" forKey:(NSString *)kABPersonAddressStateKey];

[addressDictionary setObject:@"19963" forKey:(NSString *)kABPersonAddressZIPKey];

ABMultiValueAddValueAndLabel(multiAddressRef, addressDictionary, kABWorkLabel, NULL);

ABRecordSetValue(newPersonRecord, kABPersonAddressProperty, multiAddressRef, &error);

CFRelease(multiAddressRef); [addressDictionary release];

After you set up the new contact with all the information you want to enter, you need to save it and check for any errors that occurred during the process. In the sample app, the array and the table are reloaded to display the new entry.

ABAddressBookAddRecord(addressBook, newPersonRecord, &error);
ABAddressBookSave(addressBook, &error);

if(error != NULL)
{
NSLog(@"An error occurred");
}

Summary

This chapter covered the Address Book frameworks and how to leverage them into your iOS apps. You learned about the limitations and privacy concerns of the Address Book, as well as the importance of implementing it into appropriate apps.

Exploring the included sample app, you gained insightful and practical knowledge on how to get the Address Book frameworks quickly up and running. Additionally, you learned how to work with both retrieving and inserting new data into an address book both using Apple’s provided graphical user interface and programmatically. You should now have a strong understanding of the Address Book frameworks and be comfortable adding them into your iOS apps.

Exercises

1. Sort the address book by first or last name using the ABAddressBookCopyArrayOfAllPeopleInSourceWithSortOrdering method. Experiment with different sorting options.

2. Create a new person view controller, which allows the user to enter fields of his or her own. When the user is done entering information programmatically, save the new contact into the address book.