HttpRequest Object

The HttpRequest object is used in conjunction with functions in the voltmx.net namespace to send requests to any resource on the network and fetch the response. The HttpRequest object provides the following API elements.

Uploading a File

The HttpRequest API enables you to upload any file to a remote server through the POST method by passing raw bytes of the file. The voltmx.io.FileSystem.getFile API helps you get the raw bytes of the file you want to upload.

Note: Before uploading a file, you must select the Enable File Upload check box from the Application Properties > Native > Android tab. For more information, refer Native App Properties for Android.

To upload a file, set the Content-Type parameter as "multipart/formdata" header request. For example:

setRequestHeader("Content-type”, "multipart/formdata");

You can upload the file content in two ways:

Uploading a file by passing the voltmx.types.RawBytes to the send method.

send( voltmx.types.RawBytes)

Uploading a file by passing the key-value pair to the append method of the FormData Object. In the key-value pair, set file name as a key and the voltmx.types.RawBytes object as a value.

Note: When you send raw bytes of the file for upload, the platforms set the Content-Type parameter as "multipart/formdata" by default.

Example for uploading a file

var path = voltmx.io.FileSystem.getDataDirectoryPath() + "/SampleImage.png"
var f1 = voltmx.io.FileSystem.getFile(path);  
var httpclient = new voltmx.net.HttpRequest();  
httpclient.open(constants.HTTP_METHOD_POST, “http://www.xyz.com” );  
httpclient.setRequestHeader("Content-type”,"multipart/formdata");  
var frmData= new voltmx.net.FormData();  
frmData.append(f1.name, f1.read());  
// sending rawbytes along with file name.  
httpclient.send(frmData);  
OR  
// Directly sending rawbytes.  
httpclient.send(f1.read());

Downloading a File

The HttpRequest API enables you to download any file from a remote server through the GET method. Using the open method, you can initiate the HTTP request by specifying the URL from where you want to download the file. The response will be received in the form of raw bytes (voltmx.types.RawBytes). You can write the received raw bytes to a file using the voltmx.io.FileSystem and the voltmx.io.File APIs.

Example for downloading a file

var httpclient = new voltmx.net.HttpRequest();  
httpclient.open(constants.HTTP_METHOD_GET, “http://www.xyz.com/myFile.png”, false);  
httpclient.send();  
var rb = httpclient.response;  
var myfile = new voltmx.io.File(voltmx.io.FileSystem.getDataDirectoryPath()+"/SampleImage.jpg");  
myfile.write(rb, true);  

// Use the following code snippet to download a file with an asynchronous network call.
function downloadImageAsynchronously()
{   
 httpclient = new voltmx.net.HttpRequest();   
 httpclient.open(constants.HTTP_METHOD_GET, "http://www.xyz.com/myFile.png");   
 httpclient.onReadyStateChange = downloadCallback;   
 httpclient.send();   
}
function downloadCallback()  
{
try   
 {
 if(httpclient.readyState == 4)  
 {
 var responseContent = httpclient.response;
 var myfile = new voltmx.io.File(voltmx.io.FileSystem.getDataDirectoryPath+"/SampleImage.jpg");
 myfile.write(responseContent, true);
 }  
 }
catch(err)
 {   
 alert("exception is :: " + err.getMessage());   
 }  
}

Sending a JSON Object and String data as a Request

The HttpRequest API enables you to send a JSON string or JSON object using the POST method. Using the open method, you can initiate the HTTP request with the URL. With the send method of the HttpRequest API, you can directly send the JSON string.

Example for sending a JSON data as a request

var httpclient = new voltmx.net.HttpRequest();  
httpclient.open(constants.HTTP_METHOD_POST, “http://www.xyz.com/login” );  
httpclient.setRequestHeader("Content-Type", "application/json");  
var postdata = {  
"userId": "test"  
"password": "test123"  
};

Use one of the following:

//Directly sending JSON object  
httpclient.send(postdata);

//Converting JSON object to JSON string and sending  
var jsonStr1 = JSON.stringify(postdata);   
httpclient.send(jsonStr1);

//Sending JSON string  
var jsonStr2= "{\\"userId\\":\\"test\\",\\"password\\":\\"test123\\"}";  
httpclient.send(jsonStr2);

Platform Availability

The HttpRequest API is supported in all platforms except Mobile Web.

Error Codes

100 - Invalid parameter type. The error occurs when you pass other types of data.

101 - Invalid number of arguments. The error occurs when you pass fewer arguments than expected.

Limitations

Setting the Content-Type as non-relevant data results in unexpected behavior. For example, you should not set the "application/x-www-form-urlencoded" as Content-Type when sending the file rawbytes.
When uploading a file by passing a key-value pair, set the key-value, as <”filename”, “rawbytes”>. String1 should be file name and String2 should be file raw bytes. Only then the raw bytes will be taken into consideration and sent as “multipart/formdata.” Otherwise, the raw bytes will be ignored.

SPA and Desktop Web Limitations

FileSystem or File APIs may not work for SPA and Desktop Web platforms. Only voltmx.io.FileSystem.browse and voltmx.io.FileSystem.uploadFiles APIs are available for Desktop Web.
Raw bytes cannot be read using the File APIs. You can obtain the raw bytes of any file using the openMediaGallery API (The user must select the file from the device's media gallery).
The Send method of the HttpRequest API will not encode the data based on the Content-Type header or data type. You need to encode the data that needs to be sent. By default, the data is encoded in text. Following are a few references help you encode the data:
multipart/form-data: Reference Link
x-www-form-urlencoded: Reference Link 1, Reference Link 2
File raw bytes can be read through the voltmx.net.HttpRequest response. The raw bytes cannot be saved to a file using the File APIs. The raw bytes can be downloaded using the method in the Reference Link.

Constants

The constants used by HttpRequest APIs are:

constants.HTTP_RESPONSE_TYPE_TEXT
constants.HTTP_RESPONSE_TYPE_JSON
constants.HTTP_RESPONSE_TYPE_DOCUMENT
constants.HTTP_RESPONSE_TYPE_RAWDATA
constants.HTTP_READY_STATE_UNSENT = 0
constants.HTTP_READY_STATE_OPENED = 1
constants.HTTP_READY_STATE_HEADERS_RECEIVED = 2
constants.HTTP_READY_STATE_LOADING = 3
constants.HTTP_READY_STATE_DONE = 4
constants.HTTP_METHOD_GET
constants.HTTP_METHOD_POST

The delete quotes values are mapped to the corresponding http contentType as below:

ResponseType	HTTP ContentType
constants.HTTP_RESPONSE_TYPE_TEXT	application/text, text/plain
constants.HTTP_RESPONSE_TYPE_JSON	application/json
constants.HTTP_RESPONSE_TYPE_DOCUMENT	application/xml, text/xml, text.md, mime type that ends with +xml
constants.HTTP_RESPONSE_TYPE_RAWDATA	Type except the above values