---

ABAddressBook Class Objective-C Reference

Overview

The ABAddressBook class provides a programming interface to the Address Book—a centralized database used by multiple applications to store contact and other personal information about people. The Address Book database also supports the notion of a “group” containing one or more persons. People may belong to multiple groups, and groups may also belong to other groups with some restrictions (for example, no circular references are allowed).

The ABAddressBook class provides methods for accessing, adding, and removing group and person records including the “me” record corresponding to the logged-in user. For example, you use the groups method to get an array of all the group records in the database, or the people method to get all the person records. You use the me method to get the person record corresponding to the logged-in user. You can also add and remove records using the addRecord: and removeRecord: methods.

You can also search for records matching a particular query you specify by creating an ABSearchElement object. You use the searchElementForProperty:label:key:value:comparison: method in the ABPerson and ABGroup class to create an ABSearchElement object for the corresponding record. Then use the recordsMatchingSearchElement: ABAddressBook method, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for more methods that create compound queries.

Your application uses a shared instance of ABAddressBook returned by the sharedAddressBook class method to interact with the database (multiple ABAddressBook instances are not supported). Changes you make to record objects are stored in memory and saved to disk when you invoke the saveAndReturnError: method.

The Address Book posts notifications if any application including yours makes changes to the database. Typically, you observe these notifications to update any dependent view or model objects in your application. Use NSNotificationCenter to register for the ABAddressBook notifications: kABDatabaseChangedNotification and kABDatabaseChangedExternallyNotification. These notifications are not sent until thesharedAddressBook class method has been invoked.

The ABAddressBook class is “toll-free bridged” with its procedural C, opaque type, counterpart. This means that the ABAddressBookRef type is interchangeable in function or method calls with instances of the ABAddressBook class.

Tasks

Creating and Initializing an ABAddressBook

• + sharedAddressBook
• + addressBook

Retrieving Groups and People

• – groups
• – people

Setting and Retrieving the Logged-in User’s Record

• – me
• – setMe:

Retrieving a Specific Record

• – recordForUniqueId:

Retrieving the Class of a Record

• – recordClassFromUniqueId:

Retrieving a Formatted Address

• – formattedAddressFromDictionary:

Retrieving Default Values

• – defaultCountryCode
• – defaultNameOrdering

Adding and Removing Records

• – addRecord:
• – removeRecord:

Searching

• – recordsMatchingSearchElement:

Saving and Detecting Changes

• – hasUnsavedChanges
• – save
• – saveAndReturnError:

Class Methods

addressBook

Returns a new instance of ABAddressBook.

+ (ABAddressBook *)addressBook

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + sharedAddressBook

Declared In

ABAddressBook.h

sharedAddressBook

+ (ABAddressBook *)sharedAddressBook

Discussion

Returns the unique shared instance of ABAddressBook. This method returns the address book for the logged-in user that is shared by every application. If you call this method more than once or try to create a new address book, you get a pointer to the same shared address book.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + addressBook

Declared In

ABAddressBook.h

Instance Methods

addRecord:

- (BOOL)addRecord:(ABRecord *)record

Discussion

Adds an ABPerson or ABGroup record to the Address Book database. If the record argument is nil, this method raises an exception. This method returns YES if the record was added successfully, NO otherwise.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – removeRecord:
• – initWithVCardRepresentation: (ABPerson)

Declared In

ABAddressBook.h

defaultCountryCode

- (NSString *)defaultCountryCode

Discussion

Returns the default country code for records with unspecified country codes.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ABAddressBook.h

defaultNameOrdering

- (NSInteger)defaultNameOrdering

Discussion

Returns the default name ordering defined by the user in the Address Book preferences. The possible values are kABFirstNameFirst and kABLastNameFirst.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ABAddressBook.h

formattedAddressFromDictionary:

- (NSAttributedString *)formattedAddressFromDictionary:(NSDictionary *)address

Discussion

Returns an attributed string containing the formatted address. The string’s attributes match address dictionary keys, such as kABAddressStreetKey. Each attribute value contains the localized description of the key. (For example, the value of a Canadian kABAddressZIPKey field would be “Postal Code”, while the value of a French one would be “Code Postale”.)

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ABAddressBook.h

groups

- (NSArray *)groups

