Using the Address Book C API
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 anABActionCallbacks
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.
Copyright © 2002, 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-04-23