voltmx.net Namespace

This API cancels only async network calls. Synchronous calls have a platform-specific cancellation mechanism provided by the platform (mechanism may vary from platform to platform).

Syntax

voltmx.net.cancel(  
    connHandle);

Input Parameters

Example

function cancelService() {
    voltmx.net.cancel(connHandle);
}

Return Values

None.

Exceptions

1200 - Network Error.

Remarks

Invalid parameters to this function are ignored.

Platform Availability

Available on all platforms except Server-Side Mobile Web, Windows.

Removes cookies from the client that are associated with the specified domain.

Syntax

voltmx.net.clearCookies(  
    url,  
    cookieName)

Input Parameters

Example

voltmx.net.clearCookies("http://www.google.com");

Return Values

None

Remarks

In an application where service calls are made through Browser Widget or through native service calls, cookies are sent from the servers to maintain the session. These cookies are stored in the cookie store on the client side. Using this API you can remove the cookies of a particular domain obtained through all of HttpRequest, invokeServiceAsync and browser widget.

If you specify the optional parameters url and cookieName, then all the cookies with the specified name related to that URL are removed from your application. The parameter url should be the complete URL. For example, http://www.gooogle.com. If the URL is not valid, then this API will not remove the cookies. An exception is shown of type Volt MX Error with the error code as 1005 and error name/message as “invalid input url”.

If the scheme of the URL is “https” then all the cookies of https as well as http will be removed. If the scheme of the URL is “http” then only the cookies stored for http will be removed. If the cookies are not present in the application cookie store in the provided array of cookieNames, then this API will not perform any action and does not raise an exception.

Platform Availability

Available on iOS, Android, Windows, and SPA platforms.

Limitations

• Android
  • The voltmx.net.clearCookies API does not remove the cookie from the Browser widget’s cookie store; it replaces the cookie value with an empty string.
• SPA
  • You can remove the cookies related to a currently loaded domain in a web page.
  • Cookies with the httpOnly flag cannot be removed. The secured cookies (https) cannot be removed when application is accessed with non-secured protocol.

The FormData object represents an ordered collection of entries with name-value pairs. Call this function to create a FormData object.

Syntax

voltmx.net.FormData();

Example

var httpinputparams1 = new voltmx.net.FormData()

Input Parameters

None.

Return Values

Returns an object of type FormData.

Platform Availability

Android, iOS, Windows, and SPA

Retrieves the currently-active network type.

Syntax

_voltmx.net.getActiveNetworkType(_ _optionsConfig_ _);_

Input Parameters

optionsConfig [JSON Object] - An optional JSON Object that contains the following parameters:

Note: This parameter is only available on the Android platform.

Example

function callbackFunction(network){  
  if(network.status != "FAILED"){  
    alert(JSON.stringify(network));  
  }  
  else{  
    alert("Failed to get network");  
  }  
}  
function checkActiveNetwork() {  
 var options = {  
      "requestWithPermission" : true,  
      "callback" : callbackFunction  
    };  
    return voltmx.net.getActiveNetworkType(options);  
}

Return Values

If the device is offline, it will return null. Otherwise, it will return the appropriate connection type.

For Android, if the value of the requestWithPermission parameter is true, the network information is passed to the callback function, and a null value is returned to the API. If the value of the requestWithPermission parameter is false, the appropriate connection type constant is returned.

For SPA and Desktop Web, it will always return constants.NETWORK_TYPE_ANY.

Remarks

SPA and Desktop Web depend upon the navigator.onLine property to detect if the device is offline or online. The implementation of this property across browsers is uneven. For more information, refer to Mozilla documentation for browser support.

Platform Availability

Available on all platforms.

Retrieves cookies associated with the specified domain.

Syntax

voltmx.net.getCookies(  
    URL, cookieFormat)

Input Parameters

Example

var cookies = voltmx.net.getCookies("http://www.google.com", constants.COOKIES_IN_STRING);  
for (index = 0; index < cookies.length; index++) {  
    cookie = cookies[index];  
    voltmx.print("Cookie is: " + cookie);   
}

Return Values

Returns an array of cookies. For details, see Remarks below.

//For example  
SSID=Ap4P….GTEq; Domain=foo.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT; Secure; HttpOnly

Remarks

