iOS Developer Library

Developer

Address Book Framework Reference for iOS 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

    Swift

    func ABAddressBookCreate() -> Unmanaged<ABAddressBook>!

    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.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.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.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

Callbacks

Data Types

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

    Declaration

    Swift

    typealias ABAddressBook = CFTypeRef

    Objective-C

    typedef CFTypeRef ABAddressBookRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

  • 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
    1. @implementation APLViewController
    2. - (void)viewDidLoad
    3. {
    4. [super viewDidLoad];
    5. // Do any additional setup after loading the view
    6. CFErrorRef myError = NULL;
    7. ABAddressBookRef myAddressBook = ABAddressBookCreateWithOptions(NULL, &myError);
    8. APLViewController * __weak weakSelf = self; // avoid capturing self in the block
    9. ABAddressBookRequestAccessWithCompletion(myAddressBook,
    10. ^(bool granted, CFErrorRef error) {
    11. if (granted) {
    12. NSArray *theSmiths = CFBridgingRelease(
    13. ABAddressBookCopyPeopleWithName(myAddressBook,
    14. CFSTR("Smith")
    15. )
    16. );
    17. weakSelf.numberOfSmiths = [theSmiths count];
    18. } else {
    19. // Handle the case of being denied access and/or the error.
    20. }
    21. CFRelease(myAddressBook);
    22. });
    23. }
    24. ...
    25. @end

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

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.

      Deprecated in iOS 9.0.

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

      Deprecated in iOS 9.0.

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

      Deprecated in iOS 9.0.

    • Denied

      kABAuthorizationStatusDenied

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

      Available in iOS 2.0 and later.

      Deprecated in iOS 9.0.

    • Authorized

      kABAuthorizationStatusAuthorized

      The app is authorized to access address book data.

      Available in iOS 2.0 and later.

      Deprecated in iOS 9.0.

    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.