Mac Developer Library

Developer

AddressBook Framework Reference ABAddressBook C Reference

Options
Deployment Target:

On This Page
Language:

ABAddressBook C Reference

The ABAddressBook opaque type provides a programming interface to the Address Book—a centralized database used by multiple applications to store contact and other 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 accessing, adding, and removing group and person records including the “me” record corresponding to the logged-in user. For example, you use the ABCopyArrayOfAllGroups function to get an array of all the group records in the database, or the ABCopyArrayOfAllPeople function to get all the person records. You use the ABGetMe function to get the person record corresponding to the logged-in user. You can also add and remove records using the ABAddRecord and ABRemoveRecord functions.

You can also search for records matching a particular query you specify by creating an ABSearchElement object. You use the ABGroupCreateSearchElement or ABPersonCreateSearchElement function to create an ABSearchElement object for the corresponding record. Then use the ABCopyArrayOfMatchingValues ABAddressBook function, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for more functions that create compound queries.

Your application uses a shared instance of ABAddressBook returned by the ABGetSharedAddressBook function to interact with the database (multiple ABAddressBook instances are not supported). Changes you make to the record objects are stored in memory, and saved to disk when you invoke the ABSave function.

The Address Book posts notifications if any application including yours makes changes to the database. Typically, you observe these notifications to update any dependent view or model objects in your application. Use CFNotificationCenter to register for the ABAddressBook notifications: kABDatabaseChangedNotification and kABDatabaseChangedExternallyNotification. These notifications are not sent until ABGetSharedAddressBook is called.

The ABAddressBook opaque type is “toll-free bridged” with its Objective-C counterpart. This means that the ABAddressBookRef type is interchangeable in function or method calls with instances of the ABAddressBook class.

