Metainformationen zur Seite
LoxBerry::IO::mshttp_call2
($data, $object) = mshttp_call2($msno, $command, %options);
Sends a HTTP REST request to the specified Miniserver the raw response, and optional a hash with further information.
This is the improved version of mshttp_call with more optional settings and different response. It also can directly write the response to a file.
LoxBerry Compatibility
This feature first is available with LoxBerry 2.2.1. Set your LB_MINIMUM version in your plugin.cfg accordingly.
This function is the generic Miniserver REST function with raw Miniserver output.
To send or query simple values, you should prefer LoxBerry::IO::mshttp_send and LoxBerry::IO::mshttp_get.
The first parameter is the Miniserver number (numbers are equal to LoxBerry::System::get_miniservers, starting with 1).
The second parameter is a string with the full command, but without hostname, e.g. /jdev/sps/io/Livingroom/state.
The third parameter is an options hash to configure the mshttp_call2 function.
Make sure, that your URL is correctly URI-encoded, especially with Loxone block names ("Küche"), or names with blanks ("Light livingroom").
Parameter
| Parameter | Required | Beschreibung |
|---|---|---|
| $msno | x | Number of the Miniserver |
| $command | x | The full command. The parameter must be URL-encoded correctly (slashes of the url must not be encoded, but parameters do). |
| %options | With options, you can modify the behaviour of the http request. See list below. |
Options
The options hash is optional and can be used to modify default parameters.
| Parameter | Default | Beschreibung |
|---|---|---|
| timeout | 5 (s) | Request timeout in seconds |
| ssl_verify_hostname | 0 | 0 … Do not verify destination certificate for it's hostname 1 … Verify the hostname against it's certificate |
| filename | - | If a filename is provided, the response is stored to the named file. |
Return value
| Parameter | Beschreibung |
|---|---|
| 1. return | The raw response of the Miniserver. undef on any error. |
| 2. return | A hashref to several information about the request. See table below. |
The first return value is the raw response from the Miniserver. It is undef if the request fails or timeouts.
The second return value is a hashref with additional information.
A function call will look like this:
my ( $response, $status ) = mshttp_call2( 1, "/jdev/sps/io/Wohnzimmer" );
Access the additional information with $status->{key}, e.g. $status->{code};
| Key | Beschreibung |
|---|---|
| error | In general, this key is 1 on any errors, or undef if ok. |
| code | This is the http response code. In general, 200 is OK, all other http codes are errors. The special code 601 is "Miniserver not defined". |
| status | This is the full http status line, like "200 OK" or "404 Not found". |
| message | This is a generated message from the function. It may contain both failure and success message. This is not to check for error, but can be displayed if {error} = 1 |
| filename | This contains the filename, if filename was provided in the options, and writing was successful. |
The code status may contain
- a LoxBerry-own "error code" in the 6xx area (e.g. "601" for "Miniserver not defined")
- the HTTP statuscode
- 200 if the request was successful
- 404 if the requested resource was not found
- 500 if you have no permissions to access this resource
Usage
use LoxBerry::IO; ##### Only the response my ($response) = mshttp_call2(1, "/jdev/sps/io/Light_Livingroom/state"); ##### Response with enhanced infos my ($response, $status) = mshttp_call2(1, "/jdev/sps/io/Light_Livingroom/state"); if( $status->{error} ) { print $status->{status} . " " . $status->{message}; } ##### Special options my %options = { timeout => 60 }; my ($response, $status) = mshttp_call2(1, "/jdev/sps/io/Energymeter_Washingmachine/state", %options); #### Special options directly in the call my ($response, $status) = mshttp_call2(1, "/jdev/sps/io/Energymeter_Washingmachine/state", ( timeout => 60 ) );