ABSearchElement C Reference

Derived from
Framework
AddressBook/ABAddressBookC.h
Companion 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 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 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 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 OS X v10.2 and later.

Declared in ABTypedefs.h.

kABNotEqual

Search for elements that are not equal to the value.

Available in 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 OS X v10.4 and later.

Declared in ABTypedefs.h.

kABLessThan

Search for elements that are less than the value.

Available in 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 OS X v10.2 and later.

Declared in ABTypedefs.h.

kABGreaterThan

Search for elements that are greater than the value.

Available in 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 OS X v10.2 and later.

Declared in ABTypedefs.h.

kABEqualCaseInsensitive

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

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABContainsSubString

Search for elements that contain the value.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABContainsSubStringCaseInsensitive

Search for elements that contain the value, ignoring case.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABPrefixMatch

Search for elements that begin with the value.

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABPrefixMatchCaseInsensitive

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

Available in OS X v10.2 and later.

Declared in ABTypedefs.h.

kABSuffixMatch

Search for elements that end with the value.

Available in OS X v10.4 and later.

Declared in ABTypedefs.h.

kABSuffixMatchCaseInsensitive

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

Available in OS X v10.4 and later.

Declared in ABTypedefs.h.

kABBitsInBitFieldMatch

Search for elements that match the bits in ABPersonFlags.

Available in OS X v10.3 and later.

Declared in ABTypedefs.h.

kABDoesNotContainSubString

Search for elements that do not contain the value.

Available in OS X v10.4 and later.

Declared in ABTypedefs.h.

kABDoesNotContainSubStringCaseInsensitive

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

Available in 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 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 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 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 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 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 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 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 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 OS X v10.2 and later.

Declared in ABTypedefs.h.

kABSearchOr

Join the search elements together with the OR operand.

Available in 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