HttpUtils

Aus FHEMWiki

Allgemein

Das Modul HttpUtils.pm ist sowohl für Modulentwickler, als auch Endanwender gedacht um Daten via HTTP auszutauschen. Es stellt dabei eine Reihe von Funktionen bereit, auf die in diesem Artikel näher eingegangen werden soll.

Erstellt wurde HttpUtils.pm von Rudolf König.

Die Funktionen im Einzelnen

Folgende Funktionen sind für Modulentwickler/Endanwender zur direkten Nutzung gedacht:

GetHttpFile

Die Funktion GetHttpFile ist die denkbar einfachste Variante um eine URL aufzurufen.


Aufruf: GetHttpFile($server, $file)

Parameter Bedeutung
$server Der DNS Name oder die IP-Adresse des HTTP-Servers

Beispiel:

  • www.myhost.com
  • 192.168.0.10
$file Die Datei, welche auf dem HTTP-Server aufgerufen werden soll.

Beispiel:

  • /
  • /index.html
  • /directory/image.jpg

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.


GetFileFromURL

Die Funktion GetFileFromURL ruft die HTTP URL auf und gibt als Funktionsergebnis den Seiteninhalt zurück. Im Gegensatz zu GetHttpFile beinhaltet GetFileFromURL einige Zusatzoptionen in Form von Funktionsparametern.


Aufruf: GetFileFromURL($url, [$timeout], [$data], [$noshutdown], [$loglevel])

Parameter Bedeutung
$url Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten.

Beispiel:

  • http://www.myhost.com/directory/
  • http://www.myhost.com:8080/
  • http://foo:bar@www.myhost.com/
$timeout

optional

Die maximale Dauer in Sekunden für die HTTP-Anfrage


Beispiel: 5 (Sekunden)

Standardwert: 4 Sekunden

$data

optional

Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.


Standartwert: [leer]

$noshutdown

optional

Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Dieser Parameter ist zum Beispiel notwendig um Anfragen an eine FritzBox zu stellen.


Standardwert: 0

$loglevel

optional

Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.


Standardwert: 4

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

GetFileFromURLQuiet

Diese Funktion funktioniert ähnlich wie GetFileFromURL. Allerdings wird die tatsächliche URL in allen erzeugten Log-Meldungen unkenntlich gemacht um z.B. Zugangsdaten nicht preiszugeben. Die aufgerufene Seite wird ebenfalls als Funktionsergebnis zurückgegeben.


Aufruf: GetFileFromURLQuiet($url, [$timeout], [$data], [$noshutdown], [$loglevel])

Parameter Bedeutung
$url Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten.

Beispiel:

  • http://www.myhost.com/directory/
  • http://www.myhost.com:8080/
  • http://foo:bar@www.myhost.com/
$timeout

optional

Die maximale Dauer in Sekunden für die HTTP-Anfrage


Beispiel: 5 (Sekunden)

Standardwert: 4 Sekunden

$data

optional

Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.


Standartwert: [leer]

$noshutdown

optional

Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Dieser Parameter ist zum Beispiel notwendig um Anfragen an eine FritzBox zu stellen.


Standardwert: 0

$loglevel

optional

Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.


Standardwert: 4


HttpUtils_BlockingGet

Wenn die bisher genannten Funktionen nicht ausreichen um die gewünschte Abfrage durchzuführen, so kann man diese Funktion verwenden. Aufgrund zahlreicher Parameter ermöglicht sie viele Anpassungsmöglichkeiten. Diese Funktion hat dabei nicht wie üblich eine Liste an Funktionsparametern, sondern lediglich einen Parameter, welcher ein Hash mit allen Funktionsparametern darstellt. Dieser Hash enthält sämtliche Parameter inkl. Werten.


Aufruf: HttpUtils_BlockingGet($param)

Der Hash $param kann folgende Optionen beinhalten:

Parameter Bedeutung
$param->{url} Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten.

Beispiel:

  • http://www.myhost.com/directory/
  • http://www.myhost.com:8080/
  • http://foo:bar@www.myhost.com/
$param->{timeout}

optional

Die maximale Dauer in Sekunden für die HTTP-Anfrage


Beispiel: 5 (Sekunden)

Standardwert: 4 Sekunden

$param->{data}

optional

Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $param{data} übergeben. Die Daten werden dabei als Formulardaten übertragen. Die Daten können dabei auf zwei Arten übergeben werden:

1. Daten als String:

  • Die Daten werden komplett als gesamter String in $param{data} abgelegt (z.B.: $param{data} = "Jede Menge tolle Daten").

2. Daten als Hash:

  • Die Daten werden als Hash mit Key-Value-Pairs übergeben (z.B.: $param{data}{field1} = "value1", $param{data}{field2} = "value2", ... ). Die Daten werden dann als Formulardaten mit mehrfachen Datenfeldern übertragen.


Standartwert: [leer]

$param->{noshutdown}

optional

Wenn $param->{noshutdown} auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Dieser Parameter ist zum Beispiel notwendig um Anfragen an eine FritzBox zu stellen.


Standardwert: 0

$param->{loglevel}

optional

Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.


Standardwert: 4

$param->{hideurl}

optional

Wenn dieser Parameter den Wert 1 trägt, wird die URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies ist nützlich um z.B. Zugangsdaten geheim zu halten.


Standartwert: 0

$param->{method}

optional

Die HTTP Methode, welche zur Abfrage verwendet werden soll. Sofern keine Daten übertragen werden ist dies standardmäßig "GET", ansonsten "POST". Es können aber auch andere Methoden verwendet werden.


Standardwert: "GET"

$param->{header}

optional

Eigene HTTP-Header Zeilen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. den Content-Type festzulegen, oder einfach nur zusätzliche Header-Felder zu setzen. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.


Beispiel:

  • User-Agent: Mozilla/1.22\r\nContent-Type: application/xml
  • Content-Type: application/xml


Standardwert: [leer]