voltmx.phone Namespace

Adds a new event to the device calendar.

Syntax

voltmx.phone.addCalendarEvent(  
    eventDetails);

Input Parameters

eventDetails

A JavaScript object that contains the following key-value pairs.

repeatConfig - Optional

A dictionary that indicates the repeat frequency and endRecurrence values for the event. The dictionary contains two values: repeat and endRecurrence.

repeat

A constant that indicates the repeat frequency. The values are as follows:

• CALENDAREVENT_REPEAT_NONE

• CALENDAREVENT_REPEAT_DAILY

• CALENDAREVENT_REPEAT_WEEKLY

• CALENDAREVENT_REPEAT_MONTHLY

• CALENDAREVENT_REPEAT_YEARLY

endRecurrence [Optional]

A string that stores the recurrence end date and time for the event. The format for the end date and time is “dd/mm/yyyy hh:mm:ss”. This date must be greater than the start date and time. For native iOS, if you do not specify the endRecurrence value, the events will repeat for 2 years.

Interval [Optoional]

This allows you to set the interval to repeat the event. It must have a positive integer as value. The default value is 1.

For example, to create a quarterly event, configure ‘repeat’ as constants.CALENDAREVENT_REPEAT_MONTHLY and ‘interval’ as ‘3’. The repeat event will be created in every 3 months(quarterly).

To create a bi-weekly event, configure ‘repeat’ as constants.CALENDAREVENT_REPEAT_WEEKLY and ‘interval’ as ‘2’. The repeat event will be created in every 2 weeks (biweekly).

The following example shows how to add quarterly repeat event.

Example

//Sample code to add the Input Parameter **Interval** in the add calendar event to the device   
addCalendarEvent argument  
 var eventobj = {  
summary: "Event started",  
start: this.startTime,  
finish: this.finishTime,  
alarm: 40,  
access: "public",  
“repeatConfig“:{  
“repeat“:contants.CALENDAREVENT_REPEAT_MONTHLY,  
“interval“: 3,  
“endRecurrence”:endDate  
}  
};  
voltmx.phone.addCalendarEvent(eventobj);

function addCalendarEvent() {
    try {
        alert("calendar event is about to start");
        var evtobj = {
            summary: "Event started",
            start: "15/04/2012 11:23:45",
            finish: "16/04/2012 12:59:45",
            alarm: 40,
            note: "Event will end at 12.59 PM",
            access: "public",
            repeatConfig: {
                repeat: constants.CALENDAREVENT\_REPEAT\_MONTHLY,
                endRecurrence: ”21/12/2013 13:00:00”
            }
        }
        voltmx.phone.addCalendarEvent(evtobj);
        //Adds an event to the device calendar
    } catch (PhoneError) {
        alert("error in addCalendarEvent:: " + PhoneError);
    }

}

// To add the calendar event to the device using 'voltmx.phone.addCalendarEvent' APICalendarAddEvent: function(eventObj) {
    try {

        var today = new Date();
        var dd = today.getDate();
        var mm = today.getMonth() + 1;
        var yyyy = today.getFullYear();
        var h = today.getHours();
        var m = today.getMinutes();
        var s = today.getSeconds();
        if (dd & lt; 10) {
            dd = '0' + dd
        }
        if (mm & lt; 10) {
            mm = '0' + mm
        }
        var date = dd + '/
' + mm + ' / ' + yyyy;
        var stime = h + ":" + (parseInt(m) + 2).toString() + ":" + s;
        this.startTime = date + " " + stime;
        var ftime = (parseInt(h) + 1).toString() + ":" + m + ":" + s;
        this.finishTime = date + " " + ftime;
        if (eventObj\["text"\] == "Add calendar event") {
            var evtobj = {
                summary: "Event started",
                start: this.startTime,
                finish: this.finishTime,
                alarm: 40,
                access: "public"
            };
            voltmx.phone.addCalendarEvent(evtobj);
            alert("Calendar event is added with start time = " + this.startTime + ". Please open device calendar to observe this.");
        } else {
            var evtobj = {
                summary: "Event started",
                start: this.startTime,
                finish: this.finishTime,
                alarm: 40,
                access: "confidential"
            };
            voltmx.phone.addCalendarEvent(evtobj);
            alert("Calendar event is added in confidential mode with start time = " + this.startTime + ".");

        }
    } catch (PhoneError) {
        alert("error in addCalendarEvent:: " + PhoneError);
    }
}  

