Skip to content

voltmx.contact Namespace

The voltmx.contact namspace, which is a part of the Phone API, provides the following API elements:

voltmx.contact Functions

The voltmx.contact namespace contains the following functions:

Note: The runtime permissions are applicable only in the iOS and Android platforms.

voltmx.contact.add

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.

Key Description
firstname specifies the first name of the contact
lastname specifies the last name of the contact
phone array of arrays containing Label and number
> Note: The phone number can contain a + (for country code), - (hyphen) (to separate country code, STD code, and the number), and space ((to separate country code, STD code, and the number). No other characters are allowed within a phone number.For example, +919999999999, +91 99999 99999, or +91-99999-99999.
email array of arrays containing Label and emailID
postal array of arrays containing Label and address in a table with defined keys
company array of arrays containing Label followed by table with company name and title keys
website array of arrays containing url and type. The possible types for the website key are as follows.Android: home, homepage, work, and othersiOS: home, homepage, work, ftp, blog, profile, and others

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:

Keys in the Table Possible Labels
phone •Mobile •Home •Work •Other
email •Home •Work •Other
postal •Home •Work •Other
company •Work •Other

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:

Return Value Description
Reference [Table] Table containing the information related to the newly created contact is returned.
nil If the contact was not created.

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
voltmx.contact.details

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

Parameter Description
ReferenceTable - Mandatory Specifies the reference table returned by the contact.find API

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

Return Value Description
Reference [Table] Table of the contacts retrieved. The reference table retrieved contains a field photorawbytes. This is a new property in the existing contact structure that should be populated with raw bytes, just like camera or gallery raw bytes.
nil If no contact is retrieved.

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.

voltmx.contact.find

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

Parameter Description
firstName [String] - Mandatory A string that represents the firstname of the contact.
needdetails [Boolean] - Optional When the needdetails parameter is not passed, the default value is true. When needdetails is set to true, this API returns the complete details of the contact. If needdetails is false, contact.find returns a list of contacts with a new field called displayname in the existing contact structure. All other fields of contact structure are not populated. displayname is a combination of firstname, middlename, and lastname.
filterKeys [Array of strings] - Optional You can use the filterKeys parameter to filter your search by passing any of the available keys of this parameter. If filterKeys is specified and needDetails is false, only the display name is returned. The available filter keys are as follows: "firstname", "lastname", "phone", "postal", "email", "company", "photorawbytes", "displayname", and "id". The following platform-specific keys are available for the filterKeys parameter: For Android: "middlename"

Example


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

Return Values

Return Value Description
Reference [Object] Table containing the list of all the contacts that contain the input string
nil If there is no contact with the specified first name

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.

voltmx.contact.remove

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

Syntax


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

Input Parameters

Parameter Description
ReferenceTable - Mandatory Specifies the reference table returned by the contact.find API

Example


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

Return Values

Return Value Description
Reference [Table] Table of the contacts that is deleted
nil If there is no contact with the specified first name

Platform Availability

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

voltmx.contact.addAsync

The voltmx.contact.addAsync API asynchronously adds a contact to the mobile device's address book using the native Android Contact Picker. User interaction and approval are required to complete the operation.

The callback returns a status indicating whether the contact was added successfully, the operation was cancelled by the user, or an error occurred.

Syntax

voltmx.contact.addAsync(contact, callback);

Input Parameters

Parameter Type Description
contact Object Contact details to be added. At a minimum, the contact must include a first name and one phone number.
callback Function Callback function invoked with the result of the operation.

Callback Response

The callback receives a result object containing the operation status.

Status Description
success The contact was added successfully.
cancelled The user cancelled the operation.
Other status values The operation failed. Check errormsg for additional information, if available.

Example

var contact = {
    firstname: "John",
    lastname: "Doe",
    phone: [
        {
            name: "mobile",
            number: "1234567890"
        }
    ],
    email: [
        {
            name: "work",
            id: "john.doe@example.com"
        }
    ],
    company: [
        {
            name: "work",
            company: "Acme Inc"
        }
    ]
};

voltmx.contact.addAsync(contact, function(result) {
    if (result.status === "success") {
        voltmx.print("Contact added successfully");
    } else if (result.status === "cancelled") {
        voltmx.print("User cancelled contact creation");
    } else {
        voltmx.print(
            "Failed to create contact: " + (result.errormsg || "")
        );
    }
});

Notes

  • The native Contact Picker requires user interaction to complete the contact creation process.
  • The operation is asynchronous; handle the result in the callback.
  • The contact details are provided through the contact object. Ensure that the required fields are populated before invoking the API.

Platform Availability

  • Android.
voltmx.contact.detailsAsync

The voltmx.contact.detailsAsync API asynchronously retrieves contact details using the native Android Contact Picker. User interaction is required to select a contact.

The callback returns a status indicating whether the contact details were retrieved successfully, the user cancelled the operation, or an error occurred.

Syntax

voltmx.contact.detailsAsync(null, callback);

Input Parameters

Parameter Type Description
null Null Placeholder parameter used when invoking the contact picker.
callback Function Callback function invoked with the result of the operation.

Callback Response

The callback receives a result object containing the operation status.

Status Description
success The contact details were retrieved successfully.
cancelled The user cancelled contact selection.
Other status values The operation failed. Check errormsg for additional information, if available.

Example

voltmx.contact.detailsAsync(null, function(result) {
    if (result.status === "success") {
        voltmx.print("Contact details retrieved");
    } else if (result.status === "cancelled") {
        voltmx.print("User cancelled contact selection");
} else {
        voltmx.print(
            "Unable to get contact details: " + (result.errormsg || "")
        );
    }
});

Notes

  • The native Contact Picker requires user interaction to select a contact.

  • The operation is asynchronous; handle the result in the callback.

  • Review the returned result object to access the contact details.

Platform Availability

  • Android.
voltmx.contact.removeAsync

The voltmx.contact.removeAsync API asynchronously removes a contact from the mobile device's address book. This operation requires the appropriate contact access permissions, including WRITE_CONTACTS where applicable.

The callback returns a status indicating whether the contact was removed successfully, the user cancelled the operation, or an error occurred.

Syntax

voltmx.contact.removeAsync(contactOrReference, callback);

Input Parameters

Parameter Type Description
contactOrReference Object Contact details or a reference identifying the contact to be removed.
callback Function Callback function invoked with the result of the operation.

Callback Response

The callback receives a result object containing the operation status.

Status Description
success The contact was removed successfully.
cancelled The user cancelled the contact removal operation.
Other status values The operation failed. Check errormsg for additional information, if available.

Example

voltmx.contact.removeAsync(contactRef, function(result) {
    if (result.status === "success") {
        voltmx.print("Contact removed");
    } else if (result.status === "cancelled") {
voltmx.print("User cancelled contact removal");
    } else {
        voltmx.print(
            "Failed to remove contact: " + (result.errormsg || "")
        );
    }
});

Notes

  • Provide a valid contact object or reference identifying the contact to be removed.

  • The operation is asynchronous; handle the result in the callback.

  • Ensure that the application has the required permissions for the contact removal operation.

Platform Availability

  • Android
voltmx.contact.findAsync

The voltmx.contact.findAsync API asynchronously opens the native Android Contact Picker and allows the user to select a contact. The selected contact details are returned through the callback.

The callback returns a status indicating whether a contact was selected successfully, the user cancelled the operation, or an error occurred.

Syntax

voltmx.contact.findAsync("", callback);

Input Parameters

Parameter Type Description
"" String Empty string passed as the input parameter when invoking the contact picker.
callback Function Callback function invoked with the result of the operation.

Callback Response

The callback receives a result object containing the operation status.

Status Description
success A contact was selected successfully.
cancelled The user cancelled contact selection.
Other status values The operation failed. Check errormsg for additional information, if available.

Example

voltmx.contact.findAsync("", function(result) {
    if (result.status === "success") {
        voltmx.print("Contact selected");
    } else if (result.status === "cancelled") {
voltmx.print("User cancelled contact selection");
    } else {
        voltmx.print(
            "Failed to find contact: " + (result.errormsg || "")
        );
    }
});

Notes

  • The native Contact Picker requires user interaction to select a contact.

  • The operation is asynchronous; handle the result in the callback.

  • Review the returned result object to access the selected contact details.

Platform Availability

  • Android