Module for HTTP clients. Supports get, put and post methods.
Depends on cordova-plugin-advanced-http. To install run
cordova plugin add cordova-plugin-advanced-http
A nominal usage example is:
httpClient.get({
trustAll: true,
url: "https://www.google.com"
},
function(response) {
console.log(response.body);
}
);
Many of the features of http-client modules for Cape Code and Node hosts are not supported in this module due to limitiations in the plugin. Places in the documentation where this implementation cannot meet the API of the other versions are marked with FIXMEs
FIXME: PUT and POST commands only accept stringified JSON objects as the body They are sent as json or url encoding depending on this implementation of http-client's special option: "encoding". Blame cordova-plugin-advanced-http.
Both http and https are supported.
- Version:
- $$Id: http-client.js 75980 2017-04-23 00:19:25Z beth@berkeley.edu $$
- Source:
- Version:
- $$Id: http-client.js 75980 2017-04-23 00:19:25Z beth@berkeley.edu $$
- Source:
Classes
Methods
(static) get(options, responseCallback)
Convenience method to issue an HTTP GET. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) get(options, responseCallback)
Convenience method to issue an HTTP GET. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) post(options, responseCallback)
Convenience method to issue an HTTP POST. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) post(options, responseCallback)
Convenience method to issue an HTTP POST. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) put(options, responseCallback)
Convenience method to issue an HTTP PUT. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) put(options, responseCallback)
Convenience method to issue an HTTP PUT. This just calls request() and then calls end() on the object returned by request(). It returns the object returned by request() (an instance of ClientRequest). See request() for documentation of the arguments.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(static) request(options, responseCallback)
Issue an HTTP request and provide a callback function for responses. The callback is a function that is passed an instance of IncomingMessage, defined here. This function returns an instance of ClientRequest, also defined here. The HTTP request will not actually be issued until you call the end() function on the returned ClientRequest.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
The options argument can be a string URL or a map with the following fields (this helper class assumes all fields are present, so please be sure they are):
- trustAll: FIXME THIS IS A CORDOVA EXCLUSIVE OPTION. Accept all SSL certificates. Or disable accepting all certificates. Defaults to false.
- validateDomainName: FIXME THIS IS A CORDOVA EXCLUSIVE OPTION. Whether or not to validate the domain name in the certificate. Defaults to true.
- encoding: FIXME: THIS IS ONLY A CORDOVA ISSUE For put and post requests, cordova-plugin-advanced-http only supports JSON and url encodings. Possible values are "json" and "urlencoded". "json" is default. See. https://www.npmjs.com/package/cordova-plugin-advanced-http-custom-error#setdataserializer
- body: The request body, if any. FIXME: This should support all strings and image data but doesn't. It only supports stringified JSON objects (not stringified strings!). These are either url or json encoded in the body depending on the value of the Cordova-only special "encoding" option. Default is json encoding.
- headers: An object containing request headers. By default this is an empty object. Items may have a value that is an array of values, for headers with more than one value.
- keepAlive: FIXME: The value true is not supported by the cordova http plugin! In other hosts, this is a boolean that specifies whether to keep sockets around in a pool to be used by other requests in the future. This defaults to false.
- method: FIXME: The only supported HTTP request methods in this module are 'GET', 'PUT', and 'POST'. Defaults to 'GET'. In other hosts more methods may be supported.
- outputCompleteResponseOnly: FIXME: The value false is not supported by the cordova http plugin! In other hosts, if false, then the multiple invocations of the callback may be invoked for each request. This defaults to true, in which case there will be only one invocation of the callback.
- timeout: FIXME: This parameter is ignored by the cordova http plugin! In other hosts, the amount of time (in milliseconds) to wait for a response before triggering a null response and an error. This defaults to 5000.
- url: A string that can be parsed as a URL, or an object containing
the following fields:
- host: A string giving the domain name or IP address of the server to issue the request to. This defaults to 'localhost'.
- path: Request path as a string. This defaults to '/'. This can include a query string, e.g. '/index.html?page=12', or the query string can be specified as a separate field (see below). An exception is thrown if the request path contains illegal characters.
- protocol: The protocol. This is a string that defaults to 'http'.
- port: Port of remote server. This defaults to 80. Using the defaultwill probably yield undesired behavior if the specified protocol isn't http.
- query: A query string to be appended to the path, such as '?page=12'.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options or URL. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
Returns:
An instance of ClientRequest.
(static) request(options, responseCallback)
Issue an HTTP request and provide a callback function for responses. The callback is a function that is passed an instance of IncomingMessage, defined here. This function returns an instance of ClientRequest, also defined here. The HTTP request will not actually be issued until you call the end() function on the returned ClientRequest.
This implementation ensures that for any accessor that calls this function, the callback functions are called in the same order as invocations of this request() function that triggered the request. If you call this function from the same accessor before the previous request has been completed (the callback function has been called or it has timed out), then the request will be queued to be issued only after the previous request has been satisfied.
The options argument can be a string URL or a map with the following fields (this helper class assumes all fields are present, so please be sure they are):
- trustAll: FIXME THIS IS A CORDOVA EXCLUSIVE OPTION. Accept all SSL certificates. Or disable accepting all certificates. Defaults to false.
- validateDomainName: FIXME THIS IS A CORDOVA EXCLUSIVE OPTION. Whether or not to validate the domain name in the certificate. Defaults to true.
- encoding: FIXME: THIS IS ONLY A CORDOVA ISSUE For put and post requests, cordova-plugin-advanced-http only supports JSON and url encodings. Possible values are "json" and "urlencoded". "json" is default. See. https://www.npmjs.com/package/cordova-plugin-advanced-http-custom-error#setdataserializer
- body: The request body, if any. FIXME: This should support all strings and image data but doesn't. It only supports stringified JSON objects (not stringified strings!). These are either url or json encoded in the body depending on the value of the Cordova-only special "encoding" option. Default is json encoding.
- headers: An object containing request headers. By default this is an empty object. Items may have a value that is an array of values, for headers with more than one value.
- keepAlive: FIXME: The value true is not supported by the cordova http plugin! In other hosts, this is a boolean that specifies whether to keep sockets around in a pool to be used by other requests in the future. This defaults to false.
- method: FIXME: The only supported HTTP request methods in this module are 'GET', 'PUT', and 'POST'. Defaults to 'GET'. In other hosts more methods may be supported.
- outputCompleteResponseOnly: FIXME: The value false is not supported by the cordova http plugin! In other hosts, if false, then the multiple invocations of the callback may be invoked for each request. This defaults to true, in which case there will be only one invocation of the callback.
- timeout: FIXME: This parameter is ignored by the cordova http plugin! In other hosts, the amount of time (in milliseconds) to wait for a response before triggering a null response and an error. This defaults to 5000.
- url: A string that can be parsed as a URL, or an object containing
the following fields:
- host: A string giving the domain name or IP address of the server to issue the request to. This defaults to 'localhost'.
- path: Request path as a string. This defaults to '/'. This can include a query string, e.g. '/index.html?page=12', or the query string can be specified as a separate field (see below). An exception is thrown if the request path contains illegal characters.
- protocol: The protocol. This is a string that defaults to 'http'.
- port: Port of remote server. This defaults to 80. Using the defaultwill probably yield undesired behavior if the specified protocol isn't http.
- query: A query string to be appended to the path, such as '?page=12'.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options or URL. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
Returns:
An instance of ClientRequest.
(inner) cordovaGet(request)
Issue an HTTP get request. Initiated by calling end() on a ClientRequest with its method parameter set to GET
In addition to the description of options parameter given in parseOptions(), this parameter can call accepting all, if trustAll attribute in options is set to true.
Parameters:
| Name | Type | Description |
|---|---|---|
request |
The clientRequest object initiating the command. |
- Source:
(inner) cordovaGet(request)
Issue an HTTP get request. Initiated by calling end() on a ClientRequest with its method parameter set to GET
In addition to the description of options parameter given in parseOptions(), this parameter can call accepting all, if trustAll attribute in options is set to true.
Parameters:
| Name | Type | Description |
|---|---|---|
request |
The clientRequest object initiating the command. |
- Source:
(inner) cordovaPost(options, responseCallback)
Issue an HTTP post request.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(inner) cordovaPost(options, responseCallback)
Issue an HTTP post request.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(inner) cordovaPut(options, responseCallback)
Issue an HTTP put request.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options, see parseOptions for more details. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(inner) cordovaPut(options, responseCallback)
Issue an HTTP put request.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
The options, see parseOptions for more details. |
|
responseCallback |
The callback function to call with an instance of IncomingMessage, or with a null argument to signal an error. |
- Source:
(inner) parseOptions(request)
Parses the request options and returns cordova plugin compatible attributes.
Parameters:
| Name | Type | Description |
|---|---|---|
request |
the clientRequest object containing options at request.options. |
- Source:
Returns:
an object with cordova-plugin-advanced-http compatible attributes: url, parameters and headers. returns null if unable to parse the options.
(inner) parseOptions(request)
Parses the request options and returns cordova plugin compatible attributes.
Parameters:
| Name | Type | Description |
|---|---|---|
request |
the clientRequest object containing options at request.options. |
- Source:
Returns:
an object with cordova-plugin-advanced-http compatible attributes: url, parameters and headers. returns null if unable to parse the options.