Return Values

None

Exceptions

This function throws the following phone exceptions.

This function also throws the following general exceptions.

Remarks

You can view a video on using the Calendar here.

Events cannot be added in the past.

When your app calls this function on Android, it must have both the READ_CALENDAR and WRITE_CALENDAR permissions. Due to Android limitations, when your app sets an alarm with this function the number of seconds are rounded to the nearest minute. Events are added to the local calendar with the calendar name as the application name. They cannot be synched to email accounts.

The time zone of events that your app adds is the same as the device’s current time zone.

Platform Availability

• iOS
• Android version 4.0 and later
• Windows

This API stops the ongoing vibration pattern on a device. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax

voltmx.phone.cancelVibration()

Input Parameters

None.

Example

voltmx.phone.cancelVibration();

Return Values

None.

Limitations/Requirements

• Windows

  • The device must have vibration hardware.

  • Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.

  • API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Platform Availability

• Android
• Windows

When invoked, this API clears the broadcast receiver and the existing listeners that are registered to retrieve the one-time password (OTP) from the SMS message received.

Syntax

voltmx.phone.clearSMSListeners()

Input Parameters

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example

clearAll: function() {
try {
voltmx.phone.clearSMSListeners();
} catch (err) {
alert("Error:: " + err);
}
}

Return Values

None.

Exceptions

• 101 - Invalid type of arguments to the voltmx.phone.clearSMSListeners API

Platform Availability

• Android

App hash key is a hash string composed of the app’s package name and the app’s public key certificate. When invoked, this API generates a hash key that must be included in the SMS message sent from the server to the user’s device.

For an app to receive the message callback, the hash key has to be correct.

Note: This API must be invoked only if type of SMS listener triggered is voltmx.phone.SMS_WITHOUT_USER_CONSENT

Syntax

voltmx.phone.generateAppHashKey()

Input Parameters

None.

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example

generateAppHashKey: function() {
    var key = voltmx.phone.generateAppHashKey();
    voltmx.print("AppHashkey: " + key);
}

Return Values

Platform Availability

• Android

Enables your app to call the specified telephone number.

You can use this API to make calls to other numbers without leaving the application.

Syntax

voltmx.phone.dial(  
    number);

Input Parameters

Example

dial: function() {
    var number = this.view.tbxDial.text;
    voltmx.phone.dial(number);
},

Return Values

None

Exceptions

2101 - Insufficient Permissions

Remarks

When you make a call to the specified number using this API, the underlying OS is used to make the call. The call charges as imposed by the service provider are applicable.

On the iPhone simulator, this function is a dummy call. You need to test this function on an actual iPhone device.

Platform Availability

Not supported on Windows, iPad, Android Tablets, Desktop Web, and Mobile Web platforms. You can use the phone widget to achieve the same functionality on Mobile Web.

This function finds an event in the device’s calendar.

Syntax

voltmx.phone.findCalendarEvents(  
    evtobj);

Input Parameters

Example

var evtobj = {
    type: "starting",
    start: this.startTime,
    finish: this.finishTime
};
var events = voltmx.phone.findCalendarEvents(evtobj);

Return Values

If no matching event is found, this function returns null. If matching events are found, this function returns an array of JavaScript objects containing the matching events. Each JavaScript object contains the following key-value pairs.

Exceptions

This function throws the following phone exceptions.

This function also throws the following general exceptions.

Remarks

The search criteria in the type key in the evtobj parameter can be any of the following values.

READ_CALENDAR permission is needed to use this function.

This function is supported on Android 4.0 version and above (that is, Android API 14 and later). Invocation on Android version less than 4.0 ( that is, an Android API level earlier than 14) is ignored.

This function searches only those events that are added by the application.

Platform Availability

• iOS
• Android 4.0 or later
• Windows

