< Previous PageNext Page > Hide TOC

Accessing Address Book Records

Once you have a record, you can retrieve the data within it. This article shows you how the data is organized and how to access it. It shows how to access properties from a records property list, how to handle properties that can have more than one value (such as addresses and phone numbers), how to get localized names for properties and labels, and how to associate a picture with a person.

Contents:

Using Property Lists
Using Multivalue Lists
Associating a Picture With a Person
Getting Localized Names for Properties and Labels
An Example
Using the People Picker
People Picker Example

Using Property Lists

Both groups and people store their data in property lists. This lets your application add properties to the Address Book records that other applications will ignore. See “Adding Properties to Address Book Records.”

To get data from them, such as a group’s description or a person’s first name, use the method valueForProperty: method or the C function ABRecordCopyValue. For example, to get the first name for aPerson, use

[aPerson valueForProperty:kABFirstNameProperty];

To set data, use the setValue:forProperty: method. For example, to set the name of dataGroup, use

[aGroup setValue:@"Book Club" forProperty:kABGroupNameProperty];

To find out the names of the properties for ABPerson and ABGroup, refer to the following documentation list:

Other properties can be found in ABGlobals.h for Objective-C or ABGlobalsC.h for procedural C.

Using Multivalue Lists

Many properties can have multiple values. For example, a person can have several addresses, including work, home, summer home, and mailing addresses. These properties are stored as multivalue lists, of type ABMultiValue or ABMultiValueRef. Each item in a multivalue list has a numeric index, a unique identifier, a string label (such as "Home" or "Work"), and a value. Every value in the multivalue list must be of the same type. The label does not need to be unique; after all, someone could have more than one home or work address. You access the items with the numeric index. To add an item to a multivalue list, use the method addValue:withLabel:. To retrieve an item, use the methods valueAtIndex: and labelAtIndex:.

If you want to save a reference to a specific value, use the unique identifier. The numeric index may change as the user adds and removes values, but the identifier is guaranteed never to change. To get the unique identifier for a value at a particular index, use the method identifierAtIndex:. To get the index for a identifier, use the method indexForIdentifier:.

Each multivalue list also has a primary value, which is the item the user most strongly associates with that person. For example, friends may have both home and work addresses, but the home address is their primary address. And coworkers may have both home and work phone numbers, but the work number is their primary number. To get the identifier for a multivalue list’s primary value, use the method primaryIdentifier. To set the multivalue list’s primate value, use the method setPrimaryIdentifier:.

Associating a Picture With a Person

You can associate a picture that identifies a person in your Address Book database. Because these pictures are not stored in the same way as the other Address Book properties, you need to use different methods to access them.

To associate a TIFF to a person, use the method setImageData: or the function ABPersonSetImageData. To get the TIFF data for person’s image, use the method imageData. Note that both NSImage and QuickTime have functions for converting the data into a TIFF file.

Images are located by Address Book through a specific search heirarchy, in this order:

1. Check for an image set specifically by the user.

2. Check Directory Services for the local user’s login picture.

3. Check for an image in /Network/Library/Images/People/email, where email is the user’s primary e-mail address.

4. Check for an image from the user’s .Mac account, first against the cache at ~/Library/Caches/com.apple.AddressBook/email and then against the .Mac servers.

Getting Localized Names for Properties and Labels

You can find the localized name for any of the property names and labels that are in the header files ABGlobals.h and ABGlobalsC.h. In C, the function ABCopyLocalizedPropertyOrLabel returned a name that’s localized for the user’s selected language.

If you want to localize names for the properties and labels that you create, you must handle it yourself. The Address Book framework does not have support for this.

An Example

Listing 1 is an Objective-C code sample that retrieves the country for the primary address of the logged-in user. If the country is a null string, it sets the country to USA.

Listing 1  Changing a Person’s Address, in Objective-C

ABPerson *aPerson = [[ABAddressBook sharedAddressBook] me];

ABMutableMultiValue *anAddressList =

    [[aPerson valueForProperty:kABAddressProperty] mutableCopy];

int primaryIndex =

    [anAddressList indexForIdentifier:[anAddressList primaryIdentifier]];

NSMutableDictionary *anAddress =

    [[anAddressList valueAtIndex:primaryIndex] mutableCopy];

NSString *country =

    (NSString*) [anAddress objectForKey:kABAddressCountryKey];

