Class: GDHttpRequest

GDHttpRequest()

Implements the secure HTTP communications APIs.

Constructor

new GDHttpRequest()

Properties:
Name Type Description
method string Case-sensitive string containing the HTTP method, which will be sent to the server. Typical values are: "GET", "POST", "HEAD", "OPTIONS", "TRACE", "PUT", "CONNECT". Any other value is sent as a custom method.
url string Uniform Resource Locator (URL) that will be requested. The URL must be fully qualified, including a scheme, domain, and path. For example: "http://www.example.com/index.html".
timeout number Length of time out in seconds, or 0 (zero) for never. A negative timeout number will allow this request to use the default timeout value (30 seconds).
isAsync boolean Set this value to true to make asynchronous calls.
user string Authentication username. For Kerberos, this is in the user@realm format.
password string Authentication password.
auth string The authentication scheme. Valid values are:
  • "NTLM" to use NTLM authentication
  • "DIGEST" to use Digest Access authentication
  • "NEGOTIATE" to use negotiated Kerberos authentication
  • "BASIC" or a null pointer to use Basic Access authentication.
isIncremental boolean Determine if the response from an asynchronous HTTP request should be processed incrementally (as soon as data is received), or if the entire request should be returned within a single response.
disableHostVerification boolean Disable host name verification, when making an HTTPS request. Host name verification is an SSL/TLS security option.
disableFollowLocation boolean Disable automatic following of redirections. When automatic following is disabled, the application must handle redirection itself, including handling Location: headers, and HTTP statuses in the 30x range.
disablePeerVerification boolean Disable certificate authenticity verification, when making an HTTPS request. Authenticity verification is an SSL/TLS security option.
disableCookieHandling boolean Disable automatic cookie handling. When automatic handling is disabled, the application must store and process cookies itself.
cookieState string Stores a value that determines whether or not cookies should be cleared prior to sending the request. This value should not be set directly. Instead, call the clearCookies method.
host string The address of the proxy. Can be either an Internet Protocol address (IP address, for example "192.168.1.10"), or a fully qualified domain name (for example "www.example.com").
port number Number of the port on the proxy to which connection will be made.
proxyUser string The proxy authentication username.
proxyPassword string The proxy authentication password.
proxyAuth string The proxy authentication scheme. Valid values are:
  • "NTLM" to use NTLM authentication
  • "DIGEST" to use Digest Access authentication
  • "BASIC" or a null pointer to use Basic Access authentication.
fileName string The path (optional) and filename of the file to upload if this is a file upload request. If path is omitted, the file is read from the current working directory. NOTE: There is no need to set this property directly since it will be set during the sendFile function call (see sendFile).
sendOptions object This object contains any optional parameters that are sent with the HTTP request. This value should not be set directly. Instead, call the desired optional methods to set the request parameters (e.g. addPostParameter, addRequestHeader, addHttpBody).
Source:

Methods

addHttpBody(body)

Call this function to add an httpBody to a post request, the body will take the place of any post parameters
Parameters:
Name Type Description
body string the http body to be sent
Source:

addPostParameter(key, value)

Call this function to add a name/value pair to the HTTP request. The request method must be "POST". Multiple name/value pairs can be added, by calling this function multiple times. When the request is sent, name/value pairs will be encoded in the request body in a way that is compatible with HTML form submission. No other body data can be passed in the send call.
Parameters:
Name Type Description
key string The name associated with the value.
value string The value to be set.
Source:

addRequestHeader(key, value)

Call this function to add a Header Field to the HTTP request. This is for standard HTTP Header Fields such as "Authorization". This function can be called zero or more times, since not all HTTP requests will require headers to be added by the application. If a header key is added multiple times, only the last stored value will be maintained (e.g. duplicate keys are not allowed).
Parameters:
Name Type Description
key string The HTTP Header Field to be added.
value string The header field's value.
Source:

clearCookies(includePersistentStore)

Clear cookies that were automatically stored. Cookies can be cleared from memory only, or from the persistent cookie store too. If cleared from memory only, cookies will still be reloaded from the persistent cookie store when the application is next launched. This function is most useful when automatic cookie handling is enabled (i.e. GDHttpRequest.disableCookieHandling = false).
Parameters:
Name Type Description
includePersistentStore boolean When this value is set to true, then all cookies are cleared from memory and the persistent cookie storage file. When this value is false, then all cookies are cleared from memory only.
Source:

clearHttpBody()

Call this function to clear the httpBody of a request
Source:

clearPostParameters()

Call this function to remove all name/value post variables from the HTTP request. Name/value pairs would have been added with the addPostParameter function. This function need only be called if it is required to clear name/value pairs before sending.
Source:

clearRequestHeaders()

Call this function to remove all name/value request headers that were added through a call to addRequestHeader.
Source:

createRequest(method, url, timeout, isAsync, user, password, auth, isIncremental) → {GDHttpRequest}

Call this function to create the HTTP request, and set the main parameters. NOTE: This function only initializes the HTTP parameters; it does not initiate data transfer (see send).
Parameters:
Name Type Description
method string Case-sensitive string containing the HTTP method, which will be sent to the server. Typical values are: "GET", "POST", "HEAD", "OPTIONS", "TRACE", "PUT", "CONNECT". Any other value is sent as a custom method.
url string Uniform Resource Locator (URL) that will be requested. The URL must be fully qualified, including a scheme, domain, and path. For example: "http://www.example.com/index.html".
timeout number Length of time out in seconds, or 0 (zero) for never. A negative timeout number will allow this request to use the default timeout value (30 seconds).
isAsync boolean Set this value to true to make asynchronous calls.
user string Authentication username. For Kerberos, this is in the user@realm format.
password string Authentication password.
auth string The authentication scheme. Valid values are:
  • "NTLM" to use NTLM authentication
  • "DIGEST" to use Digest Access authentication
  • "NEGOTIATE" to use negotiated Kerberos authentication
  • "BASIC" or a null pointer to use Basic Access authentication.
