DISCONTINUATION OF PROJECT.
This project will no longer be maintained by Intel.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this project.
If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project. DISCONTINUATION OF PROJECT. This project will no longer be maintained by Intel. Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates. Patches to this project are no longer accepted by Intel. In an effort to support the developer community, Intel has made this project available under the terms of the Apache License, Version 2. If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the community, please create your own fork of the project.
For access to the on-device contacts database.
The contacts plugin gives programmers access to the default contacts database on the native device. The application must be built with appropriate permissions in order for this capability to work.
The plugin vends “contact objects” which represent entries in the native contacts database. Each contact object has the following properties:
- id: An identifier which is unique to this contact, and which can be used to refer to it in plugin method calls. It may be either a number or a string, depending on the platform.
- last: A string containing the last name of the person.
- first: A string containing the first name of the person.
- name: A string containing the entire name of the person. (Not necessarily just the concatenation of the first and last names.)
- emails: An array of strings containing email addresses.
- phones: An array of strings containing phone numbers.
- addresses: An array of objects representing addresses.
An address object has the following properties:
- street: A string containing the street address. (May contain multiple lines separated by line-feed characters.)
- city: A string containing the city name.
- state: A string containing a state or province name or abbreviation.
- zip: A string containing a zip or postal code.
- country: A string containing a country name or abbreviation.
The plugin keeps an internal contact list, which is a cached copy of the device
contacts database. The internal contact list is not initialized automatically,
and a call to getContactList or
getContactData will return null if it has not been
initialized.
The internal contact list may be explicitly initialized by a call to getContacts, or implicitly initialized or updated by a successful call to addContact, chooseContact, editContact, or removeContact.
Note that a change to the device contacts database made other than through the plugin will not be reflected in the internal contact list until it is initialized or updated.
Note that methods that access or manipulate the contacts database may present the platform native interface for that functionality.
- addContact — Allow the user to add a contact.
- chooseContact — Allow the user to choose a contact.
- editContact — Allow the user to edit a contact.
- getContactData — Return the contact object with a particular identifier.
- getContactList — Return an array of the identifiers of all contacts in the database.
- getContacts — Fetch the device contact database into the plugin.
- removeContact — Remove a specified contact.
- intel.xdk.contacts.add — The user has added a contact.
- intel.xdk.contacts.busy — An operation was requested when another operation was already in progress.
- intel.xdk.contacts.choose — The user has selected a contact.
- intel.xdk.contacts.edit — The user has finished editing a contact.
- intel.xdk.contacts.get — The device contact database has been fetched into the plugin.
- intel.xdk.contacts.remove — A contact has been removed.
Invokes the system “add contact” dialog.
intel.xdk.contacts.addContact();This method displays the native device’s UI to allow the user to add a new contact.
- Apple iOS
- Google Android
- intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
- intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
- intel.xdk.contacts.add(success, contactid): If success is
true, then the user added a new contact whose id is contactid. If success isfalse, the user cancelled the dialog, and contactid is undefined.
Note: If the internal contact list was uninitialized before the call and the user canceled the add operation (i.e., success was
false), then the internal contact list is still uninitialized.
document.addEventListener('intel.xdk.contacts.add', onContactAdded);
intel.xdk.contacts.addContact();
function onContactAdded(evt) {
if (evt.success == true)
{
alert("Contact "+evt.contactid+" successfully added");
}
else
{
alert("Add Contact Cancelled");
}Invokes the system “choose contact” dialog.
intel.xdk.contacts.chooseContact();This method displays the native device’s UI to allow the user to choose a contact from the contact database.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
- intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
- intel.xdk.contacts.choose(success, contactid): If
success is
true, then the selected the contact whose id is contactid. If success isfalse, the user cancelled the dialog, and contactid is undefined.
Note: If the internal contact list was uninitialized before the call and the user canceled the choose operation (i.e., success was
false), then the internal contact list is still uninitialized.
document.addEventListener('intel.xdk.contacts.choose', onChooseContact);
intel.xdk.contacts.chooseContact();
function onChooseContact(evt) {
if (evt.success == true)
{
intel.xdk.contacts.editContact(evt.contactid);
}
else
{
alert("Choose Contact Cancelled");
}Invokes the system “edit contact” dialog.
intel.xdk.contacts.editContact(contactID);This method displays the native device's contacts application to allow the user to edit a specified contact.
- Apple iOS
- Google Android
- contactID: The contact ID of the contact to be edited.
- intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
- intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
- intel.xdk.contacts.edit(success, contactid): If
success is
true, then the edited the contact whose id is contactid. If success isfalse, the user cancelled the dialog. In either case, contactid is the same as the contactID from theeditcall.
Note: If the internal contact list was uninitialized before the call and the user canceled the edit operation (i.e., success was
false), then the internal contact list is still uninitialized.
document.addEventListener('intel.xdk.contacts.edit', onContactEdit);
intel.xdk.contacts.editContact(contactID);
function onEditContact(evt) {
if (evt.success == true)
{
alert("Contact "+evt.contactid+" successfully updated");
}
else
{
alert("Edit Contact Cancelled");
}Get a specified contact object.
contactObj = intel.xdk.contacts.getContactData(contactID);This method gets the contact object with a specified contact id.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- contactID: The contact ID of the contact to be fetched.
- The contact object in the
internal contact list whose
idproperty is contactID. nullif the internal contact list has not been initialized, or does not contain a contact object with the specified contact ID.
function contactsReceived() {
var table = document.getElementById("contacts");
table.innerHTML = '';
var myContacts = intel.xdk.contacts.getContactList();
for(var i=0;i<myContacts.length;i++) {
//add row to table
var contactInfo =
intel.xdk.contacts.getContactData(myContacts[i]);
var tr = document.createElement("tr");
tr.setAttribute('id', 'pnid'+contactInfo.id);
tr.setAttribute('onClick',
'document.getElementById("iden").value =
'+contactInfo.id+';');
tr.setAttribute('style', 'background-color:#B8BFD8');
var id = document.createElement("td");
id.innerHTML = contactInfo.id;
tr.appendChild(id);
var msg = document.createElement("td");
msg.innerHTML = contactInfo.name;
tr.appendChild(msg);
table.appendChild(tr);
}
}Get all the contact IDs.
contactListArray = intel.xdk.contacts.getContactList();This method gets an array containing the contact ID property of every contact object.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- An array containing the contact ID property of every contact object.
nullif the internal contact list has not been initialized.
document.addEventListener('intel.xdk.contacts.get', contactsReceived, false);
function contactsReceived() {
var table = document.getElementById("contacts");
table.innerHTML = '';
var myContacts = intel.xdk.contacts.getContactList();
for(var i=0;i<myContacts.length;i++) {
//add row to table
var contactInfo = intel.xdk.contacts.getContactData(myContacts[i]);
var tr = document.createElement("tr");
tr.setAttribute('id', 'pnid'+contactInfo.id);
tr.setAttribute('onClick', 'document.getElementById("iden").value =
'+contactInfo.id+';');
tr.setAttribute('style', 'background-color:#B8BFD8');
var id = document.createElement("td");
id.innerHTML = contactInfo.id;
tr.appendChild(id);
var msg = document.createElement("td");
msg.innerHTML = contactInfo.name;
tr.appendChild(msg);
table.appendChild(tr);
}
}Initialize the plugin internal contact list from the device contacts database.
intel.xdk.contacts.getContacts();This plugin maintains an internal copy of the device contacts database. The getContactList and getContactData methods retrieve information from the internal contact list, not directly from the device database. Therefore, the internal copy must be initialized from the system database before getContactList or getContactData is called. That initialization can occur explicitly with a call to this method, or implicitly with a successful call to addContact, removeContact, chooseContact, or editContact.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database. The internal list has not been initialized.
- intel.xdk.contacts.get(success): The internal contact list has been initialized. success will always be true.
document.addEventListener('intel.xdk.contacts.get', contactsReceived, false);
intel.xdk.contacts.getContacts();Remove a contact.
intel.xdk.contacts.removeContact(contactID);This method removes a specified contact.
- Apple iOS
- Google Android
- contactID: The contact ID of the contact to remove
- intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
- intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
- intel.xdk.contacts.remove(success, contactid, error):
If success is
true, then the contact whose id is contactid has been removed. If success isfalse, the contacts database has not been changed, and error is a string describing the reason the contact was not removed.
Note: If the internal contact list was uninitialized before the call and the remove operation failed for any reason (i.e., success was
false), then the internal contact list is still uninitialized.
document.addEventListener('intel.xdk.contacts.remove', onContactRemoved);
intel.xdk.contacts.removeContact(contactID);
function onEditContact(evt) {
if (evt.success == true)
{
alert("Contact "+evt.contactid+" has been removed");
}
}An addContact operation is complete.
This event is fired in response to an addContact call when the user either finishes adding a contact or cancels the operation.
- success:
trueif the user added a contact;falseif the user canceled the operation. - contactid: The
idproperty of the added contact if success istrue; undefined if success is false.
An operation could not be performed because another operation was already in progress.
This event is fired when the addContact, chooseContact, editContact, or removeContact method is called, but one of those methods has previously been called and has not finished.
A chooseContact operation is complete.
This event is fired in response to a chooseContact call when the user either finishes choosing a contact or cancels the operation.
- success:
trueif the user chose a contact;falseif the user canceled the operation. - contactid: The
idproperty of the chosen contact if success istrue; undefined if success is false.
An editContact operation is complete.
This event is fired in response to an editContact call when the user either finishes editing the contact or cancels the operation.
- success:
trueif the user edited the contact;falseif the user canceled the operation. - contactid: The
idproperty of the contact that was to be edited, whether or not it was actually edited.
The internal contact list has been initialized or updated from the device contacts database.
This event is fired in response to a getContacts call when the initialization or update of the internal contacts list is complete.
The application does not have permission to access the system contacts database.
An operation that needs to access the device contacts database has failed, either because the application was not built with the privileges required to access the database, or because the user has refused to allow the application to access the database.
A removeContact operation is complete.
This event is fired in response to a removeContact call when the operation completes, either successfully or unsuccessfully.
- success:
trueif the contact was removed;falseotherwise. - contactid: The
idproperty of the contact that was to be removed, whether or not it was actually removed. - error: A string describing the reason the contact was not removed if
success is
false; undefined if success istrue.