if ([country isEqualToString:@""]) {

    [anAddress setObject:@"USA" forKey:kABAddressCountryKey];

    [anAddressList replaceValueAtIndex:primaryIndex withValue:anAddress];

    [aPerson setValue:anAddressList forProperty:kABAddressProperty];

    [[ABAddressBook sharedAddressBook] save];

}

Using the People Picker

The People Picker is a portion of the Address Book API that provides easy and quick access to the contents of a user’s address book from any application. It offers a searchable, selectable list of people and groups that can be customized for your application.

There are two ways to integrate the People Picker into a Cocoa application. The first is to use Interface Builder and the Address Book palette. The palette is not included in the standard list of Interface Builder palettes. To add it, click the Palettes tab in Xcode’s Preferences, click the Add button, and select ABPalette.palette, located at /Developer/Extras/Palettes/ABPalette.palette.

You can drag the ABPeoplePickerView from the AB palette to your window, and use the Interface Builder Info window to set many of the attributes of the People Picker view. These include the columns the view should display, whether or not multiple selections are allowed, whether or not group selections are allowed, and the autosave name for the view. These changes are reflected immediately, even within Interface Builder. Using the Test Interface feature of Interface Builder, a People Picker view will display the address book of the logged-in user.

The other method is to create and modify the People Picker view programmatically. To do so, you must design the enclosing window yourself with the People Picker view and make the appropriate connections to your controller class in the nib file. The most basic People Picker window needs a custom view object. This custom view should be set to a custom class of ABPeoplePickerView. This will require you to include AddressBook.h and AddressBookUI.h in your controller, make a subclass of NSView called ABPeoplePickerView, and create an outlet of that type from your controller to the custom view.

With just this People Picker view connected and no other code inserted, you get a working view of the Address Book, displaying the current user’s groups and people, as well as a search bar to narrow the results.

The People Picker API provides a host of methods and functions to access the address book data, to change the layout and construction of the People Picker view, and even to activate the Address Book application to perform tasks such as editing records.

It should be noted that the Carbon People Picker is only available in a window form and cannot be used as a custom HIView. It must be created as an ABPickerRef with ABPickerCreate() and made visible withABPickerSetVisibility(). The code would look like this:

ABPickerRef peoplePicker = ABPickerCreate();

ABPickerSetVisibility(peoplePicker, TRUE);

For Cocoa applications, the People Picker also provides methods for using autosave data, so that it can retain the filter selections and column positions. See the documentation on autosaveName: and setAutosaveName:.

People Picker Example

This example would be placed in the window controller for the People Picker. Carbon developers should refer to theAddress Book Reference for C to construct the analogue for their applications. Most of the functions are named similarly. In lieu of notifications, you will need to register event handlers to handle changes to the window.

This sample incorporates the fundamentals of using the People Picker. It assumes you have created a window in your nib file with an ABPeoplePickerView object, a NSTextField outlet called nameFieldLabel, and a NSImageView outlet called personImage.

#import "PickerController.h"

@implementation PickerController

- (void)awakeFromNib

{

    NSNotificationCenter* center;

    center = [NSNotificationCenter defaultCenter];

    //Here we set up a responder for one of the four notifications,

    //in this case to tell us when the selection in the name list

    //has changed.

    [center addObserver:self

            selector:@selector(recordChange:)

            name:ABPeoplePickerNameSelectionDidChangeNotification

            object:peoplePicker];

    //Here we disallow multiple selections in the name list

    [peoplePicker setAllowsMultipleSelection:NO];

    //Here we add the e-mail and telephone properties to the

    //view. By default, the People Picker displays only the

    //Name column.

    [peoplePicker addProperty:kABEmailProperty];

    [peoplePicker addProperty:kABPhoneProperty];

}

//This is the responder for the notification we registered for

- (void)recordChange:(NSNotification*)notif {

    NSImage *personImage;

    NSString *personName;

    NSArray *array;

    array = [peoplePicker selectedRecords];

    ABPerson *person = [array objectAtIndex:0];

    personImage = [[NSImage alloc] initWithData:[person imageData]];

    personName  = [NSString stringWithFormat:@"%@ %@",

                    [person valueForProperty:kABFirstNameProperty],

                    [person valueForProperty:kABLastNameProperty]];

    [imageView setImage:personImage];

    [nameField setStringValue:personName];

    [personImage release];

}

@end

< Previous PageNext Page > Hide TOC