How Address Book Handles Individuals and Groups

The Address Book framework supports two fundamental kinds of records: 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 properties such 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; a person can be in any number of groups. For example, suppose you are a consultant who works with two companies, Acme Co. and Ajax Inc. You could set up an Acme employees group and an Ajax employees group, and make each company’s employees members of their respective group. You could then set up a Professionals group that includes the Acme group, the Ajax group, all well as some additional people who aren’t in either group.

In addition, group and person records have these characteristics:

• Each group and person has a unique identifier. It’s set when the record is created, and 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. For more information, see the ABRecord method uniqueId.

• 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. For more information, see Adding Properties to Address Book Records.

• Some of these properties can contain multiple values. For example, a person can have any number of street addresses, phone numbers, and email addresses. For more information, see Using Multivalue Lists.

How Address Book Manages Individual Search Queries

The Address Book framework manages individual search queries using ABSearchElement objects, which can be created using class methods of ABGroup and ABPerson. This has an important implication—because the search objects are created using the these particular classes, a custom subclass of ABRecord will not contain the required methods to create such an object. For this reason, you are advised not to subclass ABRecord.

For more information about searching Address Book records, see Searching an Address Book.

Other Features

The Address Book framework:

• Allows the user to control access to their contacts data. Before your application is allowed to access the user’s data in the Address Book database, the user is asked whether to grant it access. Your application specifies its reason for accessing the database by setting the value of the NSContactsUsageDescription key in its Info.plist file.

  If the user grants access, your application can access the database as usual. If the user denies access, the addressBook and sharedAddressBook methods of ABAddressBook return nil.

• Provides transparent record locking. If two applications try to change the same property within a record at the same time, the application that saved its change last will succeed. The database will not be corrupted. If two applications change different properties of the same record, both changes are expected to succeed.

• Does not provide any security above what’s provided by 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.

• 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.

• Syncs its records to iCloud. The Address Book framework uses the CardDav protocol to sync the data stored in the default properties to web services such as iCloud. Applications must not try to sync this data.