ABAddressBook C Reference

Overview

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

ABAddPropertiesAndTypes

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.

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

ABAddRecord

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

bool ABAddRecord (
   ABAddressBookRef addressBook,
   ABRecordRef record
);

ABCopyArrayOfAllGroups

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

CFArrayRef ABCopyArrayOfAllGroups (
   ABAddressBookRef addressBook
);

ABCopyArrayOfAllPeople

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

CFArrayRef ABCopyArrayOfAllPeople (
   ABAddressBookRef addressBook
);

ABCopyArrayOfMatchingRecords

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

CFArrayRef ABCopyArrayOfMatchingRecords (
   ABAddressBookRef addressBook,
   ABSearchElementRef search
);

ABCopyArrayOfPropertiesForRecordType

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

CFArrayRef ABCopyArrayOfPropertiesForRecordType (
   ABAddressBookRef addressBook,
   CFStringRef recordType
);

ABCopyDefaultCountryCode

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

CFStringRef ABCopyDefaultCountryCode (
   ABAddressBookRef addressBook
);

ABCopyRecordForUniqueId

Returns the record that matches the given unique ID.

ABRecordRef ABCopyRecordForUniqueId (
   ABAddressBookRef addressBook,
   CFStringRef uniqueId
);

ABCopyRecordTypeFromUniqueId

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

CFStringRef ABCopyRecordTypeFromUniqueId (
   ABAddressBookRef addressBook,
   CFStringRef uniqueId
);

ABCreateFormattedAddressFromDictionary

Returns a string containing the formatted address.

CFStringRef ABCreateFormattedAddressFromDictionary (
   ABAddressBookRef addressBook,
   CFDictionaryRef address
);

ABGetMe

Returns the ABPerson object for the logged-in user.

ABPersonRef ABGetMe (
   ABAddressBookRef addressBook
);

ABGetSharedAddressBook

Returns the unique shared ABAddressBook object.

ABAddressBookRef ABGetSharedAddressBook (
   void
);

ABHasUnsavedChanges

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

bool ABHasUnsavedChanges (
   ABAddressBookRef addressBook
);

ABRemoveProperties

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

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

ABRemoveRecord

Removes the specified record from the Address Book database.

bool ABRemoveRecord (
   ABAddressBookRef addressBook,
   ABRecordRef record
);

ABSave

Saves all the changes made since the last save.

bool ABSave (
   ABAddressBookRef addressBook
);

ABSetMe

Sets the record that represents the logged-in user.

void ABSetMe (
   ABAddressBookRef addressBook,
   ABPersonRef moi
);

ABTypeOfProperty

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

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

Data Types

ABAddressBookRef

A reference to an ABAddressBook object.

typedef struct __ABAddressBookRef *ABAddressBookRef;

Constants

Property Types

These are the possible types of ABRecord properties.

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

Returned by some functions when an invalid property is used.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABStringProperty

Indicates a CFString object.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABIntegerProperty

Indicates a CFNumber object representing an integer.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABRealProperty

Indicates a CFNumber object representing a real number.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDateProperty

Indicates a CFDate object.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABArrayProperty

Indicates a CFArray object.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDictionaryProperty

Indicates a CFDictionary object.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDataProperty

Indicates a CFData object.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiStringProperty

Indicates an ABMultiValue containing NSString objects.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiIntegerProperty

Indicates an ABMultiValue containing NSNumber objects representing integers.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiRealProperty

Indicates an ABMultiValue containing NSNumber objects representing real numbers.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDateProperty

Indicates an ABMultiValue containing NSDate objects.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiArrayProperty

Indicates an ABMultiValue containing NSArray objects.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDictionaryProperty

Indicates an ABMultiValue containing NSDictionary objects.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDataProperty

Indicates an ABMultiValue containing NSData objects.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

Database Notifications

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

CFStringRef kABDatabaseChangedNotification;
CFStringRef kABDatabaseChangedExternallyNotification;

Constants

kABDatabaseChangedNotification

This process has changed the AddressBook database.

Available in OS X v10.2 and later.

Declared in ABGlobals.h.

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.

Declared in ABGlobals.h.