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

ParameterRequiredBeschreibung
$msnoxNumber of the Miniserver


$commandxThe 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.

ParameterDefaultBeschreibung
timeout5 (s)Request timeout in seconds


ssl_verify_hostname0

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

ParameterBeschreibung

1. return

The raw response of the Miniserver. undef on any error.

2. returnA 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};


KeyBeschreibung
errorIn 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". 

statusThis is the full http status line, like "200 OK" or "404 Not found".
messageThis 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
filenameThis 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 ) );