isIncremental boolean Determine if the response from an aysnchronous HTTP request should be processed incrementally (as soon as data is received), or if the entire request should be returned within a single response.
Source:
Returns:
The newly created request object.
Type
GDHttpRequest

disableHttpProxy()

Call this function to disable connection through an HTTP proxy. This function should be called before GDHttpRequest.send or GDHttpRequest.sendFile has been called.
Source:

enableClientCertAuthOnUIWebView()

This method enables certificate-based authentication for XMLHttpRequest. It has to be called at first place when 'ondeviceready' event occures to connect to WebView. In case of HTTPS your SSL/TLS self-signed cervificate from your server endpoint should be trusted on your device. Please note that this call should be done only once per UIWebView.
Source:
Example
<pre class="prettyprint"><code>
window.plugins.GDHttpRequest.enableClientCertAuthOnUIWebView();

var url = 'https://your/server/endpoint'; // here should be your server endpiont that requires certificate-based auth
var xhr = new XMLHttpRequest();
xhr.open("GET", url);

xhr.onreadystatechange = function () {
    if (xhr.readyState == 4) {

        if (xhr.status === 200) {
            alert(xhr.responseText)
        } else {
            alert("Error", xhr)
        }
    }
};

xhr.send();
</code></pre>

enableHttpProxy(host, port, user, password, auth)

Call this function to configure an HTTP proxy address and credentials, and enable connection through the proxy. The proxy server can be located behind the enterprise firewall. In this case its address must be registered in the enterprise's Good Control (GC) console. Registration would usually be as a enterprise management console additional server. See the Good Control overview for application developers. Certificate authenticity verification while using a proxy is not currently supported. When making HTTPS requests through a proxy, SSL/TLS certificate verification must be disabled, see the disablePeerVerification function. This function should be called before GDHttpRequest.send or GDHttpRequest.sendFile has been called.
Parameters:
Name Type Description
host string The address of the proxy. Can be either an Internet Protocol address (IP address, for example "192.168.1.10"), or a fully qualified domain name (for example "www.example.com").
port number Number of the port on the proxy to which connection will be made.
user string The proxy authentication username.
password string The proxy authentication password.
auth string The proxy authentication scheme. Valid values are:
  • "NTLM" to use NTLM authentication
  • "DIGEST" to use Digest Access authentication
  • "BASIC" or a null pointer to use Basic Access authentication.
Source:

parseHttpResponse(responseText) → {GDHttpResponse}

Call this function to transform the HTTP response text into a GDHttpResponse object.
Parameters:
Name Type Description
responseText string A string representing the HTTP response text.
Source:
Returns:
The HTTP response object.
Type
GDHttpResponse

send(success, fail)

Send the HTTP request with it's associated parameters.
Parameters:
Name Type Description
success function Callback function to invoke upon successful completion of the request.
fail function Callback function to invoke if the request cannot be completed.
Source:
Example
<pre class="prettyprint"><code>
var data_json_url = "http://servername.dev.company.com:8082/data.json";
var poster_url = "http://servername.dev.company.com:8082/httpposter/load";
var MaxTestDuration = 10 * 1000; // In milliseconds.
var gTestTimeoutID = null;
var aRequest;

function myHTTPRequest(){
var method = "POST";
var url = data_json_url;
var timeout = 30;
var isAsync = false;
var user = null;
var password = null;
var auth = null;
var isIncremental = true;
var requestBody = {key: "value"};

//-- createRequest
aRequest = window.plugins.GDHttpRequest.createRequest(method, url, timeout, isAsync, user, password, auth, isIncremental);

//-- clearCookies in memory
aRequest.clearCookies(false);

//-- clearCookies in memory and the persistent cookie storage file
aRequest.clearCookies(true);

//-- enableHttpProxy & disableHttpProxy
var host = "some_host.com", port = 8080;
user = "some_user";
password = "some_pwd";
aRequest.enableHttpProxy(host, port, user, password, auth);
aRequest.disableHttpProxy();

//-- addRequestHeader
var headerName = "customHeader", headerValue = "customValue";
aRequest.addRequestHeader(headerName, headerValue);

//-- addHttpBody & clearHttpBody
aRequest.addHttpBody(JSON.stringify(requestBody));
aRequest.clearHttpBody();

//-- addPostParameter & clearPostParameters
var postName = "someName", postValue = "some value";
aRequest.addPostParameter(postName, postValue);
aRequest.clearPostParameters();

//-- send
function sendSuccess(response) {
 console.log("Received valid response from the send request");
 try {
     //-- parseHttpResponse
     var responseObj = window.plugins.GDHttpRequest.parseHttpResponse(response);
     console.log(responseObj.responseText);
 } catch(e) {
     console.log("Invalid response object returned from call to send.");
 }
 };

function sendFail() {
 console.log("The send request resulted in an error.");
}

aRequest.send(sendSuccess,sendFail);
}

</code></pre>

sendFile(fileName, success, fail)

Call this function to upload a file using the HTTP request object. NOTE: this method does not support asynchronous operations. The HTTP request's method can be "PUT" or a custom method. This function causes the HTTP request to be sent, similarly to the send function, above. The body of the request will be the contents of the specified file. The file will not be deleted after it is uploaded. Uploading directly from the BlackBerry Dynamics secure file system is supported.
Parameters:
Name Type Description
fileName string The path (optional) and filename of the file to upload. If path is omitted, the file is read from the application documents directory.
success function Callback function to invoke upon successful completion of the request.
fail function Callback function to invoke if the request cannot be completed.
Source: