A database isn't worth much without a way to search the contents. In address book, the class
ABSearchElement is how we create queries with any range of complexity. A search element contains a simple search, like search the address book for all records with the first name Mike, or search for all records with birth dates occurring before the turn of the millennium.
Two or more
ABSearchElement objects may be combined into a single composite search elements using either an AND operator or an OR operator. By combining search elements in this way it is possible to build quite complex queries.
ABSearchElement are created using the
ABGroup class method
searchElementForProperty:label:key:value:comparison:. Whether we invoke this method in the ABPerson class object or the
ABGroup class object depends on whether we want to perform a search for people, or a search for groups. This method takes the following parameters:
searchElementForProperty: is the record property the we wish to perform the search again
label: If the property is a multi-value property, then we can specify a label here to restrict the search to one particular element of the multi-value
key: If the property value is a dictionary, then we can specify a key in the dictionary here to restrict the search.
value: This is the value we are searching for
comparison: This parameter specifies how the search process will identify a matching value.
The last parameter, comparison:, tells the search element how to determine a matching value. There are ten possible constants to pass here:
To create a composite, or conjunction, search we use the
ABSearchElement class method
searchElementForConjunction:children:. The first parameter tells the method how the child search elements will be combined. The possible values are
kABOrSearch. The children: parameter takes an array of
ABSearchElements that are to be combined in the conjunction search. Children search elements may be simple searches, or conjunction searches themselves.
The following is an example of searching the address book using search elements:
ABSearchElement *se; NSArray *results; se = [ABPerson searchElementForProperty:kABAddressProperty label:kABAddressHomeLabel key:kABAddressStateKey value:@"Texas" comparison:kABEqual]; results = [book recordsMatchingSearchElement:se]; NSLog( [results description] );
As you can see above, the method
recordsMatchingSearchElement: returns an NSArray containing all of the people in the address book whose home address is in Texas.
Performing a conjunction search is done similarly:
ABSearchElement *se1, *se2, *cse; NSArray *children; se1 = [ABPerson searchElementForProperty:kABAddressProperty label:kABAddressHomeLabel key:kABAddressStateKey value:@"Texas" comparison:kABEqual]; se2 = [ABPerson searchElementForProperty:kABBirthdayProperty label:nil key:nil value:[NSDate dateWithTimeIntervalSinceReferenceDate:0] comparison:kABLessThan]; children = [NSArray arrayWithObjects:se1, se2, nil]; cse = [ABSearchElement searchElementForConjunction:kABAndSearch children:children]; results = [book recordsMatchingSearchElement:cse]; NSLog( [results description] );
The composite search element cse will search for all people in the address book database who not only live in Texas, but who were born before the turn of the millennium, which we specify by creating a date that is zero seconds past the reference date (the absolute reference date used by NSDate is 12:00 AM, January 1, 2001 GMT).
Odds and Ends
To tie up loose ends, let's talk a bit about assigning images to an
ABRecord, as well as how we can import and export vCards to and from the AddressBook database.
Creating a vCard is easily accomplished using the
vCardRepresentation. This method returns an NSData object whose data is formatted in the vCard format. We can then write this data to disk, which can be read by any number of applications that recognize the vCard format. Going the other way we can initialize an ABRecord object with vCard data using the method
initWithVCardRepresentation:. This method takes a parameter an NSData object, which was likely created by reading the contents of a vCard file on disk created by another application.
Finally, to associate an image with a person in the AddressBook we use the methods
TIFFImageData to set and get the person's picture. These methods work with NSData objects whose data is formatted as a TIFF image. This interfaces well with the NSImage methods
TIFFRepresentation, which returns an TIFF formatted NSData object, and
initWithData:, which initializes an NSImage object with image data.
So, that was a whirlwind tour of the AddressBook framework. It's not really my style to leave you empty-handed at the end of a column, so I've prepared a version of our old-school application Address Book that we worked on about a year ago while learning about NSTableView. This version has been revamped to display the contents of the user's address book in a table, and allow the user to edit records. It's basically the same thing we had before, except the data model is based on
ABAddressBook rather than on
NSDictionary. This is an excellent example of the utility of MVC since the model was separated from the view and insulated by the controller, so it was relatively pain-free to change.
So, happy Jaguar release, and next time we'll get back to those plug-ins.
Michael Beam is a software engineer in the energy industry specializing in seismic application development on Linux with C++ and Qt. He lives in Houston, Texas with his wife and son.
Read more Programming With Cocoa columns.
Return to the Mac DevCenter.
- Trackback from http://staff.washington.edu/oren/weblog/archives/000180.html
More on Apple
2004-04-13 11:51:50 [View]
2003-11-04 11:53:51 anonymous2 [View]
Parsing the AddressBook.data file?
2003-08-15 14:17:56 pthomsen [View]
List people in one particular category only.
2002-12-30 09:11:07 iuni [View]
What about the interface?
2002-11-26 08:00:13 anonymous2 [View]
Apple Laptop Keyboards Unsuitable for Unix Users
2002-09-18 02:20:11 anonymous2 [View]
Apple Laptop Keyboards Unsuitable for Unix Users
2004-04-06 09:50:17 macdaddy2008 [View]
2002-09-13 12:51:21 inetws [View]
2003-05-26 20:33:08 anonymous2 [View]
2002-09-09 21:41:06 johnts [View]
Strange Error ("No launchable executable")
2002-11-11 14:12:57 gracion [View]
2002-09-03 15:56:36 psheldon [View]
2002-08-29 12:58:18 cpenzini [View]
2002-08-27 22:32:59 jonblock [View]
Address Book and Security
2002-08-29 05:14:32 senjaz [View]