Phonegap Bridge – Telephony CIS 136 Building Mobile Apps 1

Telephony Contacts API 2

Contacts API Plugin: org.apache.cordova.contacts 3  provides an interface that can be used to create, locate, edit, copy and delete contacts  Interfaces with the native Contacts API provided by the mobile platform  Contacts API is available thru the navigator object

Creating a contact 4  Synchronous API call  Has no callback functions  Creates an empty object  Syntax: var contact = navigator.contacts.create();  Next steps are:  to populate the properties of the object with contact data  save the object to the Contacts’ application database

Example 5 Contact Example document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { var myContact = navigator.contacts.create({"displayName": "Test User"}); myContact.note = "This contact has a note."; console.log("The contact, " + myContact.displayName + ", note: " + myContact.note); } Example Create Contact

Finding a contact 6  Asynchronous API call  Queries the device contacts database and returns an array of Contact objects  Syntax: navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions); Parameters  contactFields: Contact fields to use as a search qualifier. The resulting Contact object only features values for these fields. (DOMString[]) [Required]  contactSuccess: Success callback function invoked with the contacts returned from the database. [Required]  contactError: Error callback function, invoked when an error occurs. [Optional]  contactFindOptions: Search options to filter contacts. [Optional]

contactFind options 7  properties that can be used to filter the results of a contacts.find operation  filter: The search string used to filter contacts. (DOMString) (Default: "")  multiple: Determines if the find operation returns multiple contacts. (Boolean) (Default: false)

Example 1 8 // success callback function onSuccess(contacts) { for (var i=0; i<contacts.length; i++) { alert(contacts[i].displayName); } }; // error callback function onError(contactError) { alert('onError!'); }; // specify contact search criteria var options = new ContactFindOptions(); options.filter=""; // empty search string returns all contacts options.multiple=true; // return multiple results fieldsToReturn = ["displayName"]; // return contact.displayName field // find contacts navigator.contacts.find(fieldsToReturn, onSuccess, onError, options);

Example 2 9 document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { // find all contacts with 'Bob' in any name field var options = new ContactFindOptions(); options.filter = "Bob"; var fieldsToReturn = ["displayName", "name"]; navigator.contacts.find(fields,ToReturn onSuccess, onError, options); } function onSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { console.log("Display Name = " + contacts[i].displayName); } function onError(contactError) { alert('onError!'); } Example Find Contacts

10 Look at your contacts on your mobile device what fields do you see on your device?

Contact Objects 11  Objects  Contact  ContactName  ContactField  ContactAddress  ContactOrganization  ContactFindOptions  ContactError

Contact Object methods 12  clone()  Returns a new Contact object that is a deep copy of the calling object, with the id property set to null.  remove()  Removes the contact from the device contacts database, otherwise executes an error callback with a ContactError object.  save()  Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.

Contact object properties describe a contact, such as a user's personal or business contact 13  id  A unique identifier for the contact  displayName  The name of the contact  name  (object) – defines different components of the name (i.e. given name, family name, middle name, etc.)  nickname  Casual name  phoneNumbers  (array) –phone numbers  s  (array) addresses  Addresses  (array) – physical addresses – home, business, etc.

Contact properties (continued) 14  ims  (array) – instant messaging addresses  Organizations  (array) – a list of the organizations the contact is associated with  Birthday  Contacts date of birth  note  Variable used for text-based notes  photos  (array) – photos of the contact  categories  (array) user-defined categories associated with the contacts (i.e. friend, family, etc)  urls  (array) – web addresses associated with the contact

Name Object defines different components of the name (i.e. given name, family name, middle name, etc.) 15  Includes string values:  formatted: contacts complete name  givenName: family name  middleName: middle name  honorificPrefix: Dr. Mrs. Mr. etc  honorificSuffix: Jr, III, PhD, etc.

Example 16 var options = new ContactFindOptions(); options.filter = ""; fieldsToShow= ["displayName", "name"]; navigator.contacts.find(fieldsToShow, onSuccess, onError, options); function onSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { alert("Formatted: " + contacts[i].name.formatted + "\n" + "Family Name: " + contacts[i].name.familyName + "\n" + "Given Name: " + contacts[i].name.givenName + "\n" + "Middle Name: " + contacts[i].name.middleName + "\n" + "Suffix: " + contacts[i].name.honorificSuffix + "\n" + "Prefix: " + contacts[i].name.honorificSuffix); } }; function onError(contactError) { alert('onError!'); };