Functions

  • Adds the given properties to all the records of the specified type in the Address Book database, and returns the number of properties successfully added.

    Declaration

    Swift

    func ABAddPropertiesAndTypes(_ addressBook: ABAddressBook!, _ recordType: CFString!, _ propertiesAndTypes: CFDictionary!) -> CFIndex

    Objective-C

    CFIndex ABAddPropertiesAndTypes ( ABAddressBookRef addressBook, CFStringRef recordType, CFDictionaryRef propertiesAndTypes );

    Parameters

    addressBook

    The address book for the logged-in user.

    recordType

    The record type you wish to add properties to: kABGroupRecordType or kABPersonRecordType.

    propertiesAndTypes

    A CFDictionary object containing the properties to add. In each dictionary entry, the key is a string with the property’s name, and the value is a constant with the property’s type. The property’s name must be unique. You may want to use Java-style package names for your properties, for example, "org.dogclub.dogname" or "com.mycompany.customerID". The property type must be one of the constants described in Property Types.

    Return Value

    The number of properties successfully added.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Adds a record of the specified type to the Address Book database.

    Declaration

    Swift

    func ABAddRecord(_ addressBook: ABAddressBook!, _ record: ABRecordRef) -> Bool

    Objective-C

    bool ABAddRecord ( ABAddressBookRef addressBook, ABRecordRef record );

    Parameters

    addressBook

    The address book for the logged-in user.

    record

    The record to add to the Address Book database. If this parameter is NULL, the function raises an exception.

    Return Value

    true if the record was added successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns an array of all the groups in the Address Book database.

    Declaration

    Swift

    func ABCopyArrayOfAllGroups(_ addressBook: ABAddressBook!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABCopyArrayOfAllGroups ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    An array of ABGroup objects representing all the groups in the Address Book database. If the database doesn’t contain any groups, the function returns an empty array. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns an array of all the people in the Address Book database.

    Declaration

    Swift

    func ABCopyArrayOfAllPeople(_ addressBook: ABAddressBook!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABCopyArrayOfAllPeople ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    An array of ABPerson objects representing all the people in the Address Book database. If the database does not contain any people, the function returns an empty array. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns an array of records that match the given search element, or an empty array if no records match the search element.

    Declaration

    Swift

    func ABCopyArrayOfMatchingRecords(_ addressBook: ABAddressBook!, _ search: ABSearchElement!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABCopyArrayOfMatchingRecords ( ABAddressBookRef addressBook, ABSearchElementRef search );

    Parameters

    addressBook

    The address book for the logged-in user.

    search

    The search element that specifies the query. If search is NULL, this function raises an exception. Create an ABSearchElement object using the record specific functions: ABGroupCreateSearchElement or ABPersonCreateSearchElement. See ABSearchElement for more functions that create compound queries.

    Return Value

    A new array containing ABRecord objects representing all the records that match search. If no records match search, this function returns an empty array. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns an array containing the names of all the properties for the specified record type.

    Declaration

    Swift

    func ABCopyArrayOfPropertiesForRecordType(_ addressBook: ABAddressBook!, _ recordType: CFString!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABCopyArrayOfPropertiesForRecordType ( ABAddressBookRef addressBook, CFStringRef recordType );

    Parameters

    addressBook

    The address book for the logged-in user.

    recordType

    Specifies the type of record: kABGroupRecordType or kABPersonRecordType.

    Return Value

    An new array containing the names (CFString objects) of all the properties in recordType. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the default country code for records with unspecified country codes.

    Declaration

    Swift

    func ABCopyDefaultCountryCode(_ addressBook: ABAddressBook!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABCopyDefaultCountryCode ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    A string with the default country code. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns the type name of the record that matches a given unique ID.

    Declaration

    Swift

    func ABCopyRecordTypeFromUniqueId(_ addressBook: ABAddressBook!, _ uniqueId: CFString!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABCopyRecordTypeFromUniqueId ( ABAddressBookRef addressBook, CFStringRef uniqueId );

    Parameters

    addressBook

    The address book for the logged-in user.

    uniqueId

    A unique ID for the record. If this is NULL, this function raises an exception.

    Return Value

    A string with the name of the type for the record that matches the given unique ID. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns the record that matches the given unique ID.

    Declaration

    Swift

    func ABCopyRecordForUniqueId(_ addressBook: ABAddressBook!, _ uniqueId: CFString!) -> ABRecordRef

    Objective-C

    ABRecordRef ABCopyRecordForUniqueId ( ABAddressBookRef addressBook, CFStringRef uniqueId );

    Parameters

    addressBook

    The address book for the logged-in user.

    uniqueId

    A unique ID for the record. If this is NULL, this function raises an exception.

    Return Value

    The record that matches the given unique ID. If no record matches uniqueId, the function returns NULL. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns a string containing the formatted address.

    Declaration

    Swift

    func ABCreateFormattedAddressFromDictionary(_ addressBook: ABAddressBook!, _ address: CFDictionary!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABCreateFormattedAddressFromDictionary ( ABAddressBookRef addressBook, CFDictionaryRef address );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    Returns a string containing the formatted address. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns the ABPerson object for the logged-in user.

    Declaration

    Swift

    func ABGetMe(_ addressBook: ABAddressBook!) -> Unmanaged<ABPerson>!

    Objective-C

    ABPersonRef ABGetMe ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    The ABPerson record that represents the logged-in user, or NULL if the user never specified such a record. You are responsible for retaining and releasing this object as needed.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the unique shared ABAddressBook object.

    Declaration

    Swift

    func ABGetSharedAddressBook() -> Unmanaged<ABAddressBook>!

    Objective-C

    ABAddressBookRef ABGetSharedAddressBook ( void );

    Return Value

    The address book for the logged-in user. You are responsible for retaining and releasing this object as needed.

    Discussion

    Every application shares the address book for the logged-in user and this function returns it. If you call this function more than once or try to create a new address book, you get a pointer to the same shared address book.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns whether if there are unsaved changes in the address book.

    Declaration

    Swift

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

    Objective-C

    bool ABHasUnsavedChanges ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    true if there are unsaved changes, false otherwise.

    Discussion

    The unsaved changes flag is set automatically whenever changes are made to the address book.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes the given properties from all the records of this type in the Address Book database, and returns the number of properties successfully removed.

    Declaration

    Swift

    func ABRemoveProperties(_ addressBook: ABAddressBook!, _ recordType: CFString!, _ properties: CFArray!) -> CFIndex

    Objective-C

    CFIndex ABRemoveProperties ( ABAddressBookRef addressBook, CFStringRef recordType, CFArrayRef properties );

    Parameters

    addressBook

    The address book for the logged-in user.

    recordType

    The name of record to remove the properties from: kABGroupRecordType or kABPersonRecordType.

    properties

    An array of properties (CFString objects) to remove.

    Return Value

    The number of properties successfully removed.

    Discussion

    Only custom properties can be removed. This function is not implemented.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes the specified record from the Address Book database.

    Declaration

    Swift

    func ABRemoveRecord(_ addressBook: ABAddressBook!, _ record: ABRecordRef) -> Bool

    Objective-C

    bool ABRemoveRecord ( ABAddressBookRef addressBook, ABRecordRef record );

    Parameters

    addressBook

    The address book for the logged-in user.

    record

    The ABRecord object to be removed. If NULL, this function raises an exception.

    Return Value

    true if the record was removed successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Saves all the changes made since the last save.

    Declaration

    Swift

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

    Objective-C

    bool ABSave ( ABAddressBookRef addressBook );

    Parameters

    addressBook

    The address book for the logged-in user.

    Return Value

    true if this function is successful or if there were no changes, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Sets the record that represents the logged-in user.

    Declaration

    Swift

    func ABSetMe(_ addressBook: ABAddressBook!, _ person: ABPerson!)

    Objective-C

    void ABSetMe ( ABAddressBookRef addressBook, ABPersonRef moi );

    Parameters

    addressBook

    The address book for the logged-in user.

    person

    The ABPerson object that represents the logged-in user. Pass NULL if you don’t want a record to represent the logged-in user.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the type of a given property for a given record.

    Declaration

    Swift

    func ABTypeOfProperty(_ addressBook: ABAddressBook!, _ recordType: CFString!, _ property: CFString!) -> ABPropertyType

    Objective-C

    ABPropertyType ABTypeOfProperty ( ABAddressBookRef addressBook, CFStringRef recordType, CFStringRef property );

    Parameters

    addressBook

    The address book for the logged-in user.

    recordType

    The record type that contains property: kABGroupRecordType or kABPersonRecordType.

    property

    The property whose type you wish to obtain.

    Return Value

    The type of property as defined in Property Types. If property does not exist in recordType, this function returns kABErrorInProperty.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Data Types

  • A reference to an ABAddressBook object.

    Declaration

    Swift

    typealias ABAddressBookRef = ABAddressBook

    Objective-C

    typedef struct __ABAddressBookRef *ABAddressBookRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Constants

  • These are the possible types of ABRecord properties.

    Declaration

    Swift

    typealias ABPropertyType = CFIndex

    Objective-C

    typedef enum _ABPropertyType { kABErrorInProperty = 0x0, kABStringProperty = 0x1, kABIntegerProperty = 0x2, kABRealProperty = 0x3, kABDateProperty = 0x4, kABArrayProperty = 0x5, kABDictionaryProperty = 0x6, kABDataProperty = 0x7, kABMultiStringProperty = 0x100 | kABStringProperty, kABMultiIntegerProperty = 0x100 | kABIntegerProperty, kABMultiRealProperty = 0x100 | kABRealProperty, kABMultiDateProperty = 0x100 | kABDateProperty, kABMultiArrayProperty = 0x100 | kABArrayProperty, kABMultiDictionaryProperty = 0x100 | kABDictionaryProperty, kABMultiDataProperty = 0x100 | kABDataProperty } ABPropertyType;

    Constants

    • kABErrorInProperty

      kABErrorInProperty

      Returned by some functions when an invalid property is used.

      Available in OS X v10.2 and later.

    • kABStringProperty

      kABStringProperty

      Indicates a CFString object.

      Available in OS X v10.2 and later.

    • kABIntegerProperty

      kABIntegerProperty

      Indicates a CFNumber object representing an integer.

      Available in OS X v10.2 and later.

    • kABRealProperty

      kABRealProperty

      Indicates a CFNumber object representing a real number.

      Available in OS X v10.2 and later.

    • kABDateProperty

      kABDateProperty

      Indicates a CFDate object.

      Available in OS X v10.2 and later.

    • kABArrayProperty

      kABArrayProperty

      Indicates a CFArray object.

      Available in OS X v10.2 and later.

    • kABDictionaryProperty

      kABDictionaryProperty

      Indicates a CFDictionary object.

      Available in OS X v10.2 and later.

    • kABDataProperty

      kABDataProperty

      Indicates a CFData object.

      Available in OS X v10.2 and later.

    • kABMultiStringProperty

      kABMultiStringProperty

      Indicates an ABMultiValue containing NSString objects.

      Available in OS X v10.2 and later.

    • kABMultiIntegerProperty

      kABMultiIntegerProperty

      Indicates an ABMultiValue containing NSNumber objects representing integers.

      Available in OS X v10.2 and later.

    • kABMultiRealProperty

      kABMultiRealProperty

      Indicates an ABMultiValue containing NSNumber objects representing real numbers.

      Available in OS X v10.2 and later.

    • kABMultiDateProperty

      kABMultiDateProperty

      Indicates an ABMultiValue containing NSDate objects.

      Available in OS X v10.2 and later.

    • kABMultiArrayProperty

      kABMultiArrayProperty

      Indicates an ABMultiValue containing NSArray objects.

      Available in OS X v10.2 and later.

    • kABMultiDictionaryProperty

      kABMultiDictionaryProperty

      Indicates an ABMultiValue containing NSDictionary objects.

      Available in OS X v10.2 and later.

    • kABMultiDataProperty

      kABMultiDataProperty

      Indicates an ABMultiValue containing NSData objects.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • These are notifications published when something changes in the Address Book database. These notifications are not sent until ABGetSharedAddressBook has been called.

    Declaration

    Swift

    let kABDatabaseChangedNotification: NSString! let kABDatabaseChangedExternallyNotification: NSString!

    Objective-C

    CFStringRef kABDatabaseChangedNotification; CFStringRef kABDatabaseChangedExternallyNotification;

    Constants

    • kABDatabaseChangedNotification

      kABDatabaseChangedNotification

      This process has changed the AddressBook database.

      Available in OS X v10.2 and later.

    • kABDatabaseChangedExternallyNotification

      kABDatabaseChangedExternallyNotification

      Another process has changed the AddressBook database. The following keys are included in the user-info dictionary of the notification: kABInsertedRecords, kABUpdatedRecords, and kABDeletedRecords. If the values for all the keys are nil, everything has changed, such as when the Address Book database is restored from a backup copy.

      Available in OS X v10.2 and later.