HTTP Module

The module provides the ability to make HTTP requests.

require 'http'

Overview: API Requests


http.request()

Configures and starts a new asynchronous HTTP request. Returns connection identifier.

Arguments: options: table

Table Field Type Required Description
url string + Full url for making connection( can contain custom port )
certs object -
certs.ca string - Path to file with certificates chain to verify server's certificate in PEM format( in HUB:zwave/certs/server.ca format )
certs.key string - Path to file with private key of client in PEM format (only if server requires client authentication via client certificates)( in HUB:zwave/certs/server.ca format )
certs.public string - Path to file with certificate of client in PEM format (only f server requires client authentication via client certificates)( in HUB:zwave/certs/server.ca format )
skip_security bool - Skip any security checks: check date, domain, and self-signed certificates criteria. Default value: false.
type string - Type of request. Possible value: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE. Default value: GET.
content_type string - Type of sending content
user string - User name
password string - User password
headers array of objects - Custom request headers
headers.key string + Name of header record
headers.value string + Value of header record
keep_alive bool - Keep HTTP request alive after establishing connection. Each plugin can have not more than 50 "alive" connections. Default value: false.
repeat_allowed bool - Allows sequential repeat_request() call after the request is completed. Otherwise, allows to get multiple responses on a single request. Default value: true.
content_length int - Length of content data in bytes
data string / binary - Data for sending
last bool - Does all data was sent or not? Default value: true. If this field is false then http_data_send event would be generated for sending next part of data for this request.
redirection int - Max number of allowed redirection. Default value: 3. Max value can be: 15.
handler string + Path to script file of plugin which should be executed when any event of connection would be generated( in HUB:my_plugin/http_receive.lua format)
user_data any - User data that was passed to an http.request() call. Can be of any valid type: string, number, boolean, array, object. If user_data is null, the value will not be set.
new_data_buffer int - Preferred size in bytes of buffer which should be used for receiving new data via http_data_received event. Minimal possible size: 32, max possible size: 500000 (Linux) or 1024 (RTOS).
new_data_cache bool - Do not send http_data_received event unless buffer is full or end of response (or it's significant part) was detected. Default value: true. When disabled, event will be triggered immediately after new portion of data received (useful for custom format response streams) thus increasing amount of events with smaller portions of data.
timeout int - Timeout in milliseconds for waiting response. Default value: 30000 milliseconds. Max possible value: 86400000 milliseconds( 24 hours ).
connect_timeout int - Timeout in milliseconds for establishing connection. Default value: 10000 milliseconds. Max possible value: 600000 milliseconds.
fail_on_error boolean - If true, the HTTP connection will be closed if a HTTP response contains status codes in the range [400, 599]. Otherwise, the HTTP-client will proceed to download document's body till the end, and then, will generate the http_connection_closed event with the HTTP status code according to the HTTP-server response. The reason field http_connection_closed.reason = {"code": 5, "text": "Closed by server" }. Default value: true.
verbose boolean - Will allow the module to be more verbose in logging mode TRACE. Default value: false.

Return value: string, id of the request

Lua errors:

http.repeat_request()

Make one more request with an already opened connection.

Arguments: options: table

Table Field Type Required Description
id string + Unique id of existing request
type string - Type of request. Possible value: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE. Default value: GET.
content_type string - Type of sending content
headers array of objects - Custom request headers
headers.key string + Name of a header record
headers.value string + Value of a header record
keep_alive bool - Keep the HTTP request alive after establishing connection. Each plugin can have not more than 50 "alive" connections. Default value: false.
repeat_allowed bool - Allows sequential repeat_request() call after the request is completed. Otherwise, allows to get multiple responses on a single request. Default value: true.
content_length int - Length of content data in bytes
data string, binary - Data for sending
last bool - Does all data was sent or not? Default value: true. If this field is false then http_data_send event would be generated for sending next part of data for this request.
handler string + Path to script file of plugin which should be executed when any event of connection would be generated( in HUB:my_plugin/http_receive.lua format)
user_data any - User data that was passed to an http.request() call. Can be of any valid type: string, number, boolean, array, object. If user_data is null, the value will not be set..
timeout int - Timeout in milliseconds for waiting response. Default value: 30000 milliseconds. Max possible value: 86400000 milliseconds( 24 hours ).
connect_timeout int - Timeout in milliseconds for establishing connection. Default value: 10000 milliseconds. Max possible value: 600000 milliseconds.

Return value: nothing

Lua errors:

http.close_connection()

Close existing connection. A plugin can use only own connections.

Arguments:

Name Type Required Description
id string + Unique ID of a request

Return value: bool

Lua errors:

http.send_data()

Method for sending the next portion of data for the existing request. A plugin can use only own connections.

Arguments: options: table

Field Type Required Description
id string + Unique ID of a request
data string, binary + Data for sending
last bool - It's the last part of data or not. Default value: true. If it is not the last part of data then http_data_send event will be generated when existing data would be sent.

Return value: Number of sent/buffered bytes

Lua errors:

http.get_connection_info()

Get the main information about a connection. A plugin can ask only about own connections.

Arguments:

Name Type Required Description
id string + Unique ID of a request

Return value: table

Name Type Required Description
id string + Unique ID of a request
url string + Full URL for making a connection (can contain custom port)
user_data any - User data that was passed to an http.request() call. Can be of any valid type: string, number, boolean, array, object. If user_data is null, the value will not be set.
max_data_length int + Size of data that can be sent per one script execution via http.send_data() method

Lua errors:

See also: HTTP Module Events