ABAddressBook Reference

Derived from
CFTypeRef
Framework
AddressBook/AddressBook.h
Declared in
ABAddressBook.h

Overview

The ABAddressBook opaque type (whose instances 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

Managing Address Book Records

Getting Address Book Change Notifications

Localizing Text

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

Return Value

true when successful, false otherwise.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
ABAddressBook.h

ABAddressBookCopyLocalizedLabel

Returns a localized version of a record-property label.

CFStringRef ABAddressBookCopyLocalizedLabel (
   CFStringRef label
);
Parameters
label

The label to localize.

Return Value

The label localized to the user’s locale.

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

ABAddressBookCreate

Creates a new address book object with data from the Address Book database. (Deprecated. Use the ABAddressBookCreateWithOptions function instead.)

ABAddressBookRef ABAddressBookCreate (
   void
);
Return Value

An address book object.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
  • Deprecated in iOS 6.0.
Declared In
ABAddressBook.h

ABAddressBookCreateWithOptions

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

ABAddressBookRef ABAddressBookCreateWithOptions (
   CFDictionaryRef options,
   CFErrorRef* error
);
Parameters
options

Reserved. Pass NULL.

error

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

Return Value

An address book object, NULL, or an empty database.

Discussion

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

On iOS 6.0 and later, if the caller does not have access to the Address Book database:

  • For apps linked against iOS 6.0 and later, this function returns NULL.

  • For apps linked against previous version of iOS, this function returns an empty read-only database.

If your app syncs information with the database, it must not sync data when it does not have access to the database.

Availability
  • Available in iOS 6.0 and later.
Declared In
ABAddressBook.h

ABAddressBookGetAuthorizationStatus

Returns the authorization status of your app for accessing address book data.

ABAuthorizationStatus ABAddressBookGetAuthorizationStatus (void);
Return Value

The authorization status for your app.

Availability
  • Available in iOS 6.0 and later.
Declared In
ABAddressBook.h

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.

Return Value

true when addressBook contains unsaved changes, false otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

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

The object to pass to the callback function.

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

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 to be removed.

record

The record to remove from addressBook.

error

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

Return Value

true when successful, false otherwise.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
ABAddressBook.h

ABAddressBookRequestAccessWithCompletion

Requests access to address book data from the user.

void ABAddressBookRequestAccessWithCompletion (
   ABAddressBookRef addressBook,
   ABAddressBookRequestAccessCompletionHandler completion
);
Parameters
addressBook

The address book in question.

completion

The completion handler, called once access has been granted or denied by the user.

Discussion

Use this function to request access to address book data. This call will not block while the user is being asked for access, allowing your app to continue running. Until access has been granted, any address book references your app has will not contain any data, and any attempt to modify data will fail with an error type of kABOperationNotPermittedByUserError. The user is only asked for permission the first time you request access. Later calls use the permission granted by the user.

The completion handler is called on an arbitrary queue. If your app uses an address book throughout the app, you are responsible for ensuring that all usage of that address book is dispatched to a single queue to ensure correct thread-safe operation.

Availability
  • Available in iOS 6.0 and later.
Declared In
ABAddressBook.h

ABAddressBookRevert

Discards unsaved changes in an address book.

void ABAddressBookRevert (
   ABAddressBookRef addressBook
);
Parameters
addressBook

The address book to revert.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

ABAddressBookSave

Saves any unsaved changes 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.”

Return Value

true when successful, false otherwise.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
ABAddressBook.h

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. The signature of the function must match ABExternalChangeCallback.

context

The object to pass to the callback function.

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

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

The object to pass to the callback function.

Discussion

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

You can register for a 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

Data Types

ABAddressBookRef

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

typedef CFTypeRef ABAddressBookRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
ABAddressBook.h

ABAddressBookRequestAccessCompletionHandler

Definition for a block callback invoked when an access request has completed.

typedef void (^ABAddressBookRequestAccessCompletionHandler) (
   bool granted,
   CFErrorRef error
);
Discussion

Address book request access completion handler blocks are used with ABAddressBookCreateWithOptions. If you had a view controller that wanted to display the count of users with the name “Smith” in the address book, you might implement something like the code shown in the following code listing.

Listing 1  Sample implementation using ABAddressBookRequestAccessCompletionHandler

@implementation APLViewController
 
- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view
    CFErrorRef myError = NULL;
    ABAddressBookRef myAddressBook = ABAddressBookCreateWithOptions(NULL, &myError);
    APLViewController * __weak weakSelf = self;  // avoid capturing self in the block
    ABAddressBookRequestAccessWithCompletion(myAddressBook,
      ^(bool granted, CFErrorRef error) {
        if (granted) {
            NSArray *theSmiths = CFBridgingRelease(
              ABAddressBookCopyPeopleWithName(myAddressBook,
                CFSTR("Smith")
              )
            );
            weakSelf.numberOfSmiths = [theSmiths count];
        } else {
            // Handle the case of being denied access and/or the error.
        }
        CFRelease(myAddressBook);
    });
}
 
...
 
@end
Availability
  • Available in iOS 6.0 and later.
Declared In
ABAddressBook.h

Constants

Address Book Error Domain

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 iOS 2.0 and later.

Declared in ABAddressBook.h.

ABAuthorizationStatus

Different possible values for the authorization status of an app with respect to address book data.

typedef CF_ENUM(CFIndex,
   ABAuthorizationStatus) {
   kABAuthorizationStatusNotDetermined = 0,
   kABAuthorizationStatusRestricted,
   kABAuthorizationStatusDenied,
   kABAuthorizationStatusAuthorized
};
Constants
kABAuthorizationStatusNotDetermined

No authorization status could be determined.

Available in iOS 6.0 and later.

Declared in ABAddressBook.h.

kABAuthorizationStatusRestricted

The app is not authorized to access address book data. The user cannot change this access, possibly due to restrictions such as parental controls.

Available in iOS 6.0 and later.

Declared in ABAddressBook.h.

kABAuthorizationStatusDenied

The user explicitly denied access to address book data for this app.

Available in iOS 6.0 and later.

Declared in ABAddressBook.h.

kABAuthorizationStatusAuthorized

The app is authorized to access address book data.

Available in iOS 6.0 and later.

Declared in ABAddressBook.h.

Address Book Errors

Errors that can be raised under the Address Book error domain.

enum {
   kABOperationNotPermittedByStoreError = 0,
   kABOperationNotPermittedByUserError
};
Constants
kABOperationNotPermittedByStoreError

The operation is not allowed by the Address Book database, because the contact’s source does not support it.

Available in iOS 2.0 and later.

Declared in ABAddressBook.h.

kABOperationNotPermittedByUserError

The operation is not allowed because the user denied access to the Address Book database.

Available in iOS 6.0 and later.

Declared in ABAddressBook.h.