ABAddressBook Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AddressBook.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
ABAddressBook.h
ABGlobals.h
Related sample code

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 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 Address Book

Retrieving Groups and People

Setting and Retrieving the Logged-in User’s Record

Retrieving a Specific Record

Retrieving the Class of a Record

Retrieving a Formatted Address

Retrieving Default Values

Adding and Removing Records

Searching

Saving and Detecting Changes

Class Methods

addressBook

Returns a new instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

+ (ABAddressBook *)addressBook
Return Value

A new instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

Discussion

If you're just making one-off lookups and edits, the sharedAddressBook method is probably more appropriate. If your code is executing a tight loop, the addressBook method can yield significant performance improvements when used with the ABPerson initWithAddressBook: method. See “Accessing the Address Book” in Address Book Programming Guide for Mac for more details.

If the user denies your application access to the Address Book database, this method returns nil.

Availability
  • Available in OS X v10.5 and later.
Declared In
ABAddressBook.h

sharedAddressBook

Returns the unique shared instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

+ (ABAddressBook *)sharedAddressBook
Return Value

The unique shared instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

Discussion

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 will get a pointer to the same shared address book.

If you're just making one-off lookups and edits, this is the appropriate method to use. If your code is executing a tight loop, using the addressBook method with the initWithAddressBook: method of ABPerson can yield significant performance improvements. See “Accessing the Address Book” in Address Book Programming Guide for Mac for more details.

If the user denies your application access to the Address Book database, this method returns nil.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABAddressBook.h

Instance Methods

addRecord:

Adds an ABPerson or ABGroup record to the Address Book database.

- (BOOL)addRecord:(ABRecord *)record
Parameters
record

The record to add.

Return Value

YES if the record was added successfully; otherwise NO.

Discussion

If the record argument is nil, this method raises an exception. Your changes are not committed until you call the save method.

It is more efficient to use the ABRecord method initWithAddressBook: when possible.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBook.h

addRecord:error:

Adds an ABPerson or ABGroup record to the Address Book database.

- (BOOL)addRecord:(ABRecord *)record error:(NSError **)error
Parameters
record

The record to add.

error

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

Return Value

YES if the record was added successfully; otherwise NO.

Discussion

If the record argument is nil, this method raises an exception. Your changes are not committed until you call the save method.

It is more efficient to use the ABRecord method initWithAddressBook: when possible.

Availability
  • Available in OS X v10.7 and later.
Declared In
ABAddressBook.h

defaultCountryCode

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

- (NSString *)defaultCountryCode
Return Value

The default country code.

Discussion

This value returned is set by the user in the Address Book application’s general preference. The supported country codes are listed in “Country Codes”.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBook.h

defaultNameOrdering

Returns the default name ordering defined by the user in the Address Book application’s preferences.

- (NSInteger)defaultNameOrdering
Return Value

The default name ordering defined by the user in the Address Book application’s preferences.

Discussion

The possible values are kABFirstNameFirst and kABLastNameFirst.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBook.h

formattedAddressFromDictionary:

Returns an attributed string containing the formatted address.

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

The dictionary containing a street address.

Return Value

An attributed string containing the formatted address.

Discussion

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 Postal”.)

To get the dictionary containing a street address for a person record, use valueForProperty: with the property kABAddressProperty, and then getting one of the values from the multivalue that is returned.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBook.h

groups

Returns an array of all the groups in the Address Book database.

- (NSArray *)groups
Return Value

An array of all the groups in the Address Book database.

Discussion

If the database doesn’t contain any groups, this method returns an empty array.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABAddressBook.h

hasUnsavedChanges

Indicates whether an address book has changes that have not been saved to the Address Book database.

- (BOOL)hasUnsavedChanges
Return Value

YES if there are unsaved changes; otherwise, NO.

Discussion

The unsaved changes flag is set automatically whenever changes are made.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBook.h

me

Returns the ABPerson record that represents the logged-in user.

- (ABPerson *)me
Return Value

The ABPerson record that represents the logged-in user.

Discussion

If the user never specified such a record, this method returns nil.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABAddressBook.h

people

Returns an array of all the people in the Address Book database.

