Searching an Address Book

You can quickly search a user’s address book, using arbitrarily complex criteria. The address book is fully indexed, automatically. And the Address Book framework’s searching features let you easily create complex searches. For example, you can search for all people named “Smith,” or for all people who work at Acme and live in San Francisco, or who work at Ajax and live in Seattle.

Here’s how you create a search query. For each property you want to search on, create a search element. If you want to search on multiple properties, combine the search elements together with Boolean operators to create a complex search element. Then search the Address Book with that simple or complex search element.

Creating a Search Element for a Single Property

To create a search element for a person, use the ABPerson class method searchElementForProperty:label:key:value:comparison:. To create a search element for a group, use the ABGroup class method searchElementForProperty:label:key:value:comparison:.

If you want to search for people or groups that have a particular property set, regardless of the value it is set to, pass nil as the value and kABEqual as the comparison. To search for people or groups that do not have a property set, pass nil as the value and kABNotEqual as the comparison.

Creating a Search Element for Multiple Properties

To combine search elements, use the ABSearchElement class method searchElementForConjunction:children:. These procedures take two arguments:

conjunctionOperator describes how to combine the search elements. It can be kABSearchAnd or kABSearchOr.
children is an NSArray of search elements. The search elements can be a simple elements that specifies only one property, or complex elements that specifies several. This lets you create arbitrarily complex search elements. You cannot combine search elements for groups with search elements for people.

Finding Records that Match a Search Element

To search the Address Book for records that match a search element, use the ABAddressBook method recordsMatchingSearchElement:, which returns an NSArray of records. Use the ABSearchElement method matchesRecord: to test whether a specific record matches a query.

Search Examples

Listing 1 shows a simple search. This code finds all the people whose last name is “Smith.”

Listing 1 Simple Search

ABAddressBook *AB = [ABAddressBook sharedAddressBook];

ABSearchElement *nameIsSmith =

    [ABPerson searchElementForProperty:kABLastNameProperty

                                 label:nil

                                   key:nil

                                 value:@"Smith"

                            comparison:kABEqualCaseInsensitive];

NSArray *peopleFound =

    [AB recordsMatchingSearchElement:nameIsSmith];

Listing 2 shows a complex search. It searches for anyone who lives in San Francisco and works for Acme, or for anyone who lives in Seattle and works for Ajax. Note that the addresses are searched using the kABHomeLabel label—we only want to know if they live in the city we are searching, not if they work in the same city.

Listing 2 Complex Search

ABAddressBook *AB = [ABAddressBook sharedAddressBook];

ABSearchElement *inSF =

    [ABPerson searchElementForProperty:kABAddressProperty

                                 label:kABHomeLabel

                                   key:kABAddressCityKey

                                 value:@"San Francisco"

                            comparison:kABEqualCaseInsensitive];

ABSearchElement *atAcme =

    [ABPerson searchElementForProperty:kABOrganizationProperty

                                 label:nil

                                   key:nil

                                 value:@"Acme"

                            comparison:kABContainsSubStringCaseInsensitive];

ABSearchElement *inSeattle =

    [ABPerson searchElementForProperty:kABAddressProperty

                                 label:kABHomeLabel

                                   key:kABAddressCityKey

                                 value:@"Seattle"

                            comparison:kABEqualCaseInsensitive];

ABSearchElement *atAjax =

    [ABPerson searchElementForProperty:kABOrganizationProperty

                                 label:nil

                                   key:nil

                                 value:@"Ajax"

                            comparison:kABContainsSubStringCaseInsensitive];

ABSearchElement *inSFAndAtAcme =

    [ABSearchElement searchElementForConjunction:kABSearchAnd

                                        children:[NSArray arrayWithObjects:

                                            inSF, atAcme, nil]];

ABSearchElement *inSeattleAndAtAjax =

    [ABSearchElement searchElementForConjunction:kABSearchAnd

                                        children:[NSArray arrayWithObjects:

                                            inSeattle, atAjax, nil]];

ABSearchElement *inSFAndAtAcmeOrInSeattleAndAtAjax =

    [ABSearchElement searchElementForConjunction:kABSearchOr

                                        children:[NSArray arrayWithObjects:

                                            inSFAndAtAcme, inSeattleAndAtAjax, nil]];

NSArray *peopleFound =

    [AB recordsMatchingSearchElement:inSFAndAtAcmeOrInSeattleAndAtAjax];

Last updated: 2009-08-07

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.