Addresses (array) – physical addresses – home, business, etc. 17  Two-dimensional array of contact address objects with these values  pref:  Boolean value that defines if the entry is the default address for the contact  type:  String defining the address type (home/work)  formatted:  Full address formatted for display  streetAddress:  Full street address  locality:  city  region:  state  postalCode:  Zip code  country  Country associated with address

Example 18 function onSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { for (var j = 0; j < contacts[i].addresses.length; j++) { alert("Pref: " + contacts[i].addresses[j].pref + "\n" + "Type: “ + contacts[i].addresses[j].type + "\n" + "Formatted: " + contacts[i].addresses[j].formatted + "\n" + "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" + "Locality: " + contacts[i].addresses[j].locality + "\n" + "Region: " + contacts[i].addresses[j].region + "\n" + "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" + "Country: " + contacts[i].addresses[j].country); } }; function onError(contactError) { alert('onError!'); }; // find all contacts var options = new ContactFindOptions(); options.filter = ""; var fieldsToShow = ["displayName", "addresses"]; navigator.contacts.find(fieldsToShow, onSuccess, onError, options);

Organizations (array) – a list of the organizations the contact is associated with 19  Two-dimensional array of organization objects with these values  pref:  Boolean value that defines if the entry is the preferred or default organization for the contact  type:  String defining the type of organization (home/work)  name:  name of the organization  department:  department where the contact works  title:  Contacts title in the organizations

Example 20 function onSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { for (var j = 0; j < contacts[i].organizations.length; j++) { alert("Pref: " + contacts[i].organizations[j].pref + "\n" + "Type: " + contacts[i].organizations[j].type + "\n" + "Name: " + contacts[i].organizations[j].name + "\n" + "Department: " + contacts[i].organizations[j].department + "\n" + "Title: " + contacts[i].organizations[j].title); } }; function onError(contactError) { alert('onError!'); }; var options = new ContactFindOptions(); options.filter = ""; filter = ["displayName", "organizations"]; navigator.contacts.find(filter, onSuccess, onError, options);

Phones, s, and ims 21  Two-dimensional array of objects with these values  pref:  Boolean value that defines if the entry is the default value  type:  String defining the type of value (home/work)  value:  Contact value such as phone number or address

Example 22 var contact = navigator.contacts.create(); // store contact phone numbers in ContactField[] var phoneNumbers = []; phoneNumbers[0] = new ContactField('work', ' ', false); phoneNumbers[1] = new ContactField('mobile', ' ', true); phoneNumbers[2] = new ContactField('home', ' ', false); contact.phoneNumbers = phoneNumbers; // save the contact contact.save();

Contact data example 23 JSON string { “FullName”: “Michael Smith”, “LastName”: “Smith”, “Firstname”: “Michael”, “ Address”: “OfficePhone:” : “ ”, “MobilePhone”: “ ” }

Contact Success 24  provides the Contact array resulting from a contacts.find operation  Parameters  contacts: The contact array resulting from a find operation

Contact Error 25  Returned through the ContactError callback function  Properties  code: One of the predefined error codes listed below.  Constants  ContactError.UNKNOWN_ERROR  ContactError.INVALID_ARGUMENT_ERROR  ContactError.TIMEOUT_ERROR  ContactError.PENDING_OPERATION_ERROR  ContactError.IO_ERROR  ContactError.NOT_SUPPORTED_ERROR  ContactError.PERMISSION_DENIED_ERROR