Discussion

Returns an array of all the groups in the Address Book database, or returns an empty array if the database doesn’t contain any groups

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – people

Declared In

ABAddressBook.h

hasUnsavedChanges

- (BOOL)hasUnsavedChanges

Discussion

Returns YES if there are unsaved changes, NO otherwise. The unsaved changes flag is set automatically whenever changes are made.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – saveAndReturnError:

Declared In

ABAddressBook.h

me

- (ABPerson *)me

Discussion

Returns the ABPerson record that represents the logged-in user, or nil if the user never specified such a record.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setMe:

Declared In

ABAddressBook.h

people

- (NSArray *)people

Discussion

Returns an array of all the people in the Address Book database, or an empty array if the database doesn’t contain any people.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – groups

Declared In

ABAddressBook.h

recordClassFromUniqueId:

- (NSString *)recordClassFromUniqueId:(NSString *)uniqueId

Discussion

Returns the class name of the record that matches the given unique ID.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ABAddressBook.h

recordForUniqueId:

- (ABRecord *)recordForUniqueId:(NSString *)uniqueId

Discussion

Returns the ABPerson or ABGroup record that matches the given unique ID, or nil if no record has the given ID. If uniqueId is nil, this method raises an exception.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – uniqueId (ABRecord)

Declared In

ABAddressBook.h

recordsMatchingSearchElement:

- (NSArray *)recordsMatchingSearchElement:(ABSearchElement *)search

Discussion

Returns an array of records that match the given search element, or returns an empty array if no records match the search element. If search is nil, this method raises an exception.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + searchElementForProperty:label:key:value:comparison: (ABPerson)
• + searchElementForProperty:label:key:value:comparison: (ABGroup)
• + searchElementForConjunction:children: (ABSearchElement)

Declared In

ABAddressBook.h

removeRecord:

- (BOOL)removeRecord:(ABRecord *)record

Discussion

Removes an ABPerson or ABGroup record from the Address Book database. If record is nil, this method raises an exception. This method returns YES if the record was removed successfully, NO otherwise.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – addRecord:

Declared In

ABAddressBook.h

save

- (BOOL)save

Discussion

Saves all the changes made since the last save. Returns YES if this method is successful or there were no changes, NO otherwise.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – hasUnsavedChanges
• – saveAndReturnError:

Declared In

ABAddressBook.h

saveAndReturnError:

Saves all the changes made since the last save.

- (BOOL)saveAndReturnError:(NSError **)error

Parameters

error

A pointer to an error object that is set to an NSError instance if an error occurs.

Return Value

YES if successful or there were no changes; otherwise, NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – save
• – hasUnsavedChanges

Declared In

ABAddressBook.h

setMe:

- (void)setMe:(ABPerson *)person

Discussion

Sets the record that represents the logged-in user. If you don’t want a record to represent the logged-in user, then pass nil as the person argument.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – me

Declared In

ABAddressBook.h

Notifications

These notifications are sent when something changes in the Address Book database. These are not sent until thesharedAddressBook class method has been invoked.

kABDatabaseChangedNotification

Posted when this process has changed the Address Book database. The process id of the sender and the effective user ID are always included in the user-info dictionary; you access them through the keys "kABSenderProcessID" and "kABUserUID", respectively. In addition, depending on the operation performed on the address book, one or more of the following keys may be included: kABInsertedRecords, kABUpdatedRecords, and kABDeletedRecords. The values for each of the keys are the unique IDs of the records that were inserted, updated, or deleted, respectively. If the values for all the keys are nil, everything has changed, such as when the Address Book database is restored from a backup copy.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

ABGlobals.h

kABDatabaseChangedExternallyNotification

Posted when a process other than the current one has changed the Address Book database. The process id of the sender and the effective user ID are always included in the user-info dictionary; you access them through the keys "kABSenderProcessID" and "kABUserUID", respectively. In addition, depending on the operation performed on the address book, one or more of the following keys may be included: kABInsertedRecords, kABUpdatedRecords, and kABDeletedRecords. The values for each of the keys are the unique IDs of the records that were inserted, updated, or deleted, respectively. If the values for all the keys are nil, everything has changed, such as when the Address Book database is restored from a backup copy.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

ABGlobals.h

---