ABAddressBook Reference

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

• ABAddressBookCreate
• ABAddressBookCreateWithOptions
• ABAddressBookGetAuthorizationStatus
• ABAddressBookRequestAccessWithCompletion
• ABAddressBookHasUnsavedChanges
• ABAddressBookSave
• ABAddressBookRevert

Managing Address Book Records

• ABAddressBookAddRecord
• ABAddressBookRemoveRecord

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
);

ABAddressBookCopyLocalizedLabel

Returns a localized version of a record-property label.

CFStringRef ABAddressBookCopyLocalizedLabel (
   CFStringRef label
);

ABAddressBookCreate

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

ABAddressBookRef ABAddressBookCreate (
   void
);

ABAddressBookCreateWithOptions

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

ABAddressBookRef ABAddressBookCreateWithOptions (
   CFDictionaryRef options,
   CFErrorRef* error
);

ABAddressBookGetAuthorizationStatus

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

ABAuthorizationStatus ABAddressBookGetAuthorizationStatus (void);

ABAddressBookHasUnsavedChanges

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

bool ABAddressBookHasUnsavedChanges (
   ABAddressBookRef addressBook
);

ABAddressBookRegisterExternalChangeCallback

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

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

ABAddressBookRemoveRecord

Removes a record from an address book.

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

ABAddressBookRequestAccessWithCompletion

Requests access to address book data from the user.

void ABAddressBookRequestAccessWithCompletion (
   ABAddressBookRef addressBook,
   ABAddressBookRequestAccessCompletionHandler completion
);

ABAddressBookRevert

Discards unsaved changes in an address book.

void ABAddressBookRevert (
   ABAddressBookRef addressBook
);

ABAddressBookSave

Saves any unsaved changes to the Address Book database.

bool ABAddressBookSave (
   ABAddressBookRef addressBook,
   CFErrorRef *error
);

ABAddressBookUnregisterExternalChangeCallback

Unregisters a callback.

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

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
);

Data Types

ABAddressBookRef

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

typedef CFTypeRef ABAddressBookRef;

ABAddressBookRequestAccessCompletionHandler

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

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

@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 error

        }

    });

    CFRelease(myAddressBook);

}

...

@end

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.