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

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.

ABAddRecord

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

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.

ABCopyArrayOfAllGroups

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

CFArrayRef ABCopyArrayOfAllGroups (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

ABCopyArrayOfAllPeople

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

CFArrayRef ABCopyArrayOfAllPeople (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

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

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.

ABCopyArrayOfPropertiesForRecordType

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

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.

ABCopyDefaultCountryCode

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

CFStringRef ABCopyDefaultCountryCode (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

ABCopyRecordForUniqueId

Returns the record that matches the given unique ID.

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.

ABCopyRecordTypeFromUniqueId

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

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.

ABCreateFormattedAddressFromDictionary

Returns a string containing the formatted address.

CFStringRef ABCreateFormattedAddressFromDictionary (
   ABAddressBookRef addressBook,
   CFDictionaryRef address
);

Parameters

addressBook

The address book for the logged-in user.

ABGetMe

Returns the ABPerson object for the logged-in user.

ABPersonRef ABGetMe (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

Related Sample Code

• MyFirstJNIProject

ABGetSharedAddressBook

Returns the unique shared ABAddressBook object.

ABAddressBookRef ABGetSharedAddressBook (
   void
);

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.

Related Sample Code

• MyFirstJNIProject

ABHasUnsavedChanges

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

bool ABHasUnsavedChanges (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

Discussion

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

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

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.

ABRemoveRecord

Removes the specified record from the Address Book database.

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.

ABSave

Saves all the changes made since the last save.

bool ABSave (
   ABAddressBookRef addressBook
);

Parameters

addressBook

The address book for the logged-in user.

ABSetMe

Sets the record that represents the logged-in user.

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.

ABTypeOfProperty

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

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.

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 Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABStringProperty

Indicates a CFString object.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABIntegerProperty

Indicates a CFNumber object representing an integer.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABRealProperty

Indicates a CFNumber object representing a real number.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDateProperty

Indicates a CFDate object.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABArrayProperty

Indicates a CFArray object.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDictionaryProperty

Indicates a CFDictionary object.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABDataProperty

Indicates a CFData object.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiStringProperty

Indicates an ABMultiValue containing NSString objects.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiIntegerProperty

Indicates an ABMultiValue containing NSNumber objects representing integers.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiRealProperty

Indicates an ABMultiValue containing NSNumber objects representing real numbers.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDateProperty

Indicates an ABMultiValue containing NSDate objects.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiArrayProperty

Indicates an ABMultiValue containing NSArray objects.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDictionaryProperty

Indicates an ABMultiValue containing NSDictionary objects.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h.

kABMultiDataProperty

Indicates an ABMultiValue containing NSData objects.

Available in Mac 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 Mac 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 Mac OS X v10.2 and later.

Declared in ABGlobals.h.

---