AppPickContact Method (CLIENT)

PLB Web Only, 9.9

The AppPickContact method launches the Contact Picker to select a single contact from the device contacts database. 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.

Flags Affected: OVER, ZERO

Note the following:

1. This method is only used for a Sunbelt PL/B Web Client App using Cordova\PhoneGap operations. See the following link for details on the Cordova plugin used:

 

     https://www.npmjs.com/package/cordova-plugin-contacts

 

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

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

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

5. The method starts an asynchronous Contact Picker dialog on mobile device and a result is generated as a PLB 'AppEventContactPicked' CLIENT object event with the event data being returned in ARG1 in JSON notation.

 

The event number used in EVENTREG is:

 

AppEventContactPicked EQU 101 //Event number for EVENTREG.

 

The event data is returned by this method either with an Error JSON object or a Contact JSON object.

 

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.

 

Contact JSON Object Event Data fields are defined as follows:

 

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

 

resContact DIM 500

nRes FORM 3

.

        EventReg Client,AppEventContactPicked,ContactEvent,ARG1=resContact

.

        Client.AppPickContact GIVING nRes

See Also: CLIENT, Client Methods, Method Syntax