This API returns an array of constants that indicates possible actions for removing a particular event depending on the native support on the device. One of the values that this API returns must be passed as removeOption for voltmx.phone.removeCalendarEvent API.

Syntax

voltmx.phone.getRemoveEventOptions([eventHandle](#eventHandle1))

Input Parameters

Example

var removeOptions = voltmx.phone.getRemoveEventOptions(eventHandle);

Return Values

An array with possible constant values depending on native support in devices. The possible constants that will be returned as part of the array are as follows:

Note: Depending on the OS configuration of certain Android devices, any of these two values may not be applicable. So before passing any of these two values in the API, you must verify if the Android device supports the required value.

Platform Availability

• iOS
• Android
• Windows

This API returns whether vibrator is supported on a device. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax

voltmx.phone.hasVibratorSupport()

Example

hasVibratorSupport: function() {
    if (voltmx.phone.hasVibratorSupport() === true) {
        alert("The device contains a Vibration motor");
    }
},

Input Parameters

None.

Return Values

Boolean is the return value.

Limitations/Requirements

• Windows

  • The device must have vibration hardware.

  • Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.

  • API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Platform Availability

• Android
• Windows

This API allows the application to launch the native email client with predefined email addresses, subject, body, and attachments.

Syntax

voltmx.phone.openEmail(torecipients,ccrecipients, bccrecipients, subject, messagebody, ismessagebodyhtml, attachments, viewMode, filterEmailAppsOnly)

Input Parameters

<queries>
<intent>
<action android:name="android.intent.action.SENDTO" />
<data android:scheme="mailto"/>
</intent>
</queries>

Example

emailSend: function() {
    voltmx.phone.openEmail(["kitchensinkapp@voltmx.com"], [""], [""], "Feedback on KitchenSink Application 1.1", "", false, []);
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

• 2100 - Unable to send the Message
• 2101 - Insufficient Permissions
• 2102 - Cannot open mail, mail not configured
• 2103 - Cannot open media gallery

Platform Availability

Available on all platforms except Server Side Mobile Web, SPA, and Desktop Web.

For these platforms you can launch the native email client by using Richtext widget with an href tag similar to the one shown below:

Email Me

This API allows you to open the picture gallery of the mobile device and pick an existing picture.

You can use this API to use any of the multimedia resources (image files, audio files, or video files) available in the device media gallery within your application.

For iPad, openMediaGallery will show the Photos/Videos in the native popover. The popover can be anchored to a widget. The widget to which the popup should be anchored will be provided as a third parameter to openMediaGallery API.

You can view a video on using iPad Popover here.

Syntax

voltmx.phone.openMediaGallery([onselectioncallback](#onselectioncallback), [querycontext,](#querycontext) [PSP](#PSP))

Input Parameters

Example

openMediaGalleryForEmail: function() {
    voltmx.phone.openMediaGallery(this.openMediaGallaeryCallBck, {
        mimetype: "image/*"
    });
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

• 2100 - Unable to send the Message
• 2101 - Insufficient Permissions
• 2102 - Cannot open mail, mail not configured
• 2103 - Cannot open media gallery

Platform Availability

Supported on all platforms except Mobile Web, SPA, and Desktop Web.

This API provides various haptic feedback to users, and is available from V9 SP2 onwards.

Syntax

voltmx.phone.performHapticFeedback(hapticFeedbackValue)

Input Parameters

hapticFeedbackValue [constant] – Mandatory

Indicates the type of haptic feedback. Its possible values are as follows:

Example

hapticFeedback: function(){
  voltmx.phone.performHapticFeedback(5);
}

Return Values

None.

Remarks

• iOS
  • The Haptic Feedback feature is available on iPhone 7 devices and later. These devices have Taptic Engine hardware and users can enable/disable Haptics from Device Settings-> Sounds & Haptics-> System Haptics.
• Android
  • Users can enable the Vibrate on touch feature from Settings-> Sound & notification-> Other sounds.

Platform Availability

• iOS

This API either deletes a single event or a series of repeat events starting from the date specified in the eventHandle from the device calendar, depending on the provided removeOption parameter. While deleting a series of recurring events, the API deletes all subsequent events beginning from the date specified in the eventHandle; however, the API does not delete any repeat event that is before the specified date.

Note: To delete an event, you must first search for the event by using the findCalendarEvents API and delete the event.

Syntax

voltmx.phone.removeCalendarEvent([eventHandle](#eventHandle), [removeOption](#removeOption))

Input Parameters

Example

//To remove the calendar event from the device using 'voltmx.phone.removeCalendarEvent' API

CalendarRemoveEvent: function() {
    if (this.startTime === "undefined" || this.startTime === undefined) {
        this.view.lblPhone.text = "Please create the calendar event.";
        return;
    }
    var evtobj = {
        type: "starting",
        start: this.startTime,
        finish: this.finishTime
    };
    var events = voltmx.phone.findCalendarEvents(evtobj);

    voltmx.phone.removeCalendarEvent(events[0]);
    alert("Calendar event is removed. Please open device calendar to observe this");
}

voltmx.phone.removeCalendarEvent(events\[1\],constants.CALENDAREVENT\_REMOVE\_THIS);  
voltmx.phone.removeCalendarEvent(events\[1\],constants.CALENDAREVENT\_REMOVE\_THIS\_AND\_FUTURE);  
voltmx.phone.removeCalendarEvent(events\[1\]); //If it is non-recurring, the current event is deleted; however, if it is a recurring event, the event as well as future events will be deleted.

Return Values

None.

Exceptions

PhoneError

The following error codes are defined for Phone APIs

• 2100 - Unable to send the Message
• 2101 - Insufficient Permissions
• 2102 - Cannot open mail, mail not configured
• 2103 - Cannot open media gallery

Error

• 100 – invalid type of parameters
• 101 – invalid number of arguments
• 102 – invalid input – thrown when the input is invalid based on the context.
• 103 – invalid operation – thrown when the operation is invalid based on the context.
• 104 – not supported error – thrown when the method is not supported at all.
• 105 – index out of range.
• 106 – unknown error.

Platform Availability

• iOS
• Android
• Windows

Remarks

• READ_CALENDAR and WRITE_CALENDAR permissions are needed for this API.
• This API is supported for Android 4.0 version and above (that is, Android API level later to 13). Invocation on Android version less than 4.0 ( that is, Android API level earlier to 14) will be ignored.
• If this API removes last calendar event added to local calendar, then the local calendar account will be deleted.

When invoked, this API reads an SMS message received from the server. The API then retrieves the one-time password (OTP) from the message if it matches with the config provided.

Syntax

voltmx.phone.retrieveSMS(callback, SMSConfig);

Input Parameters

SMSConfig [Object] - Optional

SMSConfig supports the following key-value pairs:

callback [Function] - Mandatory

The callback executed to communicate the SMS Listener Registration status and response of API. The syntax of the callback function is:

callback(callbackObject)

The callbackObject contains SMS and status key value pairs.

SMS key: SMS object, the value of the SMS key is populated only when code is equal to voltmx.phone.SMS_RETRIEVED_SUCCESSFULLY. In case of any error, the SMS object is null.

The SMS object contains the following key-value pairs:

Note: The OTP value returned can be null/empty if the message doesn’t contain any OTP matching the SMSConfig.

status key: Value of the status key contains the following key-value pairs:

The code key can have any of the following values. A code value is populated when the scenario in the corresponding description occurs.

The following codes specify if the framework is successful in starting the SMS listener.

The following codes are applicable only after voltmx.phone.SMS_LISTENER_REGISTRATION_SUCCESS is received.

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example

retrieveOTPFromSMS: function() {


    SMSConfig = {}
    SMSConfig.OTPSizeLimit = 4;
    SMSConfig.OTPType = voltmx.phone.SMS_NUMERIC_OTP;
    SMSConfig.SMSListenerType = voltmx.phone.SMS_WITH_USER_CONSENT;
    SMSConfig.SMSSenderDetails = null;
    try {
        voltmx.phone.retrieveSMS(callback, SMSConfig);
    } catch (err) {
        voltmx.print("ERROR:" + err);
    }


    function callback(callbackObj) {
        statusCode = callbackObj.status.code;

        voltmx.print("STATUS_CODE::" + statusCode);

        if (statusCode == voltmx.phone.SMS_LISTENER_REGISTRATION_SUCCESS) {
            //ADD CODE TO INDICATE SERVER TO SEND OTP
        }

        if (statusCode == voltmx.phone.SMS_RETRIEVED_SUCCESSFULLY) {
            voltmx.print("message:" + callbackObj.SMS.message)
            voltmx.print("otp:" + callbackObj.SMS.OTP)
            alert(callbackObj.SMS.OTP)
        }

    }

Return Values

None

Limitations

You must start an SMS retriever only after the previous registered retriever responds with a success or failure response. However, if you register a second SMS retriever before the first SMS retriever provides a response, the possible limitations are as follows:

• When two SMS retrievals without a user’s consent run simultaneously, the SMS callbacks are triggered in the same sequence in which they are registered. This sequence might not be same as the sequence in which the user has sent the requests to the server. As a result, a mismatch in the provided OTP config might occur.
• When two SMS retrievals with a user’s consent provide two unique sender details for two parallel SMS retrieval registrations, the SMS callbacks are triggered in the same sequence in which they are registered. The SMS details received at the native level does not contain the senders information. Consequently, a mismatch between the senders might occur.

Exceptions

Error Codes:

• 100 - Invalid number of arguments to API voltmx.phone.retrieveSMS()

• 101 - Invalid type of arguments to API voltmx.phone.retrieveSMS()

Platform Availability

Android

This API provides access to the Messaging service of the underlying platform. You can send a text message to a specified number. This API accesses the messaging application of the underlying platform and uses that application to send text message to the specified number.

Important: You can send only text messages and multimedia messages are not supported.

Note: When you send messages using this API, the charges as imposed by the Service Provider are applicable. On iPhone this API opens the Messages application with a prepopulated text and number.

You can use this API to send messages to other numbers without leaving the application.

Syntax

voltmx.phone.sendSMS([phonenumber](#phonenumber), [text](#text))

Input Parameters

Example

sendSMS: function() {
    if (voltmx.os.deviceInfo().model == "iPhone Simulator") {
        alert("Works only on device");
    } else {
        var phoneNo = "+91 40 12345678"; // This is a dummy number
        var text = "Hi Volt MX developer";
        voltmx.phone.sendSMS(phoneNo, text);
    }
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

• 2100 - Unable to send the Message.
• 2101 - Insufficient Permissions.

Remarks

When you send messages using this API, the messaging application of the underlying platform is used to send the message with the number and text you specified i.e., the phone number and the message are pre-populated in the messaging application.

Platform Availability

Available on all platforms except Desktop Web,SPA, Mobile Web, Android Tablets, iPad.

Note: This API allows you to send only text messages. It does not support multimedia messages.

This API starts the vibration feature on a device, provided that device supports vibration. If the device does not support vibration, this API has no effect. If a vibration pattern is already in progress when this API is called, the previous pattern is halted and the new one begins. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax

voltmx.phone.startVibration (vibrationConfig, repeat)

Input Parameters

Example

//Device will vibrate for 100 milliseconds.
  
startVibration: function()
  {
    if(voltmx.phone.hasVibratorSupport()===true)
      {
        var vibrationConfig=[{
    "delay": 0,
    "duration": 100,
    "amplitude": 250
}];
        voltmx.phone.startVibration(vibrationConfig, true);
      }
    else{
        alert("The device does not support vibration");  
    }
  }

Return Values

None.

Behavior, Requirements, and Limitations

• iOS

  • The startVibration API generates only a single vibration effect.
  • iOS does not support config parameters, such as amplitude and duration, for startVibration API.
  • The startVibration API accepts arguments on iOS devices, but it ignores them. The API does not throw any error/exception.

• Windows

  • The device must have vibration hardware.

  • Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.

  • API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Remarks

• You can call this API with or without arguments for Android and Windows. If the arguments are not specified, the device vibrates for 100 milliseconds to align with the behavior for iOS.

Platform Availability

• Android
• iOS
• Windows