voltmx.contact Namespace

This API adds a contact to the address book of the mobile device.

Syntax

voltmx.contact.add([contactDetails](#contactDetails))

Input Parameters

contactDetails [Table] - Mandatory

A table that has the following key-value pairs.

Example (For website key)

{
    "website": [{
        "url": "www.google.com",
        "type": "homepage"
    }, {
        "url": "www.myblog.com",
        "type": "blog"
    }, {
        "url": "www.voltmx.com",
        "type": "work"
    }, {
        "url": "www.myprofile.com",
        "type": "profile"
    }, {
        "url": "www.facebook.com",
        "type": "profile"
    }]
}

Note: firstname and phone fields are mandatory with at least one phone number in phone field

The following are the Labels for different fields in the table:

Example

//Contact Details.
var mycontact = {
    firstname: "John",
    lastname: "Steve",
    phone: [{
        name: "mobile",
        number: "9999999999"
    }, {
        name: "home",
        number: "9999999999"
    }],
    email: [{
        name: "home",
        id: "abc@yahoo.com"
    }, {
        name: "work",
        id: "def@voltmx.com"
    }],
    postal: [{
        name: "home",
        street: "Raheja",
        city: "hyderabad",
        state: "AP",
        zipcode: "500310"
    }],
    company: [{
        name: "work",
        company: "voltmx",
        title: "architect"
    }]
};
//Adding the contact to your device.
voltmx.contact.add(mycontact);
this.view.lblDevContact.text = "Contact is added with firstname = 'John' and lastname = 'Steve' . Please Check the device contacts.";

Return Values

The following are the return values for this API:

Error Codes

If any of the field is not stored, the field is ignored. If no field is stored, an error is raised.

Implementation Details

The following are the implementation details:

• firstname and phone field with empty string or nil does not create a contact and the API call is ignored.
• Other fields with empty string or nil or invalid data type assignment are ignored.
• id field is read only property and must not be modified by the application.

API Usage

When you use this API with Android emulator that uses Android SDK 2.0 and above, you will be prompted to create an account to add contacts.

Creating an account (Google/GMail) is a mandate to add contacts. This is an Android platform limitation.

Ensure that the following permissions are set for Android:

• READ_CONTACTS
• WRITE_CONTACTS
• GET_ACCOUNTS.

You can set these permissions for Android under Manifest Properties in Project Properties -> Native App -> Android. For more information about Android Manifest permissions, see Volt MX IrisUser Guide.

Platform Availability

• iOS
• Android
• Windows

This API displays the details of a given contact and returns a new instance of the contact structure.

The API is introduced to improve the performance and for effective utilization of memory. In platforms like Android, contact information is stored in multiple database tables, one table contains the contact id, first name, and lastname, and the another table contains the entire contact details. The contacts application displays only firstname, lastname in the initial screen, and when the user selects a particular contact, the details are shown in next screen.

When you to accommodate the contact details in one call to contact.find API, the memory is not sufficient when the contacts are numerous. This results in an out of memory issue and results in performance issues in many applications.

Syntax

voltmx.contact.details([ReferenceTable](#ReferenceTable1))

Input Parameters

Example

//Use the below function to retrieve the contact details.
getDetails: function() {
    //Finding the contact whose details are to be retrieved.
    var findContacts = voltmx.contact.find("John");
    if (findContacts === null || findContacts === "" || findContacts === undefined) {
        this.view.lblDevContact.text = "No contacts with the first name is 'John' ";
    } else {
        //Retrieving the contact details.
        var a = voltmx.contact.details(findContacts);
        this.view.lblDevContact.text = a;
    }

}

Return Values

Example of the reference table returned:

{
 firstname = "John", middleName = "Cena"
lastname = "Xyz",

//array of arrays containing "Label" and "number"
phone = {
    {
        name = "mobile", number = "99999999999"
    },

   ////array of arrays containing "Label" and "emailid"
    {
        name = "home", number = "99999999999"
    }, {
        name = "home", number = "5555555555"
    }, .....
},
email = {
    {
        name = "home", id = "abc@yahoo.com"
    }, {
        name = "work", id = "def@voltmx.com"
    }, ....
},

////array of arrays containing "Label" and address in a table with 
defined keys.

postal = {
    name = "home", street = "ABC", city = "hyderabad", state = "AP", zipcode = "500310"
}, {
    name = "work", street = "XYZ", city = "hyderabad", state = "AP", zipcode = "500010"
}, ...
},

//array of arrays containing "Label" followed by table with company name 
and title keys.
company = {
    {
        name = "work", company = "voltmx", title = "Tester"
    }, {
        name = "other", company = "abc", title = "VP"
    }, ...
},
id = "platform specific identifier for the contact"
photorawbytes = rawbytes
}

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web.

This API parses through the address book of the mobile device and looks for contacts that match the input string.

Syntax

voltmx.contact.find([firstName](#firstName), [needdetails](#needdetails), [filterKeys](#filterKeys))

Input Parameters

Example

//Finding the contact whose details are to be retrieved.
var findContacts = voltmx.contact.find("John");

Return Values

Implementation Details

This API searches and matches only the contacts that have the firstname as the specified input string.

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web.

This API deletes the contact (s) that was returned by the contact.find operation.

Syntax

voltmx.contact.remove([ReferenceTable](#ReferenceTable))

Input Parameters

Example

var array = voltmx.contact.find('John', false);
voltmx.contact.remove(array);

Return Values

Platform Availability

Available on all platforms except SPA, Desktop Web, Mobile Web.