In an application where service calls are made through Browser Widget or through native service calls, cookies are sent from the servers to maintain the session. These cookies are stored in cookie store on the client side. The voltmx.net.getCookies API enables access to the cookies for a particular domain. The URL is given as an input parameter to voltmx.net.getCookies API, then all cookies related to that domain are returned.

In the current application context, you can also access cookies for a particular domain stored in cookie store on the client side or device.

The voltmx.net.getCookies function returns all the cookies stored in local cookie store on the client side or device for that particular domain. The returned cookies can vary based on the domain (partial or full domain) and as well as the path.

The URL is passed as input and must be a fully formed, valid URL like http://www.google.com.

If the URL is invalid or not formed properly, Null is returned.

Each cookie that this function returns is a string that follows the format key=value. Each cookie string can also contain additional information following the Standard HTTP Cookie Format, such as Domain, Path, Expires, Secure, and HttpOnly. This function returns Null if there are no cookies for the domain.

If the scheme of the URL is https, then this function returns all the cookies of https cookies as well as the http cookies. If the scheme of the URL is http, then only the cookies stored for http are returned.

Platform Availability

Android, iOS, Windows, and SPA

Limitations

• In Windows, the cookies stored in the Browser Widget cookie store are returned. Cookies stored through native service calls are not returned.
• In SPA, the cookies related to a currently loaded domain in a web page are accessible.
• In SPA, cookies with the httpOnly flag cannot be accessed.

Determines whether the device has the specified capability.

Syntax

voltmx.net.hasCapability(capability);

Input Parameters

capability

A constant that specifies the availability of a capability on the device. You can specify any of the following.

Example

voltmx.net.hasCapability(constants.NET_CAPABILITY_TEMPORARILY_NOT_METERED)

Return Values

Boolean

Exceptions

None

Platform Availability

Available on Android platform.

Creates an HttpRequest object.

Syntax

voltmx.net.HttpRequest(requestOptions)

Example

var httpRequestNew = voltmx.net.HttpRequest({
       "timeoutIntervalForRequest": 60,
       "timeoutIntervalForResource": 600
   }
);

Input Parameters

requestOptions - An optional argument that can have the following parameters.

Note: The requestOptions parameter is only available on the Android and iOS platforms.

Return Values

None

Remarks

The HttpRequest Object supports an HTTP or HTTPS request to any resource on the network and fetches the response.

Note: SNI (Server Name Indication ) is supported from Android 4.2 onwards. That is, from API level >=17. From Android 4.0 to 4.2 versions, the support of SNI depends on device capability. That is 14<= API Level <17.

Platform Availability

Available on all platforms.

This API enables you to check whether a network is available for data transport on a device.

Syntax

voltmx.net.isNetworkAvailable(  
    networkType, optionsConfig)

Input Parameters

Network Constants

Example

function checkIfNetworkIsAvailable() {  
  
var options = {  
  "requestWithPermission" : true  
}  
return voltmx.net.isNetworkAvailable(constants.NETWORK_TYPE_ANY, options);  
}

Return Values

Boolean

Returns true if the specified data network is available, or false if not.

Platform Availability

Available on all platforms.

Sets a client certificate to be used for HTTPS client authentication.

Syntax

voltmx.net.loadClientCertificate(  
    certParamsTable)

Input Parameters

certParamsTable

A list of following key-value pairs required to load client certificate for client authentication in a mutually authenticated HTTPS connection.

Example

function loadCert() {  
  try {  
  var certFileName = voltmx.io.FileSystem.getCacheDirectoryPath() + "/" + clientCertFileName;  
  var certFile = new voltmx.io.File(certFileName);  
  var certStream = certFile.read()  
  
  var certParamTable = {  
  cert: certStream,  
  pass: "password"  
  };  
  var res = voltmx.net.loadClientCertificate(certParamTable);  
  voltmx.print("loadClientCertificate status = " + res)  
  } catch (e) {  
  alert(e);  
  }  
 }

Return Values

This API returns a Boolean value whether the client certificate is loaded successfully or not.

Remarks

The following functions use the client authentication feature:

voltmx.net.invokeServiceAsync

voltmx.net.send

If loading the client certificate succeeds, the previously-loaded certificate is replaced with new one.

If loading the client certificate fails, the previously-loaded certificate is retained as is.

