---

About the Address Book

The Address Book is a centralized database for contact and other personal information for people. Users need to enter personal information about themselves and their friends only once instead of entering it repeatedly whenever the information is used. Applications that support the Address Book framework share this contact information with other applications, including Apple’s Mail and iChat. Both Carbon and Cocoa applications can access it.

This database contains people’s names, street addresses, email addresses, phone numbers, home pages, and more. Your applications can use this data as it is or extend it to include information specific to your applications. Every user on the computer has one and only one address book. Every application shares the address book for the currently logged-in user.

Contents:

Basic Address Book Concepts
Advanced Address Book Concepts

Basic Address Book Concepts

This section details the basic information that every developer using the Address Book and its associated API should know. It will help you get started with the remainder of the content in this document.

The Address Book contains two fundamental sorts of records, and they are what you would expect of an address book: ABPerson, for individuals, and ABGroup, for groups. Both are subclasses of the same root class ABRecord, and they can be used interchangeably in some places.

An ABPerson record contains such properties as the person’s name, company, addresses, email addresses, phone numbers, instant messaging IDs, and a comments field.

An ABGroup object can contain any number of people and other groups. For example, let’s say you are the CEO of two companies, Acme Co. and Ajax Inc. You logically would have an Acme employees group and an Ajax employees group, containing both companies’ respective employees (in the form of ABPerson records). You could then set up a Professional group that includes the Acme group, the Ajax group, and some additional people who aren’t in either group. A person can be in any number of groups.

Each group and person has a unique identifier that’s set when the record is created. It’s guaranteed never to change even if a user changes the group’s or person’s name or other information. Use this identifier if your application needs to store a reference to a group or person.

The groups and people are stored in an extensible form. As such, you can add custom properties to Address Book records that other applications will ignore, without worrying about data corruption or usability issues.

Some of these properties can contain multiple values. For example, a person can have any number of street addresses, phone numbers, and email addresses. A user can also specify that one of those multiple values is the primary value. For example, a user can specify that email be sent to one person’s work address and another person’s home address unless otherwise specified. For any such property that contains multiple values, the Address Book framework uses the ABMultiValue class. For more information, see “Using Multivalue Lists” in “About the Address Book.”

Searching the address book of a user, of course, is vitally important. Address Book manages individual search queries using an ABSearchElement object, instances of which can be created using class methods of ABGroup and ABPerson. See “Searching an Address Book” for a detailed look at searching Address Book records. This does have one important implication—since the ABSearchElement objects are created using ABPerson and ABGroup, a custom subclass of ABRecord will not contain the required methods to create such an object. For this reason, Apple advises against creating subclasses of ABRecord.

Advanced Address Book Concepts

This section explains some of the advanced features of Address Book, but may not be relevant to some developers.

The Address Book framework provides transparent record locking. If two applications try to change the same record simultaneously, the application that tried to change it last will succeed. The database will not be corrupted.

The Address Book does not provide any security above what’s provided by Mac OS X. Anyone who has read and write access to a user’s home folder can also read and write that user’s address book. For that reason, the Address Book may not be an appropriate place to store confidential information, such as credit card numbers.

The Address Book API provides localized versions of the built-in property names and labels. If you add properties or labels, you must provide your own way for localizing them.

---