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:
|
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:
|
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). |
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 |
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. |
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. |
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. |
clearHttpBody()
Call this function to clear the httpBody of a request
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.
clearRequestHeaders()
Call this function to remove all name/value request headers that
were added through a call to addRequestHeader.
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:
|
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. |
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.
enableClientCertAuth()
iOS Only! 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 certificate from your server endpoint
should be trusted on your device.
Please note that this call should be done only once per WKWebView.
Example
window.plugins.GDHttpRequest.enableClientCertAuth();
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.setRequestHeader('Access-Control-Allow-Origin', '*');
xhr.onreadystatechange = function () {
if (xhr.readyState == 4) {
if (xhr.status === 200) {
alert(xhr.responseText)
} else {
alert("Error", xhr)
}
}
};
xhr.send();
enableClientCertAuthOnUIWebView()
iOS Only! 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 WKWebView.
- Deprecated:
- It will be removed in future versions. Use window.plugins.GDHttpRequest.enableClientCertAuth(); instead.
- Source:
Example
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();
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:
|
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. |
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. |
Example
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);
}
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. |