AppFindContact Method (CLIENT)

PLB Web Only, 9.9

The AppFindContact method retrieves a mobile device's contact information. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A CLIENT object.

return

Optional. A Numeric Variable that returns the success or failure of the method.

fields

Required. A Character String Variable or string literal that is a JSON string giving the Contact fields to use as a search qualifier.

options

Optional. A Character String Variable or string literal that specifies a JSON notation string that is passed directly to the Cordova routine used for this method.

Flags Affected: OVER, ZERO

Note the following:

1. The ZERO flag is set when the {return} value is zero.

2. The OVER flag is set if the value returned is too large to be stored into the {return} variable.

3. A zero-length (NULL) parameter is invalid and results in INVALID_ARGUMENT_ERROR. A value of "*" searches all contact fields.

4. The {fields} JSON string is formatted to include the names used when searching the mobile device contacts:

 

JSON string:

 

["displayName","name"]

 

 Example:

 

FindContact INIT "[#"displayName#",#"name#"]"

 

5. The {options} parameter is passed directly as a JSON object to the Cordova routine. See the plugin documentation for more information. The parameter uses the following fields:

 

Field	Description
filter	The search string finds navigator.contacts. If the JSON "filter" name is not specified, the default behavior is to search all contacts (Default: ""). If provided, a case-insensitive, partial value match is applied to each field specified in the 'Fields' parameter. If there is a match for any of the specified fields, the contact is returned.
multiple	Determines if the find operation returns multiple navigator.contacts. (Default: `false`)
desiredField	Specify the Contact fields that are returned as previously defined by event data Contact JSON object description. For the specified Contact fields, the resulting `Contact` object only returns values for these fields.
hasPhoneNumber	(Android only) Filters the search to only return contacts with a phone number informed. (Default: `false`)

 

6. This method executes asynchronously, querying the device contacts database. A result is returned as an 'AppEventGetContact' event with the event data being returned in ARG1 in JSON notation.

 

The event number used in EVENTREG is:

 

AppEventGetContact EQU 108 //Event number for EVENTREG.

 

The event data returned by this method can be either as a JSON error object or as an array of Contact JSON objects where the data is returned in the PLB Event ARG1 parameter.

 

A JSON error object contains the fields of:

 

Field	Description
code	One of the predefined error codes listed below:   0 - UNKNOWN_ERROR 1- INVALID_ARGUMENT_ERROR 2 - TIMEOUT_ERROR 3 - PENDING_OPERATION_ERROR 4 - IO_ERROR 5 - NOT_SUPPORTED_ERROR 6 - OPERATION_CANCELLED_ERROR 20- PERMISSION_DENIED_ERROR
message	Error message description.

 

An array of Contact JSON objects with the fields:

 

 

Field	Description
id	A globally unique identifier.
displayName	The name of this Contact, suitable for display to end users.
name	An object containing all components of a person's name.
nickname	A casual name by which to address the contact.
phoneNumbers	An array of all the contact's phone numbers.
emails	An array of all the contact's email addresses.
addresses	An array of all the contact's addresses.
ims	An array of all the contact's IM addresses.
organizations	An array of all the contact's organizations.
birthday	The birthday of the contact.
note	A note about the contact
photos	An array of the contact's photos.
categories	An array of all the user-defined categories associated with the contact.
urls	An array of web pages associated with the contact.

 

Example Event Data returned in ARG1:

 

{

   "id": "{5.70002.30}",

   "rawId": null,

   "displayName": "Tom Smith",

   "name":

      {

      "formatted": "Tom Smith",

      "familyName": "Smith",

      "givenName": "Tom",

      "middleName": null,

      "honorificPrefix": null,

      "honorificSuffix": null

      },

   "nickname": "Tom",

   "phoneNumbers": [],

   "emails": [],

   "addresses": [],

   ims": [],

   "organizations": [],

   "birthday": null,

   "note": null,

   "photos": null,

   "categories": null,

   "urls": null

}

Example Code

 

Cl CLIENT

.

   EventReg Cl,AppEventGetContact,GetContactFunc,ARG1=ContactData

.

   Cl.AppFindContact Using *Fields="[#"displayName#",#"name#"]":

     *Options="{#"filter#": #"Bob#"}"

See Also: CLIENT, Client Methods, Method Syntax