iOS Developer Library

Developer

AddressBook Framework Reference ABAddressBook Reference

Options
Deployment Target:

On This Page
Language:

ABAddressBook Reference

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

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

    Deprecation Statement

    Use the ABAddressBookCreateWithOptions function instead.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 6.0.

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

    Declaration

    Swift

    func ABAddressBookCreateWithOptions(_ options: CFDictionary!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Unmanaged<ABAddressBook>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func ABAddressBookGetAuthorizationStatus() -> ABAuthorizationStatus

    Objective-C

    ABAuthorizationStatus ABAddressBookGetAuthorizationStatus ( void );

    Return Value

    The authorization status for your app.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 6.0 and later.

  • Requests access to address book data from the user.

    Declaration

    Swift

    func ABAddressBookRequestAccessWithCompletion(_ addressBook: ABAddressBook!, _ completion: ABAddressBookRequestAccessCompletionHandler!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func ABAddressBookHasUnsavedChanges(_ addressBook: ABAddressBook!) -> Bool

    Objective-C

    bool ABAddressBookHasUnsavedChanges ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book in question.

    Return Value

    true when addressBook contains unsaved changes, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

  • Saves any unsaved changes to the Address Book database.

    Declaration

    Swift

    func ABAddressBookSave(_ addressBook: ABAddressBook!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

  • Discards unsaved changes in an address book.

    Declaration

    Swift

    func ABAddressBookRevert(_ addressBook: ABAddressBook!)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

  • Adds a record to an address book.

    Declaration

    Swift

    func ABAddressBookAddRecord(_ addressBook: ABAddressBook!, _ record: ABRecord!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

  • Removes a record from an address book.

    Declaration

    Swift

    func ABAddressBookRemoveRecord(_ addressBook: ABAddressBook!, _ record: ABRecord!, _ error: UnsafeMutablePointer<Unmanaged<CFError>?>) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

  • Returns a localized version of a record-property label.

    Declaration

    Swift

    func ABAddressBookCopyLocalizedLabel(_ label: CFString!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABAddressBookCopyLocalizedLabel ( CFStringRef label );

    Parameters

    label

    The label to localize.

    Return Value

    The label localized to the user’s locale.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

Callbacks

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

    Declaration

    Swift

    typealias ABExternalChangeCallback = CFunctionPointer<((ABAddressBook!, CFDictionary!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*ABExternalChangeCallback) ( 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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

Data Types

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

    Declaration

    Swift

    typealias ABAddressBookRef = ABAddressBook

    Objective-C

    typedef CFTypeRef ABAddressBookRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    typealias ABAddressBookRequestAccessCompletionHandler = (Bool, CFError!) -> Void

    Objective-C

    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 1Sample 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

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 6.0 and later.

Constants

  • Error domain under which Address Book errors are grouped.

    Declaration

    Swift

    let ABAddressBookErrorDomain: CFString!

    Objective-C

    const CFStringRef ABAddressBookErrorDomain;

    Constants

    • ABAddressBookErrorDomain

      ABAddressBookErrorDomain

      The main error domain for Address Book framework operations.

      Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum ABAuthorizationStatus : CFIndex { case NotDetermined case Restricted case Denied case Authorized }

    Objective-C

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

    Constants

    • NotDetermined

      kABAuthorizationStatusNotDetermined

      No authorization status could be determined.

      Available in iOS 6.0 and later.

    • Restricted

      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.

    • Denied

      kABAuthorizationStatusDenied

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

      Available in iOS 6.0 and later.

    • Authorized

      kABAuthorizationStatusAuthorized

      The app is authorized to access address book data.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var kABOperationNotPermittedByStoreError: Int { get } var kABOperationNotPermittedByUserError: Int { get }

    Objective-C

    enum { kABOperationNotPermittedByStoreError = 0, kABOperationNotPermittedByUserError };

    Constants

    • kABOperationNotPermittedByStoreError

      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.

    • kABOperationNotPermittedByUserError

      kABOperationNotPermittedByUserError

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

      Available in iOS 6.0 and later.