- (NSArray *)people
Return Value

An array of all the people in the Address Book database.

Discussion

If the database doesn’t contain any people, this method returns an empty array.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABAddressBook.h

recordClassFromUniqueId:

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

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

The unique ID of the record.

Return Value

The name of the class of the record, for example ABPerson.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBook.h

recordForUniqueId:

Returns the person or group record that matches the given unique ID.

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

The unique ID of the record. This value must not be nil; otherwise, an exception is raised.

Return Value

The person or group record that matches the given unique ID.

Discussion

If no record has the given ID, this method returns nil.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABAddressBook.h

recordsMatchingSearchElement:

Returns an array of records that match the given search element, or returns an empty array if no records match the search element.

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

The search element to perform the search against.

Return Value

An array of records that match the given search element, or an empty array if no records match the search element.

Discussion

If search is nil, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBook.h

removeRecord:

Removes an ABPerson or ABGroup record from the Address Book database.

- (BOOL)removeRecord:(ABRecord *)record
Parameters
record

The record to be removed.

Return Value

YES if the record was removed successfully; otherwise, NO.

Discussion

If record is nil, this method raises an exception. Your changes are not committed until you call the save method.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBook.h

removeRecord:error:

Removes an ABPerson or ABGroup record from the Address Book database.

- (BOOL)removeRecord:(ABRecord *)record error:(NSError **)error
Parameters
record

The record to be removed.

error

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

Return Value

YES if the record was removed successfully; otherwise, NO.

Discussion

If record is nil, this method raises an exception. Your changes are not committed until you call the save method.

Availability
  • Available in OS X v10.7 and later.
Declared In
ABAddressBook.h

save

Saves all the changes made since the last save.

- (BOOL)save
Return Value

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

Availability
  • Available in OS X v10.2 and later.
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 OS X v10.5 and later.
Declared In
ABAddressBook.h

setMe:

Sets the record that represents the logged-in user.

- (void)setMe:(ABPerson *)person
Parameters
person

The person to set as representing the logged-in user.

Discussion

If you don’t want a record to represent the logged-in user, then pass nil as the person argument. Note that this will not delete the existing record, if one is set.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABAddressBook.h

Constants

Database change notification keys

Keys contained by the user-info dictionary of the notifications posted by the Address Book framework.

NSString * const kABInsertedRecords;
NSString * const kABUpdatedRecords;
NSString * const kABDeletedRecords;
Constants
kABInsertedRecords

Records that have been inserted.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABUpdatedRecords

Records that have been updated.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABDeletedRecords

Records that have been deleted.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

Errors

Errors codes returned by the Address Book Framework.

enum {
   ABAddRecordsError = 1001,
   ABRemoveRecordsError = 1002,
   ABPropertyValueValidationError = 1012,
   ABPropertyUnsupportedBySourceError = 1013,
   ABPropertyReadOnlyError = 1014
};
Constants
ABAddRecordsError

The records could not be added

Available in OS X v10.7 and later.

Declared in ABAddressBook.h.

ABRemoveRecordsError

The records could not be removed.

Available in OS X v10.7 and later.

Declared in ABAddressBook.h.

ABPropertyValueValidationError

The property value is not valid.

Available in OS X v10.7 and later.

Declared in ABAddressBook.h.

ABPropertyUnsupportedBySourceError

The property is not supported by the source.

Available in OS X v10.7 and later.

Declared in ABAddressBook.h.

ABPropertyReadOnlyError

The property is read only.

Available in OS X v10.7 and later.

Declared in ABAddressBook.h.

Notifications

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

kABDatabaseChangedNotification

Posted when this process has changed the Address Book database.

Depending on the operation performed on the address book, one or more of the following keys may be included in the user-info dictionary: 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, every record has changes. For example, this happens when the Address Book database is restored from a backup copy.

Availability
Declared In
ABGlobals.h

kABDatabaseChangedExternallyNotification

Posted when a process other than the current one has changed the Address Book database.

Depending on the operation performed on the address book, one or more of the following keys may be included in the user-info dictionary: 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, every record has changes. For example, this happens when the Address Book database is restored from a backup copy.

Availability
Declared In
ABGlobals.h