Deprecated Functions

This API allows you to invoke a service asynchronously with the specified parameters.

Note: These APIs are generated by VoltMX Irisfor the code generated using mapping editor. Even though these APIs have been retained as is they have not been published as standard APIs provided by the VoltMX runtime libraries. These APIs will not be available to a developer not using VoltMX Irisin future for development.

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.

			function asyncCallback(status, news) 
			{
			// populate UI
			};

			var news_inputparam = {};
			news_inputparam["serviceID"] = "news";
			news_inputparam["httpheaders"] = {};
			news_inputparam["httpconfig"] = {timeout:5};
			news = appmiddlewareinvokerasync(news_inputparam, asyncCallback);
		

Syntax

voltmx.net.invokeServiceAsync ([url](#url),[inputParamTable](#inputParamTable),[callback](#callback)[,info](#info))

Input Parameters

url [String] - Mandatory

The URL containing the remote location from where the content is to be retrieved.

inputParamTable [Object] - Mandatory

The inputParamTable is the list of parameters that need to be passed to the remote service. The inputParamTable contains the following key-value pairs:

• appID - Unique ID of the application.
• serviceID - Unique ID of the service.
• channel - Indicates the mobile application channel for which the request is been raised. Valid values are “rc” for native clients and “wap” for Mobile Web and SPA clients.

Important:  

• The above fields appID, serviceID, and channel are mandatory only when middleware is used.
• If you use a third-party URL for invokeServiceAsync API, the URL should return only JSON value.

• httpheaders [Object] - The httpheaders is an optional key in the parameter table . Use this key when you want to pass custom headers to the remote service.

For example:

	 httpheaders={authkey:"myauthkey",  
     authtoken:"myauthtoken"}
     

Certain headers like useragent are overridden by the underlying SDK and cannot be set using the httpheaders key.

If the remote service requires basic authentication, you can set the header as follows:

	 Authorization:"Basic" <base64encoding of the username:password>". For example, httpheaders={Authorization:  
     "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="} 
     

Note:  

• Make sure there is a space between Basic and the actual base64 encoded string.
• In SPA and Desktop Web, if you use third-party URLs, then apply xmlHTTPRequest APIs and enable Cross-Origin Resource Sharing (CORS) headers on the target servers (that is, the server to which the service request is made).

If you make a third-party URL call without CORS headers, it results in security exception saying that browser has prevented cross origin request.

The following is an example on how to use this parameter:

 local myhttpheaders={authkey:  
 "myauthkey",authtoken:"myauthtoken"}  
 local inputParamTable={appID:"SampleApp",  
 serviceID:"accountLogin",channel:"rc",  
 httpheaders:myhttpheaders};  
 
 

• httpconfig [Object] - The httpconfig is an optional key in the parameter table . Use this key when to pass custom configurations to set the timeout in seconds for network calls.

For example:

	 httpconfig={timeout:5}
     

Important: On SPA and Desktop Web, if you are using third-party URLs, use the HTTP request method.

To configure the HTTP request method, use “method.” The possible values are:

• Get
• Post (default value)

Note: An invalid value to method leads to undefined behavior.

For example: 

	 httpconfig = { timeout: 5, method: "get"}
     

callback [Function] - Mandatory

The callback function that is called to handle the return values of the asynchronous network call (in case of success) and error messages (in case of failure). The following is the signature:

callback(status, resulttable)

• status - an integer value - indicating the status

  • 100 - network call initiated successfully. The resultset is not available, and it is nil.
  • 200 - network is in progress (when you start receiving the first byte). The resultset is not available, and it is nil.
  • 300 - network call canceled. The resultset is not available and it is nil.
  • 400 - network call is finished (called in success and failure scenarios). Actual state can be queried using opstatus in the resultset.

Note: On Mobile Web, the callback function is always invoked with a status of 400. Other intermediate status codes are not applicable on Mobile Web.

• resulttable - an object with key-value pairs. Follows the same structure (opstatus, errcode, and errmsg along with the actual network returned data).

The resulttable represents the object returned by the service. This object contains three values:

opstatus

errcode

errmsg

If the opstatus is 0, the service call is a success while a non-zero value indicates a failure.

If the opstatus is a non-zero value, an errcode is generated. The following are the error codes:

• 1000- Unknown error while connecting (if the platform cannot differentiate between network errors, the platform reports error code 1000 by default).
• 1011 - Device has no Wi-Fi or mobile connectivity. Try the operation after establishing connectivity.
• 1012 - Request failed.
• 1013 - Middleware returned invalid JSON string.
• 1014 - Request timed out.
• 1015 - Cannot find host.
• 1016 - Cannot connect to host.
• 1200 - SSL - Certificate related error codes.

The error message corresponding to each error code is captured in the errmsg parameter.

Important: The following information is applicable only for iOS and Android platforms.

The resulttable also contains the httpresponse key. The httpresponse contains a value as a table containing responsecode, url, headers, and cookies keys.

 httpresponse:{  
     "headers":{  
         "xxxx":"Basic realm=\\"Authentication required\\"",  
         "Content-Language":"en",  
         "Content-Type":"text.html;charset=utf-8",  
         "Date":"Tue, 29 Jul 2014 10:17:04 GMT",  
         "Server":"Apache-Coyote/1.1",  
         "Content-Length":"951"},  
     "responsecode":401,  
     "url":"http://x.x.x.x",  
     "integrityStatus":"constants.HTTP\_INTEGRITY\_CHECK\_SUCCESSFUL"}.
 

The integrityStatus field can be one of the following values.

• constants.HTTP_INTEGRITY_CHECK_NOT_DONE
• constants.HTTP_INTEGRITY_CHECK_SUCCESSFUL
• constants.HTTP_INTEGRITY_CHECK_FAILED

For more information, see HTTP Integrity Checking.

info [Object] - Optional

A JavaScript object consisting of key value pairs. If the info parameter is specified, it is passed to the callback function as a last parameter. If the info parameter is not specified, the callback function receives the info as null. The info object represents user data where in the application developers will pass it to the async API’s, and the platform returns this info object to the corresponding async callback.This parameter helps developers remember the context when the methods are called in asynchronous fashion.Developers can define any custom keys and values within the info object based on the needs. Custom keys are not predefined keys with values.

Return Values

connHandle

The connHandle represents the handle to the underlying URL connection. The connHandle helps cancel the network call using the cancel API.

null

If the input parameters are invalid.

Implementation Details

To ensure security, all JavaScript functions within an application are executed in a single thread. There is no separate thread for the asynchronous service callback functions. The callback function for the service call executes serially in the thread, only after the execution of other JavaScript functions (queued up earlier).

Any subsequent user actions are queued if they occur during the execution of the callback function. Therefore, parallel execution of multiple asynchronous calls (even the operation of waiting for the response) cannot be guaranteed.

API Usage

Based on the application requirement and logic, a developer should decide whether to invoke a service synchronously or asynchronously.

UI Behavior

There is no noticeable difference in the user interface because the user can perform other actions while the asynchronous network call is in progress.

Rules and Restrictions

Do not use other service calls or functions that use/update the same data structure that is applied by the asynchronous network call. If you invoke more than one asynchronous service call that accesses the same data structure, the behavior of the application is unpredictable. You should handle such validations or error handling mechanisms in the callback function that is executed when an asynchronous service call is made.

Note: You must sanitize the data such as user input or http response before setting them as http header values. If the data is not sanitized it can lead to various types of header manipulation attacks such as an HTTP response splitting attack, cross-site scripting, browser hijacking, cookie manipulation, and cross-user defacement.

Exceptions

1200 - Network Error.

Platform Availability

Available on all platforms.

Example

		function callbackfunction(status, resulttable)
			{
			if(status == 400)
			{
			if(resulttable["opstatus"] == 0)
			{
			alert("opstatus is zero");
			}
			}
			}

			function startup()
			{
			try
			{
			var myhttpheaders={authkey:"myauthkey", authtoken:"myauthtoken"};
			var inputParamTable=
			{
			appID:"SampleApp", 
			serviceID:"accountLogin", 
			channel:"rc", 
			httpheaders:myhttpheaders
			};
			var connHandle = voltmx.net.invokeServiceAsync(
			"http://www.test.voltmx.com", 
			inputParamTable, 
			callbackfunction);
		
			}
			catch(err)
			{
			alert("Error"+err);
			}	
		}

This API allows you to invoke a service synchronously with the specified parameters.

Syntax

voltmx.net.invokeService(url,inputParamTable,isblocking)

Input Parameters

url [String] - Mandatory

The URL containing the remote location from where the content is to be retrieved.

inputParamTable [None.]

It is the list of parameters that need to be passed to the remote service. The parametermap is a table that has the following key-value pairs:

• appID - Unique ID of the application
• serviceID - Unique ID of the service

• httpheaders [None.] - The httpheaders is an Optional key in the parameter table . You can use this key when you want to pass custom headers to the remote service.

  For example,

	httpheaders={authkey:"myauthkey",  
    authtoken="myauthtoken"}
    

Certain headers like User-Agent will be overridden by the underlying SDK and hence cannot be set using this key.

If the remote service requires basic authentication, you can set the header as follows:

	`Authorization="Basic <base64encoding of the username:password>"`. For example, `httpheaders={Authorization=  
    "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}`
    

Note: Make sure there is a space between Basic and the actual base64 encoded string.

The following is an example on how to use this parameter:

local myhttpheaders={authkey=  
"myauthkey",authtoken="myauthtoken"}  
local inputParamTable={appID="SampleApp",  
serviceID="accountLogin",  
httpheaders=myhttpheaders};  

isblocking [Boolean] - Mandatory

Indicates if further actions on the user-interface needs to be blocked or not. If set to true, further clicks or actions on the form are blocked. If set to false, the user can to scroll through the user-interface but cannot perform any actions.

Return Values

resulttable

This table contains three values:

• opstatus
• errcode
• errmsg.

If the opstatus is 0, it indicates that the service call is a success while a non-zero value indicates a failure.

If the opstatus is a non-zero value, it is captured in errcode. The following are the possible error codes:

• 1000- Unknown Error while connecting (If the platform cannot differentiate between the various kinds of network errors, the platform reports this error code by default)
• 1011 - Device has no WIFI or mobile connectivity. Please try the operation after establishing connectivity.
• 1012 - Request Failed
• 1013 - Middleware returned invalid JSON string
• 1014 - Request Timed out
• 1015 - Cannot find host
• 1016 - Cannot connect to host

• 1022 - Service call is canceled. You can customize the behavior of the application if a service call is canceled.

  Note: When you explicitly call form.show, then the iOS device will cancel the service call.

• 1200 - SSL - Certificate related error codes.

The error message corresponding to each error code is captured in the errmsg parameter.

API Usage

Based on the application requirement and logic, the developer should decide whether to invoke a service synchronously or asynchronously. For a synchronous service call, you should use the net.invokeservice API. For an asynchronous service call, you should use the net.invokeserviceasync API.

UI Behavior

When the synchronous service call is in progress, you can scroll through the user-interface but cannot perform any actions until the application receives the response for the synchronous service from the server. A progress indicator (something similar to ) appears on the screen indicating to the user that a service call is in progress.

Note: Currently, the iPhone platform allow you to cancel a synchronous service call while it is in progress. When a service call is canceled, 1022 error code is thrown and you have to handle the logic that needs to be executed for that specific error code.

On iPhone, if the isblocking parameter is set to true, a message similar to the following message appears at the bottom of the screen allowing you to cancel the service call.

If the isblocking parameter is set to false, this message does not appear.

Note: On iPhone platform, the default value of isblocking parameter is true.

Rules and Restrictions

Use synchronous service calls only when you need the service output to be consumed immediately for other actions in the application. In other words, use synchronous service calls when you want the code in the application to be executed sequentially.

Platform Availability

Available on all platforms.

Example

local myhttpheaders={authkey="myauthkey",authtoken="myauthtoken"}
local params={appID="12345",serviceID="test1",httpheaders=myhttpheaders};
local myresulttable=net.invokeservice("http://test.hcl.net",  
params,true);
if (myresulttable.opstatus == 0)
then
// display some other form
else// display error
end;