Mac Developer Library

Developer

AddressBook Framework Reference ABSearchElement C Reference

Options
Deployment Target:

On This Page
Language:

ABSearchElement C Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AddressBook

Objective-C

@import AddressBook;

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

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

    Declaration

    Swift

    func ABSearchElementCreateWithConjunction(_ conjunction: ABSearchConjunction, _ children: CFArray!) -> Unmanaged<ABSearchElement>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Tests whether or not a record matches a search element.

    Declaration

    Swift

    func ABSearchElementMatchesRecord(_ searchElement: ABSearchElement!, _ record: ABRecordRef) -> Bool

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Data Types

  • A reference to an ABSearchElement object.

    Declaration

    Swift

    typealias ABSearchElementRef = ABSearchElement

    Objective-C

    typedef struct __ABSearchElementRef *ABSearchElementRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Constants

  • Constants used to specify the type of comparison being made.

    Declaration

    Swift

    typealias ABSearchComparison = CFIndex

    Objective-C

    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

      kABEqual

      Search for elements that are equal to the value.

      Available in OS X v10.2 and later.

    • kABNotEqual

      kABNotEqual

      Search for elements that are not equal to the value.

      Available in OS X v10.2 and later.

    • kABNotEqualCaseInsensitive

      kABNotEqualCaseInsensitive

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

      Available in OS X v10.4 and later.

    • kABLessThan

      kABLessThan

      Search for elements that are less than the value.

      Available in OS X v10.2 and later.

    • kABLessThanOrEqual

      kABLessThanOrEqual

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

      Available in OS X v10.2 and later.

    • kABGreaterThan

      kABGreaterThan

      Search for elements that are greater than the value.

      Available in OS X v10.2 and later.

    • kABGreaterThanOrEqual

      kABGreaterThanOrEqual

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

      Available in OS X v10.2 and later.

    • kABEqualCaseInsensitive

      kABEqualCaseInsensitive

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

      Available in OS X v10.2 and later.

    • kABContainsSubString

      kABContainsSubString

      Search for elements that contain the value.

      Available in OS X v10.2 and later.

    • kABContainsSubStringCaseInsensitive

      kABContainsSubStringCaseInsensitive

      Search for elements that contain the value, ignoring case.

      Available in OS X v10.2 and later.

    • kABPrefixMatch

      kABPrefixMatch

      Search for elements that begin with the value.

      Available in OS X v10.2 and later.

    • kABPrefixMatchCaseInsensitive

      kABPrefixMatchCaseInsensitive

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

      Available in OS X v10.2 and later.

    • kABSuffixMatch

      kABSuffixMatch

      Search for elements that end with the value.

      Available in OS X v10.4 and later.

    • kABSuffixMatchCaseInsensitive

      kABSuffixMatchCaseInsensitive

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

      Available in OS X v10.4 and later.

    • kABBitsInBitFieldMatch

      kABBitsInBitFieldMatch

      Search for elements that match the bits in ABPersonFlags.

      Available in OS X v10.3 and later.

    • kABDoesNotContainSubString

      kABDoesNotContainSubString

      Search for elements that do not contain the value.

      Available in OS X v10.4 and later.

    • kABDoesNotContainSubStringCaseInsensitive

      kABDoesNotContainSubStringCaseInsensitive

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

      Available in OS X v10.4 and later.

    • kABWithinIntervalAroundToday

      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.

    • kABWithinIntervalAroundTodayYearless

      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.

    • kABNotWithinIntervalAroundToday

      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.

    • kABNotWithinIntervalAroundTodayYearless

      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.

    • kABWithinIntervalFromToday

      kABWithinIntervalFromToday

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

      Available in OS X v10.4 and later.

    • kABWithinIntervalFromTodayYearless

      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.

    • kABNotWithinIntervalFromToday

      kABNotWithinIntervalFromToday

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

      Available in OS X v10.4 and later.

    • kABNotWithinIntervalFromTodayYearless

      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.

    Discussion

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

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Constants used to create compound search elements.

    Declaration

    Swift

    typealias ABSearchConjunction = CFIndex

    Objective-C

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

    Constants

    • kABSearchAnd

      kABSearchAnd

      Join the search elements together with the AND operand.

      Available in OS X v10.2 and later.

    • kABSearchOr

      kABSearchOr

      Join the search elements together with the OR operand.

      Available in OS X v10.2 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.