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.
Name | 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 | - | 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:myplugin/http_receive.lua format) |
user_data | string | - | Any data which will be passed to receive_script and send_script. |
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: 3600000 milliseconds. |
connect_timeout | int | - | Timeout in milliseconds for establishing connection. Default value: 10000 milliseconds. Max possible value: 600000 milliseconds. |
Return value: id of the request
Lua errors:
- Required parameter didn't define:
- The file doesn\'t exist:
- Plugin doesn\'t have permissions to the file:
- Wrong format of parameter:
- Limit of parameter is reached:
- Limit of connections is reached
http.repeat_request()
Make one more request with an already opened connection.
Name | 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 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 | - | 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:myplugin/http_receive.lua format) |
user_data | string | - | Any data which will be passed to receive_script and send_script. |
timeout | int | - | Timeout in milliseconds for waiting response. Default value: 30000 milliseconds. Max possible value: 3600000 milliseconds. |
connect_timeout | int | - | Timeout in milliseconds for establishing connection. Default value: 10000 milliseconds. Max possible value: 600000 milliseconds. |
Lua errors:
- Required parameter didn't define:
- The file doesn\'t exist:
- The plugin doesn\'t have permissions to the file:
- Wrong format of the parameter:
- Limit of the parameter is reached:
- Connection doesn't exist
- Sending of previous request data didn't finish
http.close_connection()
Close existing connection. A plugin can use only own connections.
Name | Type | Required | Description |
---|---|---|---|
id | string | + | Unique ID of request |
Return value: bool
Lua errors:
- Required parameter didn't define:
- Wrong format of the parameter:
- Limit of the parameter is reached:
- Connection doesn't exist
http.send_data()
Method for sending the next portion of data for the existing request. A plugin can use only own connections.
Name | Type | Required | Description |
---|---|---|---|
id | string | + | Unique ID of request |
data | string | + | 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:
- Required parameter didn't define:
- Wrong format of the parameter:
- Limit of the parameter is reached:
- Connection doesn't exist
- Request for sending data wasn\'t started
http.get_connection_info()
Get the main information about a connection. A plugin can ask only about own connections.
Name | Type | Required | Description |
---|---|---|---|
id | string | + | Unique ID of request |
Return value:
Name | Type | Required | Description |
---|---|---|---|
id | string | + | Unique ID of request |
url | string | + | Full url for making connection( can contain custom port ) |
user_data | string | - | User data which was passed to http.request() call. |
max_data_length | int | + | Size of data which can be send peer one script execution via http.send_data() method |
Lua errors:
- Required parameter didn't define:
- Wrong format of the parameter:
- Limit of the parameter is reached:
- Connection doesn't exist