< Previous PageNext Page >

Hide TOC

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:. These procedures take the following arguments:

property is the name of the property to search on, such as kABAddressProperty or kABLastNameProperty. It cannot be nil. For a full list of the properties, see ABGlobals.h.
label is the label name for a multivalue list, such as kABAdressHomeLabel, kABPhoneWorkLabel, or a user-specified label, such as "Summer Home". If the specified property does not have multiple values, pass nil. If the specified property does have multiple values, pass nil to search all the values.
key is the key name for a dictionary, such as kABAddressCityKey or kABAddressStreetKey. If the specified property is not a dictionary, pass nil. If the specified property is a dictionary, pass nil to search all keys.
value is what you’re searching for. It cannot be nil.
comparison specifies the type of comparison to perform. You can choose
- To search for elements that are equal or not equal to the value, use kABEqual, kABNotEqual, or kABEqualCaseInsensitive
- To search for elements that are less than or greater than the value, use kABLessThan, kABLessThanOrEqual, kABGreaterThan, or kABGreaterThanOrEqual.
- To search for elements kABContainsSubString, kABContainsSubStringCaseInsensitive, kABPrefixMatch, or kABPrefixMatchCaseInsensitive.

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:. These procedures return an NSArray of records.

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];