< Previous PageNext Page > Hide TOC

Using Address Book from C

This article contains important information for developers using Address Book’s 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 Carbon developers need to be aware of when using the Address Book C API:

• The Carbon People Picker comes only in window form and does not have an API for setting an accessory view. In addition, changes in selection and displayed properties are sent via Carbon Events.

• When creating an action plug-in using Carbon, your CFBundle 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

Otherwise, the Objective-C and C APIs act quite similar.

To access the user’s shared address book from Carbon, you need to set an ABAddressBookRef to the return value of ABGetSharedAddressBook:

ABAddressBookRef addressBook = ABGetSharedAddressBook();

Compare this with the same line, but from a Cocoa Objective-C application:

ABAddressBook *addressBook = [ABAddressBook sharedAddressBook];

Notice the similarity in the method and function names. Most of the sample code in this document is written in Objective-C, except where required to explain differences in the API. However, you can see that the mapping between the two APIs is easy to follow.

Let’s take an 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  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];

In Listing 2 you see that very same code segment, but written using the C API:

Listing 2  Simple Search, in C

ABAddressBookRef AB = ABGetSharedAddressBook();

ABSearchElementRef nameIsSmith =

    ABPersonCreateSearchElement(kABLastNameProperty,

                    NULL,

                    NULL,

                    CFSTR("Smith"),

                    kABEqualCaseInsensitive);

CFArrayRef peopleFound =

    ABCreateArrayOfMatchingRecords(AB, nameIsSmith);

Look familiar? For more details about integrating the Address Book into your Carbon applications, refer to Address Book Reference for C.

< Previous PageNext Page > Hide TOC