ABAddressBook C Reference

Derived from
Framework
AddressBook/ABAddressBookC.h
Companion guide
Declared in
ABAddressBookC.h
ABGlobals.h
ABTypedefs.h

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.

Return Value

The number of properties successfully added.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

true if the record was added successfully, false otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

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

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

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

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBookC.h

ABCreateFormattedAddressFromDictionary

Returns a string containing the formatted address.

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABAddressBookC.h

ABGetMe

Returns the ABPerson object for the logged-in user.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGetSharedAddressBook

Returns the unique shared ABAddressBook object.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

The number of properties successfully removed.

Discussion

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

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

true if the record was removed successfully, false otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABSave

Saves all the changes made since the last save.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.

Return Value

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

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

Data Types

ABAddressBookRef

A reference to an ABAddressBook object.

typedef struct __ABAddressBookRef *ABAddressBookRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

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.