HttpClient
This document describes the HttpClient available in the JavaScript environment for app serivices.
Table of content
request
Creates an HttpClientRequest object. The actual request is started asynchronously. So synchronous function calls on that object are handled before the request is sent.
Parameters
| string method | The HTTP method to be used. Supported values are "GET", "PUT", "POST", "DELETE", "HEAD", "OPTIONS", "TRACE", "PROPFIND", "MKCOL", "COPY", "MOVE", "LOCK", "UNLOCK", "PROPPATCH", "PATCH". |
| string uri | An absolute http: or https: URI. |
Return value
var req = HttpClient.request("GET", "https://www.innovaphone.com");
timeout
Sets a timeout that shall be used for HTTP requests. If the function is not called by the application, a default timeout of 60s is used.
HTTP requests will be terminated if the server does not respond or sends no more data for the specified time. In that cases the onerror callback is
invoked with error "HTTP_SHUTDOWN_TIMEOUT".
Parameters
| string timeoutMs | The desired timeout in milliseconds. 0 means that no timeout shall be used. |
Return value
| HttpClient | A reference to the object itself. Useful for method chaining. |
var req = HttpClient.timeout(30000);
auth
Sets credentials that shall be used for HTTP authentication (basic, digest, ntlm), if requested by the server.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.
Parameters
| string username | |
| string password | |
Return value
req.auth("someuser","somepassword");
header
Sets a custom request header.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.
Parameters
| string field | Name of the header field. |
| string value | Value of the header field. |
Return value
req.header("X-Token","c29tZXRva2Vu");
contentType
Sets the content type of the request body. If the function is not called, "text/plain" will be used as a default.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.
Parameters
| string value | An Internet Media Type value. |
Return value
req.contentType("application/json");
contentLength
Sets the content length of the request body. If the function is not called, chunked encoding will be used.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.
Setting the content length requires the application to send excactly the specified number of bytes using the send function.
Parameters
| uint value | The content length in bytes. |
Return value
req.contentLength(17);
onrecv
Sets a callback function for receiving response data. The data is received asynchronouly using flow control. So only a specified number of bytes is received at a time. After invoking the onrecv callback, the library waits for the application to process the data. To receive the next chunk of data the application must call recv.
Optional. If no callback is set, the library will silently discard the response data.
Parameters
| function callback(HttpClientRequest request, Uint8Array data, bool last) | A callback that will be called when response data is received. |
| int bufferSize | The maxiumum number of bytes that shall be received per callback. |
Return value
var responseData = "";
req.onrecv(function(req, data, last) {
responseData += new TextDecoder("utf-8").decode(data);
if (!last) req.recv();
}, 1024);
recv
Tells the library to receive the next chunk of data.
Must be called after receiving the onrecv callback, if the last parameter was false.
Return value
req.onrecv(function(req, data, last) {
if (!last) req.recv();
});
onsend
Sets a callback function for sending request body data. The data is sent asynchronouly using flow control. So the library invokes the callback to notify the application that is ready to send data. Then it waits for the application to call send.
Optional. If no callback is set, the library will send a request with an empty body.
Parameters
| function callback(HttpClientRequest request) | A callback that will be called when the libary is ready to send data. |
Return value
req.onsend(function(req) {
req.send(new TextEncoder("utf-8").encode("somedata"), true);
});
send
Tells the library to send the next chunk of data.
Must be called after receiving the onsend callback.
Parameters
| Uint8Array data | The data to be sent. |
| bool last | false if there is more data to be sent and the application wants to receive another onsend callback. true for the last chunk of data. |
Return value
req.onsend(function(req) {
req.send(new TextEncoder("utf-8").encode("somedata"), true);
});
oncomplete
Sets a callback function that is invoked when the request is completed.
Optional.
Parameters
| function callback(HttpClientRequest request, bool success) | A callback that will be called when the request is complete. |
Return value
req.oncomplete(function(req, success) {
log("HttpRequest " + (success ? "succeeded" : "failed"));
});
onerror
Sets a callback function that is invoked when the request has been aborted.
Optional. If no onerror callback is set, aborted requests will lead to an oncomplete callback with success=false instead.
Parameters
| function callback(error) |
A callback that will be called when the request has been aborted. The parameter error is a string representation of http_shutdown_reason_t.
|
Return value
req.oncomplete(function(req, success) {
log("HttpRequest complete");
})
.onerror(function(error) {
log("HttpRequest error=" + error);
});
responseCode
Returns the HTTP response status code.
Optional. Can be called after the request is completed and the response has been received.
Return value
| integer | If the response header has been received already: The HTTP status code of the response. |
| undefined | If the response header has not been received yet. |
var code = req.responseCode();
responseCodeDescription
Returns the HTTP response status code and reason phrase (e.g. "404 Not Found").
Optional. Can be called after the request is completed and the response has been received.
Return value
| string | If the response header has been received already: The HTTP status code and reason phrase of the response. |
| undefined | If the response header has not been received yet. |
var description = req.responseCodeDescription();
responseHeader
Returns the value of a header field in the response.
Optional. Can be called after the request is completed and the response has been received.
Parameters
| string field | The name of the header field. |
Return value
| array[string] | An array of strings containing the values for the specified response header. Note that a header field can occur multiple times. That is why an array is returned instead of a single string. |
var arr = req.responseHeader("X-Token");
close
Can be used to abort the request at any time.
Return value
req.close();
Examples
In this example we get a text file in 2048 byte chunks and print the content to the log.
var text = "";
HttpClient.request("GET", "https://www.example.com/file.txt")
.onrecv(function (req, data, last) {
text += new TextDecoder("utf-8").decode(data);
if (!last) req.recv();
}, 2048)
.oncomplete(function(req, success) {
if (success) log("GET OK\n" + text);
else log("GET ERROR");
});
In this example we put a text file with the content "sometext".
HttpClient.request("PUT", "https://www.example.com/file.txt")
.contentType("text/plain")
.onsend(function(req) {
req.send(new TextEncoder("utf-8").encode("sometext"), true);
})
.oncomplete(function(req, success) {
log(success ? "PUT OK" : "PUT ERROR");
});
In this example we delete a text file.
HttpClient.request("DELETE", "https://www.example.com/file.txt")
.oncomplete(function(req, success) {
log(success ? "DELETE OK" : "DELETE ERROR");
});