Any certificate loaded using this function is automatically unloaded as soon as the application exits.

Note: When you use the voltmx.net.HttpRequest API in sync mode, both server and client pinning do not work in the iOS platform.

Exceptions

If the mandatory parameters are missing, following error codes occur.

100 - invalid type of parameters

101 - invalid number of arguments

Platform Availability

• iOS
• Android

Invokes a Volt MX Foundry service asynchronously.

Syntax

voltmx.net.mfintegrationsecureinvokerasync(  
    inputParams,  
    serviceName ,  
    operationName,  
    callbackFunction)

Input Parameters

Example

function callbackFunction(status, response) {
    //application specific code goes here.
}

var serviceName = "ServiceTwo";
var operationName = "HealthOperation";

// inputParams here is just a sample. Your Parameters will look different.
// The Parameters are dependent on the input information that your 
// Volt MX Foundry service's operation requires.
// <place-holder> is a placeholder for the atual values of your parameters.
var inputParams = {
    "q": "<place-holder>",
    "httpheaders": {
        "api-key": "<place-holder>"
    }
};
mfintegrationsecureinvokerasync(inputParams, serviceName, operationName, callbackFunction);
				

Return Values

None.

Remarks

Use this service to call a Volt MX Foundry service from your app. When the service sends a response to your app, the response is processed by the callback function that your app passes through the callbackFunction parameter of this function.

The format of the inputParams object parameter is not specified here because its format depends entirely on the information that the Volt MX Foundry service’s operation requires for input.

The function passed through the callbackFunction parameter must match the following Syntax.

callbackFunction(status,response);

The callback function takes two parameters. The first, called status, is an integer that indicates the status of the response from the service’s operation The value contained in the status parameter depends on the service itself.

The second parameter to the callback function is called response. It is a JavaScript object that contains the response from the service’s operation. The format of the object and the data it contains is dictated by the service’s operation.

Clears the default cache of an application by removing all responses received from URLs.

Syntax

voltmx.net.removeAllCachedResponses()

Example

voltmx.net.removeAllCachedResponses();

Input Parameters

None.

Return Values

None.

Platform Availability

iOS

Removes already loaded client certificate.

Syntax

voltmx.net.removeClientCertificate()

Example

function removeCert() {  
    voltmx.net.removeClientCertificate();  
}

Input Parameters

None.

Return Values

None.

Exceptions

None.

Platform Availability

• Android

Disables intregity checks for HTTP calls between the client and the server.

Syntax

voltmx.net.removeIntegrityCheck()

Example

voltmx.net.removeIntegrityCheck();

Input Parameters

None.

Return Values

None.

Determines if the device has a 5G network connection to the app.

Syntax

voltmx.net.set5GNetworkListener(callback);

Input Parameters

callback - The callback function that must be executed after the execution of the API call is complete.

Example

callbackFunction : function(networktype){  
  if(networktype = constants.OVERRIDE_NETWORK_TYPE_LTE_CA)
    alert("LTE_CA");  
}  
voltmx.net.set5GNetworkListener(callbackFunction);

Return Values

Constant

Exceptions

None

Platform Availability

Available on Android platform.

Note: You can unregister from the 5G Network Listener by invoking the voltmx.net.unregister5GNetworkListener() API.

Adds cookies in the main app cookie storage. If a cookie with the same name, domain, and path already exists in storage, this API replaces the specified cookie in the cookie storage.

Syntax

voltmx.net.setCookies(url,cookiesList)

Input Parameters

Example

function setCookiesFunc() {
    var lisOfCookies = [{
        "Name": "appName",
        "Value": "App01",
        "Domain": "app.example.com",
        "Path": "/"
    }]
    voltmx.net.setCookies("https://www.example.com", listOfCookies)
}

Return Values

None

Remarks

To successfully create a cookie, you must provide values for (at least) the Path, Name, Value, and the Domain keys. All the other valid keys must start with capital letters.

The parameter url must be the complete URL. For example, http://www.gooogle.com.

Platform Availability

Available on iOS platform.

Enables the addition of checksums to HTTP calls for HTTP integrity checking.

Syntax

voltmx.net.setIntegrityCheck(  
    propertiesTable)

Input Parameters

propertiesTable

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

Example

