find

Purpose

Searches the user's address book for entries matching the given parameters.

Signature

find( options, callbacks )

Returns

This method does not return anything.

Parameter

Name	Description
options	An object containing search parameters. Please see the table below for more information.
callbacks	An object containing two callback methods listed below.

The table below lists the supported parameters.

Parameter	Description	Use
filterValue	A string value that will be matched against selected fields. Required for the filter to work.	Required
filterOp	A filter operation. The Contacts API supports the following two operations: "is" and "contains". The default value is "contains".	Optional
filterBy	An array of field names to include in filter. Required for the filter to work.	Required
filterLimit	A maximum number of search results.	Optional
sortBy	The name of the field, by which search results will be sorted. Required for the sorting function to work. Only fields of the type "string" are allowed.	Required
sortOrder	The Contacts API supports the following two sorting orders: "ascending" and "descending". The default value is "ascending".	Optional

For example:

var options = {
          filterValue : "Developer",
          filterOp    : "is",
          filterBy    : ["jobTitle"],
          sortBy      : "givenName",
          sortOrder   : "ascending",
          filterLimit : 100
        };

The following table lists the phone number types that may be returned in the type property of the phone number list.

Type	Description
mobile	Denotes a mobile phone number.
home	Indicates a home phone number.
work	Indicates a work phone number.
company	Denotes a company phone number.
pager	Denotes a pager number.
fax-home	Indicates a home fax number.
fax-work	Indicates a work fax number
iphone	Indicates an IP phone number
other	A phone number that does not match the above categories.

The following table lists the email types that may be returned in the type property of the phone number list.

Type	Description
home	Denotes a home email address.
work	Indicates a work email address.
other	Indicates an address that does not match the above categories.

Tip

In addition to the above listed types, platform-specific types can also be returned.

Callbacks object structure

The remove listener's callbacks object can be structured as follows:

{
    onSuccess: function (contact) { ... },
    onFailure: function (error) { ... }
}

Callback methods

Name	Description	Return type
onSuccess	A callback function that accepts an array of contact entries that match the query. The entries of the returned contacts array are consistent with the section 5.1 of the The Contact dictionary specification.	`undefined`
onFailure	Passed to notify that the process could not be completed. It passes an object that contains a description of an error.	`undefined`

Contacts methods