Next Page >

Hide TOC

ABSearchElement C Reference

Derived from	CFType
Framework	AddressBook/ABAddressBookC.h
Companion guide	Address Book Programming Guide
Declared in	ABAddressBookC.h ABTypedefs.h

Overview

ABSearchElement is used to specify a search query for records in the Address Book database.

You can create a simple query by creating an ABSearchElement object using either the ABGroupCreateSearchElement or ABPersonCreateSearchElement function for the corresponding record. Then you use the ABAddressBook ABCopyArrayOfMatchingValues function, passing the ABSearchElement as the parameter, to query the database.

ABSearchElement also provides a function for creating compound queries. Use the ABSearchElementCreateWithConjunction function to combine two simple or complex queries into a compound query using either the kABSearchAnd or kABSearchOr conjunction constants.

Use the ABSearchElementMatchesRecord function to test whether or not a specific record matches a query.

The ABSearchElement opaque type is “toll-free bridged” with its Objective-C counterpart. This means that the ABSearchElementRef type is interchangeable in function or method calls with instances of the ABSearchElement class.

Functions

ABSearchElementCreateWithConjunction

Returns a compound search element created by combining the search elements in an array with the given conjunction.

ABSearchElementRef ABSearchElementCreateWithConjunction (
   ABSearchConjunction conjunction,
   CFArrayRef childrenSearchElement
);

Parameters

conjunction: The conjunction used to join the search elements in children. Can be either kABSearchAnd or kABSearchOr.
children: An array containing ABSearchElement objects to be joined using conjunction. If NULL this function raises an exception.

Return Value

A new compound search element joining the search elements in children using conjunction. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABSearchElementMatchesRecord

Tests whether or not a record matches a search element.

bool ABSearchElementMatchesRecord (
   ABSearchElementRef searchElement,
   ABRecordRef record
);

Parameters

searchElement: The search element containing the query you wish to test record with.
record: The record you wish to test.

Return Value

Returns true if the record parameter satisfies the conditions in the searchElement, false otherwise.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

Data Types

ABSearchElementRef

A reference to an ABSearchElement object.

typedef struct __ABSearchElementRef *ABSearchElementRef;

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

Constants

ABSearchComparison

Constants used to specify the type of comparison being made.

enum ABSearchComparison {
   kABEqual,
   kABNotEqual,
   kABLessThan,
   kABLessThanOrEqual,
   kABGreaterThan,
   kABGreaterThanOrEqual,
   kABEqualCaseInsensitive,
   kABContainsSubString,
   kABContainsSubStringCaseInsensitive,
   kABPrefixMatch,
   kABPrefixMatchCaseInsensitive,
   kABBitsInBitFieldMatch,
   kABDoesNotContainSubString,
   kABDoesNotContainSubStringCaseInsensitive,
   kABNotEqualCaseInsensitive,
   kABSuffixMatch,
   kABSuffixMatchCaseInsensitive,
   kABWithinIntervalAroundToday,
   kABWithinIntervalAroundTodayYearless,
   kABNotWithinIntervalAroundToday,
   kABNotWithinIntervalAroundTodayYearless,
   kABWithinIntervalFromToday,
   kABWithinIntervalFromTodayYearless,
   kABNotWithinIntervalFromToday,
   kABNotWithinIntervalFromTodayYearless
};

Constants

kABEqual

Search for elements that are equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABNotEqual

Search for elements that are not equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABNotEqualCaseInsensitive

Search for elements that are not equal to the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABLessThan

Search for elements that are less than the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABLessThanOrEqual

Search for elements that are less than or equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABGreaterThan

Search for elements that are greater than the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABGreaterThanOrEqual

Search for elements that are greater than or equal to the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABEqualCaseInsensitive

Search for elements that are equal to the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABContainsSubString

Search for elements that contain the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABContainsSubStringCaseInsensitive

Search for elements that contain the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABPrefixMatch

Search for elements that begin with the value.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABPrefixMatchCaseInsensitive

Search for elements that begin with the value, ignoring case.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABSuffixMatch

Search for elements that end with the value.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABSuffixMatchCaseInsensitive

Search for elements that end with the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABBitsInBitFieldMatch

Search for elements that match the bits in ABPersonFlags.

Available in Mac OS X v10.3 and later.

Declared in ABTypedefs.h

kABDoesNotContainSubString

Search for elements that do not contain the value.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABDoesNotContainSubStringCaseInsensitive

Search for elements that do not contain the value, ignoring case.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABWithinIntervalAroundToday

Search for elements that are within a time interval (in seconds) forward or backward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABWithinIntervalAroundTodayYearless

Search for elements that are within a time interval (in seconds) forward or backward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABNotWithinIntervalAroundToday

Search for elements that are not within a time interval (in seconds) forward or backward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABNotWithinIntervalAroundTodayYearless

Search for elements that are not within a time interval (in seconds) forward or backward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABWithinIntervalFromToday

Search for elements that are within a time interval (in seconds) forward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABWithinIntervalFromTodayYearless

Search for elements that are within a time interval (in seconds) forward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABNotWithinIntervalFromToday

Search for elements that are not within a time interval (in seconds) forward from today.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

kABNotWithinIntervalFromTodayYearless

Search for elements that are not within a time interval (in seconds) forward from this day in any year.

Available in Mac OS X v10.4 and later.

Declared in ABTypedefs.h

Discussion

These constants are used in a call to the ABGroupCreateSearchElement or ABPersonCreateSearchElement function to specify the type of comparison being made.

Version Notes

ABSearchConjunction

Constants used to create compound search elements.

enum ABSearchConjunction {
   kABSearchAnd = 0,
   kABSearchOr = 1
};

Constants

kABSearchAnd

Join the search elements together with the AND operand.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

kABSearchOr

Join the search elements together with the OR operand.

Available in Mac OS X v10.2 and later.

Declared in ABTypedefs.h

Discussion

These constants are used to create compound search elements with the ABSearchElementCreateWithConjunction function.

Version Notes

Next Page >

Hide TOC

Last updated: 2005-04-29

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice