ABAddressBook Reference

Overview

The ABAddressBook opaque type (instances of which are known as address books) provides a programming interface to the Address Book—a centralized database used by multiple applications to store 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.

The ABAddressBook opaque type provides functions for creating references to the Address Book database, saving changes, discarding changes, and registering for changes made externally (by other threads or processes) to the database.

Functions by Task

Managing Address Books

• ABAddressBookCreate
• ABAddressBookHasUnsavedChanges
• ABAddressBookSave
• ABAddressBookRevert

Managing Address Book Records

• ABAddressBookAddRecord
• ABAddressBookRemoveRecord
• ABAddressBookGetPersonCount
• ABAddressBookCopyArrayOfAllPeople
• ABAddressBookGetGroupCount
• ABAddressBookCopyArrayOfAllGroups

Getting Address Book Change Notifications

• ABAddressBookRegisterExternalChangeCallback
• ABAddressBookUnregisterExternalChangeCallback

Localizing Text

• ABAddressBookCopyLocalizedLabel

Functions

ABAddressBookAddRecord

Adds a record to an address book.

bool ABAddressBookAddRecord (
   ABAddressBookRef addressBook,
   ABRecordRef record,
   CFErrorRef *error
);

Parameters

addressBook

The address book to which record is added.

record

The record to add to addressBook.

error

On error, contains error information. See “Address Book Errors.”

ABAddressBookCopyArrayOfAllGroups

Returns an array with all the groups in an address book.

CFArrayRef ABAddressBookCopyArrayOfAllGroups (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book from which to return the groups

ABAddressBookCopyArrayOfAllPeople

Returns all the person records in an address book.

CFArrayRef ABAddressBookCopyArrayOfAllPeople (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book whose person records to return.

ABAddressBookCopyLocalizedLabel

Returns a localized version of record-property label.

CFStringRef ABAddressBookCopyLocalizedLabel (
   CFStringRef label
);

Parameters

label

The label to localize.

ABAddressBookCreate

Returns a new address book with data from the Address Book database.

ABAddressBookRef ABAddressBookCreate (
   void
);

Discussion

Changes made to the returned address book are reflected in the Address Book database only after saving the address book with ABAddressBookSave.

ABAddressBookGetGroupCount

Returns the number of groups in an address book.

CFIndex ABAddressBookGetGroupCount (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book whose record count to return.

ABAddressBookGetPersonCount

Returns the number of person records in an address book.

CFIndex ABAddressBookGetPersonCount (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book whose person-record count to return.

ABAddressBookHasUnsavedChanges

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

bool ABAddressBookHasUnsavedChanges (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book in question.

ABAddressBookRegisterExternalChangeCallback

Registers a callback to receive notifications when the Address Book database is modified.

void ABAddressBookRegisterExternalChangeCallback (
   ABAddressBookRef addressBook,
   ABExternalChangeCallback callback,
   void *context
);

Parameters

addressBook

The address book used to interact with the Address Book database.

callBack

The function to invoke when the Address Book database changes.

context

Object to pass to the callback function.

See Also

• ABExternalChangeCallback
• ABAddressBookUnregisterExternalChangeCallback

ABAddressBookRemoveRecord

Removes a record from an address book.

bool ABAddressBookRemoveRecord (
   ABAddressBookRef addressBook,
   ABRecordRef record,
   CFErrorRef *error
);

Parameters

addressBook

The address book from which record is removed.

record

The record to remove from addressBook.

error

On error, contains error information. See “Address Book Errors.”

ABAddressBookRevert

Discards unsaved changes in an address book.

void ABAddressBookRevert (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book to revert.

Discussion

The addressBook address book is loaded with the information in the Address Book database.

ABAddressBookSave

Saves unsaved changes to an address book to the Address Book database.

bool ABAddressBookSave (
   ABAddressBookRef addressBook,
   CFErrorRef *error
);

Parameters

addressBook

The address book to save.

error

On error, contains error information. See “Address Book Errors.”

ABAddressBookUnregisterExternalChangeCallback

Unregisters a callback.

void ABAddressBookUnregisterExternalChangeCallback (
   ABAddressBookRef addressBook,
   ABExternalChangeCallback callback,
   void *context
);

Parameters

addressBook

The address book used to interact with the Address Book database.

callBack

The function to invoke when the Address Book database changes. Must match the callback used in the registration.

context

Object to pass to the callback function. Must match the callback used in the registration.

See Also

• ABExternalChangeCallback
• ABAddressBookRegisterExternalChangeCallback

Callbacks

ABExternalChangeCallback

Prototype for a function callback invoked on an address book when the Address Book database is modified by another address book instance.

typedef void (*ABExternalChangeCallback) (
   ABAddressBookRef addressBook,
   CFDictionaryRef info,
   void *context
);

If you name your callback function MyAddressBookExternalChangeCallback, you declare it like this:

void *MyAddressBookExternalChangeCallback (
   ABAddressBookRef addressBook,
   CFDictionaryRef info,
   void *context
);

Parameters

addressBook

An address book used to interact with the Address Book database.

info

Always NULL.

context

Object to pass to the callback function.

Discussion

Use ABAddressBookRegisterExternalChangeCallback to register and ABAddressBookUnregisterExternalChangeCallback to unregister the callback function.

You can register for callback with different contexts or callback functions. The run loop on the thread that registered the callback invokes the callback.

The addressBook object does not take any action to flush or synchronize cached state with the Address Book database. If you want to ensure that addressBook doesn’t contain stale values, use ABAddressBookRevert.

Data Types

ABAddressBookRef

Reference to an object used to interact with the Address Book database.

typedef CFTypeRef ABAddressBookRef;

Constants

Address Book Error Domain

This constant identifies the error domain under which “Address Book Errors” are grouped.

const CFStringRef ABAddressBookErrorDomain;

Constants

ABAddressBookErrorDomain

The main error domain for Address Book framework operations.

Available in iPhone OS 2.0 and later.

Declared in ABAddressBook.h.

Address Book Errors

Errors that can be raised under the “Address Book Error Domain.”

enum {
   kABOperationNotPermittedByStoreError = 0
};

Constants

kABOperationNotPermittedByStoreError

The operation is not allowed by the Address Book database.

Available in iPhone OS 2.0 and later.

Declared in ABAddressBook.h.

---