var propertiesTable {
    algo: “SHA256”,
    salt: “secret_123”,
    headerName: “X - Checksum”,
    validateResp: true,
    hostNamesList: [“mail.voltmx.com”, “cloud.voltmx.com”]

};

voltmx.net.setIntegrityCheck(propertiesTable);

Return Values

None

Exceptions

This function throws the following exceptions.

Remarks

Use this function to cause the Volt MX IrisAPI Framework to use checksums to validate HTTP messages passing between the client app and the servers.

The beginning and ending whitespace is automatically trimmed on all string arguments in the propertiesTable parameter .

If the validateResp argument in the propertiesTable parameter is set to true, your app uses an HttpRequest object to receive the response. When it does, it uses the integrityStatus property of the HttpRequest object to check whether the integrity check is successful or not.

If the optional hostNameList argument is omitted from the propertiesTable parameter, then the integrity checking header is added to all outgoing HTTP and HTTPS calls. However, if the host names are specified in the hostNameList argument, then the integrity checking header is only added to calls to the specified hosts. Also, only basic validation is performed on the named hosts’ parameters if the hostname strings are limited to the set [a-z, A-Z, 0-9, -]. In addition, the wildcard character, which is the asterisk (*), can only be used as a prefix. For example, *.voltmx.com is valid, but voltmx.* is not. Finally, you must ensure that all of the host names you pass are valid. The setIntegrityCheck function does not validate the format of the host names for you. All host names must follow the standard delineated in the Wikipedia Hostname topic.

Platform Availability

• Android
• iOS
• Windows

This function allows the developer to register for network status changes.

Syntax

voltmx.net.setNetworkCallbacks(  
    callbackconfig)

Input Parameters

Example

var config = {};
config.statusChange = function(isOnLine) {
    if (isOnLine) {
        alert("Device is online");
    } else {
        alert("Device is offline");
    }
};
voltmx.net.setNetworkCallbacks(config);

Return Values

None

Remarks

This function allows the developer to register for network status changes. You can then change the user experience according to the network availability.

Platform Availability

Available on all platforms except Windows and Mobile Web.

Unregister from the 5G Network Listener.

Syntax

voltmx.net.unregister5GNetworkListener();

Input Parameters

None

Example

voltmx.net.unregister5GNetworkListener();

Return Values

None

Exceptions

None

Platform Availability

Available on Android platform.

Converts a URL string from application/x-www-form-urlencoded format in the UTF-8 encoding.

Syntax

voltmx.net.urlDecode(  
    queryParams,  
    exemptionString)

Input Parameters

Example with exemptionString parameter

var result = voltmx.net.urlDecode(“hello*_%40+world”); 
voltmx.print(result);  
  
//iOS output  
  hello*_%40+worl%64  
  
//Android output  
  hello*_%40+world

Example without exemptionString parameter

var result = voltmx.net.urlDecode(“hello*_%40+world”); 
voltmx.print(result);
					  
//Output for all platforms  
  “hello*_@ world”		

Return Values

Returns a string containing the decoded URL.

Platform Availability

• Android
• iOS
• Windows

Converts a URL string into application/x-www-form-urlencoded format using the UTF-8 encoding.

Syntax

voltmx.net.urlEncode(  
    queryParams  
    exemptionString)

Input Parameters

Example with exemptionString parameter

var exemptionString =  "helloworl-*_.";
var result = voltmx.net.urlEncode(“hello*_@ world”, exemptionString); 
voltmx.print(result);  
  
//iOS output  
  hello*_%40+worl%64  
  
//Android output  
  hello*_%40+world

Example without exemptionString parameter

var result = voltmx.net.urlEncode(“hello*_@ world”); 
voltmx.print(result);
					  
//Output for all platforms  
  hello*_%40+world		

Return Values

Returns the encoded string.

Remarks

The string is encoded based on the following rules.

• The following characters remain the unchanged.
  • a-z
  • A-Z
  • 0-9
  • Period (.), hyphen (-), asterisk (*), and underscore (_)
• The space character “ “ is converted to a plus symbol (+).
• Other characters are unsafe and are first converted to one or more bytes using an encoding scheme. Each byte is represented as 3-character string, %xy, where xy is the two-digit hexadecimal representation of the byte.

Platform Availability

• Android
• iOS
• Windows