For the most part, the Objective-C API has close method and syntax parity with the C API. This makes it easy to determine, for example, which function corresponds to a given Objective-C method.
There are a couple of primary differences that developers need to be aware of when using the Address Book C API:
The people picker comes only in window form and does not have a C API for setting an accessory view. In addition, changes in selection and displayed properties are sent via Carbon Events.
When creating a C-based action plug-in, your bundle must implement a function called ABActionRegisterCallbacks
, which will return an ABActionCallbacks
structure. The structure needs to be formed according to this type definition:
typedef struct { |
// The version of this struct is 0 |
CFIndex version; |
// A pointer to a function that returns the AddressBook |
// property this action applies to. |
ABActionPropertyCallback property; |
// A pointer to a function that returns the AddressBook |
// property this action applies to. Only items with labels |
// may have actions at this time. |
ABActionTitleCallback title; |
// A pointer to a function which returns YES if the action |
// should be enabled for the passed ABPersonRef and item |
// identifier. The item identifier will be NULL for single value |
// properties. This field may be NULL. Actions with NULL enabled |
// callbacks will always be enabled. |
ABActionEnabledCallback enabled; |
// A pointer to a function which will be called when the user |
// selects this action. It's passed an ABPersonRef and item |
// identifier. The item identifier will be NULL for single |
// value properties. |
ABActionSelectedCallback selected; |
} ABActionCallbacks |
To access the user’s shared address book using the C programming interface, you need to use the value returned by ABGetSharedAddressBook
.
ABAddressBookRef addressBook = ABGetSharedAddressBook(); |
Compare this with the corresponding code using the Objective-C programming interface, noting the mapping between corresponding method and function names.
ABAddressBook *addressBook = [ABAddressBook sharedAddressBook]; |
This example from “Searching an Address Book,” Listing 1, searches for anyone named Smith in the current user’s address book and returns an array of results.
Listing 1 A simple search, in Objective-C
ABAddressBook *AB = [ABAddressBook sharedAddressBook]; |
ABSearchElement *nameIsSmith = |
[ABPerson searchElementForProperty:kABLastNameProperty |
label:nil |
key:nil |
value:@"Smith" |
comparison:kABEqualCaseInsensitive]; |
NSArray *peopleFound = |
[AB recordsMatchingSearchElement:nameIsSmith]; |
Listing 2 performs the same search using the C API. Again, note the mapping between corresponding method and function names.
Listing 2 A simple search, in C
ABAddressBookRef AB = ABGetSharedAddressBook(); |
ABSearchElementRef nameIsSmith = |
ABPersonCreateSearchElement(kABLastNameProperty, |
NULL, |
NULL, |
CFSTR("Smith"), |
kABEqualCaseInsensitive); |
CFArrayRef peopleFound = |
ABCopyArrayOfMatchingRecords(AB, nameIsSmith); |
For more details about using the C API for the Address Book framework, refer to Address Book C Framework Reference for Mac OS X.
Last updated: 2010-08-03