DevelopmentModuleAPI: Unterschied zwischen den Versionen
K (Typos) |
(setDisableNotifyFn ergänzt) |
||
(84 dazwischenliegende Versionen von 11 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden! | {{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden! | ||
<hr /> | <hr /> | ||
Please note: This list of functions is not | Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]! | ||
}} | }} | ||
Diese Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler | |||
* Wiederverwendbare Routinen leichter identifizieren zu können | * Wiederverwendbare Routinen leichter identifizieren zu können | ||
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen | * Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen | ||
* Aufwand zu verringern | * Aufwand zu verringern | ||
* Bei Änderungen auch betroffene Module leichter | * Bei Änderungen auch betroffene Module leichter identifizieren zu können | ||
Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte. | |||
== FHEM-Befehlsausführung == | == FHEM-Befehlsausführung == | ||
=== AnalyzeCommand === | === AnalyzeCommand === | ||
:< | :<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight> | ||
AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls. | |||
Parameter: | Parameter: | ||
Zeile 21: | Zeile 25: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$client_hash</code>''' | ||
''mandatory<br>can be <code>undef</code>'' | ''mandatory<br>can be <code>undef</code>'' | ||
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung. | || Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$cmd</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!).<br> | ||
Beispiel: | Beispiel: | ||
* | * <code>define dummy1 dummy</code> | ||
* | * <code>{Log3(undef, 1, "Hallo")}</code> | ||
|} | |} | ||
Zeile 40: | Zeile 44: | ||
! Rückgabewert!! Bedeutung | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$error</code>''' | ||
|| Fehlermeldungen, die beim | || Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben. | ||
|} | |} | ||
=== AnalyzeCommandChain === | === AnalyzeCommandChain === | ||
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt. | AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt. | ||
:< | :<syntaxhighlight lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</syntaxhighlight> | ||
Parameter: | Parameter: | ||
Zeile 54: | Zeile 57: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$client_hash</code>''' | ||
''mandatory<br>can be <code>undef</code>'' | ''mandatory<br>can be <code>undef</code>'' | ||
Zeile 60: | Zeile 63: | ||
|- | |- | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$cmds</code>''' | ||
''mandatory'' | ''mandatory'' | ||
Zeile 73: | Zeile 76: | ||
! Rückgabewert!! Bedeutung | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$errors</code>''' | ||
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben. | || Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben. | ||
|} | |} | ||
=== AnalyzePerlCommand === | |||
== | :<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight> | ||
AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen). | |||
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen. | |||
Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben. | |||
Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden. | |||
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden. | |||
Parameter: | Parameter: | ||
Zeile 92: | Zeile 97: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$client_hash</code>''' | ||
''mandatory'' | ''mandatory<br>can be <code>undef</code>'' | ||
|| | || Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung. | ||
|- | |||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$cmds</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt.<br> | ||
Beispiel: | |||
* <code> my $ignore; if($we) {$ignore=1} </code> | |||
|} | |} | ||
Zeile 112: | Zeile 116: | ||
! Rückgabewert!! Bedeutung | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$errors</code>''' | ||
|| | || Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben. | ||
|} | |||
=== EvalSpecials === | |||
:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight> | |||
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt. | |||
Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren. | |||
In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden. | |||
Parameter: | Parameter: | ||
Zeile 138: | Zeile 133: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$cmd</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen. | ||
Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code> | |||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>%specials</code>''' | ||
'' | ''mandatory'' | ||
|| | || Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen. | ||
Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code> | |||
|} | |} | ||
Zeile 157: | Zeile 153: | ||
! Rückgabewert!! Bedeutung | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$final_cmd</code>''' | ||
|| | || Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss. | ||
Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen. | |||
In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet. | |||
|} | |} | ||
=== parseParams === | |||
<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd); | |||
< | my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator); | ||
</syntaxhighlight></ul> | |||
$a = | |||
# | parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt: | ||
* einfache, durch den Separator getrennte, Zeichenfolgen | |||
* benannte Parameter der Form <code><name>=<wert></code> | |||
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten | |||
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt. | |||
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist. | |||
</ | |||
In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird. | |||
Parameter: | Parameter: | ||
Zeile 202: | Zeile 181: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$cmd</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die | || Die Argumente des Kommandos als String oder als Array-Referenz. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$separator</code>''' | ||
'' | ''optional'' | ||
|| Der | || Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden. | ||
| | Standardwert: ' ' ''(Leerzeichen)'' | ||
|- | |||
|'''<code>$joiner</code>''' | |||
''optional'' | |||
| | |||
</ | |||
|- | |- | ||
|'''<code>$keyvalueseparator</code>''' | |||
''optional'' | |||
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '=' | |||
'' | |||
| | |||
|} | |} | ||
Zeile 239: | Zeile 206: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$a</code>''' | ||
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält. | |||
|| | |- | ||
<code> | | style="vertical-align:top" | '''<code>$h</code>''' | ||
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!) | |||
|} | |} | ||
Beispiel: Die Zeile | |||
=== | :<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code> | ||
:< | wird in die folgenden Elemente geparst: | ||
<syntaxhighlight lang="perl"> | |||
# Die nicht benannten Parameter: | |||
$a = [ | |||
'set', | |||
'<name>', | |||
'test1', | |||
'test3', | |||
'test4 test4', | |||
'{my $x = "abc"}' | |||
]; | |||
# Die benannten Parameter: | |||
$h = { | |||
'test10' => '{ { my $abc ="xyz" } }', | |||
'test5' => 'test5 test5', | |||
'test8' => '\'', | |||
'test2' => 'abc', | |||
'test7' => '', | |||
'test9' => '"', | |||
'test6' => 'test6=test6' | |||
}; | |||
</syntaxhighlight> | |||
=== asyncOutput === | |||
:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight> | |||
Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden. | |||
Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist. | |||
Parameter: | Parameter: | ||
Zeile 257: | Zeile 255: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$client_hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt. | ||
|- | |||
| style="vertical-align:top" | '''<code>$message</code>''' | |||
''mandatory'' | |||
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen. | |||
|} | |} | ||
=== SetExtensions === | |||
:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight> | |||
Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet. | |||
Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion. | |||
Parameter: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
|| | ''mandatory'' | ||
<code> | || Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird. | ||
|- | |||
| style="vertical-align:top" | '''<code>$usage_list</code>''' | |||
''mandatory'' | |||
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command <font color="grey">''[...]''</font> choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden. | |||
Beispiel: | |||
:< | * <code>"on off statusRequest"</code> | ||
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code> | |||
|- | |||
| style="vertical-align:top" | '''<code>@set_args</code>''' | |||
''mandatory'' | |||
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]] | |||
|} | |||
Rückgabewerte: | Rückgabewerte: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$error</code>''' | ||
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden. | |||
|} | |||
Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]] | |||
== Time / Timestamp == | |||
=== FmtDateTimeRFC1123=== | |||
<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight> | |||
</ul> | |||
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück. | |||
Parameter: | Parameter: | ||
Zeile 305: | Zeile 326: | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$timestamp</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird<br> | ||
Bsp: <code>1457201868</code> | |||
|} | |||
Rückgabewerte: | |||
| | {| class="wikitable" | ||
|- | |- | ||
! Rückgabe!! Bedeutung | |||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$timestampGMT </code>''' | ||
|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet.<br> | |||
|| | <code>Sat, 05 Mar 2016 18:17:48 GMT</code> | ||
|} | |||
=== FmtDateTime=== | |||
:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight> | |||
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$time</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird.<br> | ||
Bsp: <code>1457201868</code> | |||
|} | |} | ||
Zeile 341: | Zeile 368: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$timestamp </code>''' | ||
|| Zeitstempel | || Zeitstempel in lokaler Zeitzone im Format<br> | ||
<code>2016-02-16 19:34:24</code> | |||
|} | |} | ||
=== TimeNow === | |||
:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight> | |||
:< | |||
Parameter: | Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter. | ||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$timestamp</code>''' | |||
|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format<br> | |||
<code>2016-02-16 19:34:24</code><br> | |||
Benutzt die Funktion <code>FmtDateTime()</code> | |||
|} | |||
=== fhemTimeGm=== | |||
:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight> | |||
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um. | |||
Parameter: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter!! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$sec</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. | || Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$min</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. | || Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$hour</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. | || Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$mday</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31. | || Die Tag-Komponente als Ganzzahl zwischen 1 und 31. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$month</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11. | || Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$year</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Jahres-Komponente. Das Jahr wird dabei | || Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. | ||
|} | |} | ||
Zeile 393: | Zeile 439: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$timestamp </code>''' | ||
|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) <br> | || Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) <br> | ||
Zeile 399: | Zeile 445: | ||
|} | |} | ||
=== fhemTimeLocal=== | |||
:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight> | |||
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um. | |||
:< | |||
</ | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$sec</code>''' | ||
''mandatory'' | |||
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. | |||
|- | |||
| style="vertical-align:top" | '''<code>$min</code>''' | |||
''mandatory'' | |||
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. | |||
Die | |||
|- | |- | ||
| style="vertical-align:top" | '''<code>$hour</code>''' | |||
| style="vertical-align:top" | '''<code>$ | |||
''mandatory'' | ''mandatory'' | ||
|| Die | || Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$mday</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Tag-Komponente als Ganzzahl zwischen 1 und 31. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$month</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der Wert | || Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$year</code>''' | ||
'' | ''mandatory'' | ||
|| | || Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. | ||
|} | |} | ||
Zeile 455: | Zeile 489: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$timestamp </code>''' | ||
|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) <br> | |||
Bsp: <code>1457201868</code> | |||
|} | |} | ||
== Readings / Events == | |||
=== | === readingsBeginUpdate === | ||
< | :<syntaxhighlight lang="perl"> | ||
readingsBeginUpdate($hash); | |||
</ | </syntaxhighlight> | ||
Die Funktion | Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können. | ||
Parameter: | Parameter: | ||
Zeile 473: | Zeile 511: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$hash</code>''' | | style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen | ||
|| Die Hash-Referenz der Definition, wo Readings geupdatet | |||
|} | |} | ||
=== readingsBulkUpdate === | |||
<ul><syntaxhighlight lang="perl"> | |||
$rv = readingsBulkUpdate($hash, $reading, $value); | |||
<ul>< | $rv = readingsBulkUpdate($hash, $reading, $value, $changed); | ||
$rv = | </syntaxhighlight></ul> | ||
</ | Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. | ||
Die Funktion | |||
Parameter: | Parameter: | ||
Zeile 500: | Zeile 530: | ||
''mandatory'' | ''mandatory'' | ||
|| Die Hash-Referenz der Definition, wo | || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$reading</code>''' | | style="vertical-align:top" | '''<code>$reading</code>''' | ||
Zeile 512: | Zeile 542: | ||
|| Der Wert, welchen das Reading annehmen soll | || Der Wert, welchen das Reading annehmen soll | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$changed</code>''' | ||
'' | ''optional'' | ||
|| Flag, ob | || Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...) | ||
|} | |} | ||
Zeile 526: | Zeile 556: | ||
|} | |} | ||
=== readingsBulkUpdateIfChanged === | |||
<ul><syntaxhighlight lang="perl"> | |||
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value); | |||
<ul>< | $rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed); | ||
$ | </syntaxhighlight></ul> | ||
$ | Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt. | ||
</ | |||
Die Funktion | |||
Parameter: | Parameter: | ||
Zeile 542: | Zeile 569: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$reading</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Name des Readings, welches geupdatet werden soll | ||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' | |||
''mandatory'' | |||
|| Der Wert, welchen das Reading annehmen soll | |||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$changed</code>''' | ||
''optional'' | ''optional'' | ||
|| | || Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...) | ||
|} | |} | ||
Zeile 564: | Zeile 595: | ||
! Rückgabewert !! Bedeutung | ! Rückgabewert !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben. | ||
|} | |} | ||
== | === readingsEndUpdate === | ||
<ul><syntaxhighlight lang="perl"> | |||
readingsEndUpdate($hash, $do_trigger); | |||
<ul><syntaxhighlight lang="perl"> | |||
</syntaxhighlight></ul> | </syntaxhighlight></ul> | ||
Die Funktion | Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert. | ||
Parameter: | Parameter: | ||
Zeile 581: | Zeile 610: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Definition, wo Readings geupdatet wurden. | ||
|- | |- | ||
| '''<code>$ | | style="vertical-align:top" | '''<code>$do_trigger</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt. | ||
|} | |} | ||
=== readingsSingleUpdate === | |||
<ul><syntaxhighlight lang="perl"> | |||
<ul>< | $rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger); | ||
</syntaxhighlight></ul> | |||
</ | Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen. | ||
</ul> | |||
Die Funktion | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter!! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$reading</code>''' | ||
'' | ''mandatory'' | ||
|| Der | || Name des Readings, welches geupdatet werden soll | ||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' | |||
''mandatory'' | |||
|| Der Wert, welchen das Reading annehmen soll | |||
|- | |||
| style="vertical-align:top" | '''<code>$do_trigger</code>''' | |||
''mandatory'' | |||
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt. | |||
|} | |} | ||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. | |||
|} | |||
=== readingsDelete === | |||
<ul><syntaxhighlight lang="perl"> | |||
<ul>< | readingsDelete($hash, $reading); | ||
</ | </syntaxhighlight></ul> | ||
</ul> | Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>. | ||
Die Funktion | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter!! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$hash</code>''' | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Die Hash-Referenz der Definition, | || Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll | ||
|- | |||
| style="vertical-align:top" | '''<code>$reading</code>''' | |||
''mandatory'' | |||
|| Name des Readings, welches gelöscht werden soll | |||
|} | |} | ||
== | === DoTrigger === | ||
<ul><syntaxhighlight lang="perl"> | <ul><syntaxhighlight lang="perl"> | ||
$ret = DoTrigger($name, $new_state); | |||
$ret = DoTrigger($name, $new_state, $no_replace); | |||
</syntaxhighlight> | </syntaxhighlight></ul> | ||
</ul> | Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt). | ||
Die Funktion | |||
Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden. | |||
Parameter: | Parameter: | ||
Zeile 668: | Zeile 700: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Name der Definition deren Events durchgeführt werden sollen. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$new_state</code>''' | ||
'' | ''mandatory'' | ||
|| | || Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist. | ||
|- | |||
| style="vertical-align:top" | '''<code>$no_replace</code>''' | |||
''optional'' | |||
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>). | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert !! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben. | ||
|} | |} | ||
=== deviceEvents === | |||
<ul><syntaxhighlight lang="perl"> | |||
$events = deviceEvents($hash, $with_state); | |||
</syntaxhighlight></ul> | |||
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln. | |||
$ | |||
</ | |||
Die Funktion | |||
Parameter: | Parameter: | ||
Zeile 702: | Zeile 737: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen. | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$with_state</code>''' | ||
| '''<code>$ | |||
''mandatory<br>can be <code>undef</code>'' | ''mandatory<br>can be <code>undef</code>'' | ||
|| | || Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll. | ||
|} | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert !! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>. | ||
Bsp. (mit <code>$with_state = 0</code>): | |||
<ul> | |||
<syntaxhighlight lang="perl"> | |||
[ | |||
"humidity: 84", | |||
"T: 10.5 H: 84", | |||
"temperature: 10.5" | |||
] | |||
</syntaxhighlight></ul> | |||
Bsp. (mit <code>$with_state = 1</code>): | |||
<ul> | |||
<syntaxhighlight lang="perl"> | |||
[ | |||
"humidity: 84", | |||
"state: T: 10.5 H: 84", | |||
"temperature: 10.5" | |||
] | |||
</syntaxhighlight></ul> | |||
|} | |} | ||
=== notifyRegexpChanged === | |||
= | <ul><syntaxhighlight lang="perl"> | ||
notifyRegexpChanged($hash, $event_regexp, $disableNotifyFn); | |||
</syntaxhighlight></ul> | |||
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen. | |||
Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann. | |||
'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).''' Ansonsten kann der Eintrag in <code>$hash->{NOTIFYDEV}</code> über ''setNotifyDev()'' erfolgen. | |||
</ | |||
Parameter: | Parameter: | ||
Zeile 740: | Zeile 794: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde. | ||
|- | |- | ||
| '''<code>$ | | style="vertical-align:top" | '''<code>$event_regexp</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]]) | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$disableNotifyFn</code>''' | ||
''optional'' | |||
|| Wahrheitswert, wenn wahr, wird die NotifyFn() für diese Modulinstanz deaktiviert. | |||
|} | |} | ||
=== setNotifyDev === | |||
<ul><syntaxhighlight lang="perl"> | |||
setNotifyDev($hash, $devspec); | |||
</syntaxhighlight></ul> | |||
Die Funktion setNotifyDev() setzt für <code>$hash</code> einen Eintrag in <code>$hash->{NOTIFYDEV}</code> auf $devspec (ohne die vorgenannten Einschränkungen bei notifyRegexpChanged()) und veranlasst einen Neuaufbau der allgemeinen Filterstruktur. | |||
</ | |||
Die Funktion | |||
Parameter: | Parameter: | ||
Zeile 779: | Zeile 824: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Hash-Referenz der Definition, für welche der neue/geänderte ''NOTIFYDEV''-Eintrag gesetzt werden soll. | ||
|- | |- | ||
| '''<code>$ | | style="vertical-align:top" | '''<code>$devspec</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die ''devspec'' zur Ermittlung der zu überwachenden Geräte, welche für <code>$hash</code> gesetzt werden soll (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]]) | ||
|} | |} | ||
=== setDisableNotifyFn === | |||
($hash, 1) | |||
<ul><syntaxhighlight lang="perl"> | |||
setDisableNotifyFn($hash, $doit); | |||
</syntaxhighlight></ul> | |||
Die Funktion setDisableNotifyFn() setzt für <code>$hash</code> einen Eintrag in <code>$hash->{disableNotifyFn}</code> bzw. entfernt diesen Schlüssel und veranlasst einen Neuaufbau der allgemeinen Filterstruktur für NOTIFYDEV. | |||
Parameter: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Parameter !! Bedeutung | ||
|- | |||
| style="vertical-align:top" | '''<code>$hash</code>''' | |||
''mandatory'' | |||
|| Hash-Referenz der Definition, für welche der ''disableNotifyFn''-Eintrag gesetzt bzw. gelöscht werden soll. | |||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$doit</code>''' | ||
''mandatory'' | |||
|| Wahrheitswert. Wenn wahr, wird der Eintrag gesetzt, diese Instanz erhält dann keine Aufrufe der ''NotifyFn()'' mehr. | |||
|} | |} | ||
=== goodReadingName === | |||
== | <ul><syntaxhighlight lang="perl"> | ||
$valid = goodReadingName($name); | |||
</syntaxhighlight> | |||
</ul> | |||
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen: | |||
* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein) | |||
* Zahlen (0-9) | |||
* Punkt <code>.</code> | |||
* Unterstrich <code>_</code> | |||
* Bindestrich <code>-</code> | |||
* Schrägstrich <code>/</code> | |||
Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht. | |||
Parameter: | Parameter: | ||
Zeile 817: | Zeile 882: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$name</code>''' | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Readingname, welcher geprüft werden soll. | ||
|} | |} | ||
Zeile 838: | Zeile 893: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist. | ||
Folgende Werte sind möglich: | |||
0 - Readingname enthält unzulässige Zeichen<br> | |||
1 - Readingname besteht aus zulässigen Zeichen | |||
|} | |} | ||
=== makeReadingName === | |||
<ul><syntaxhighlight lang="perl"> | |||
$validName = makeReadingName($name); | |||
</syntaxhighlight> | |||
$ | </ul> | ||
</ | Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind. | ||
Die Funktion | |||
Parameter: | Parameter: | ||
Zeile 854: | Zeile 913: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$name</code>''' | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Readingname, welcher geprüft werden soll. | ||
|} | |} | ||
Zeile 876: | Zeile 924: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt. | ||
|} | |} | ||
== zweistufige Modulkommunikation == | |||
=== | === AssignIoPort === | ||
<ul><syntaxhighlight lang="perl"> | |||
AssignIoPort($hash); | |||
AssignIoPort($hash, $proposedName); | |||
</syntaxhighlight></ul> | |||
Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise: | |||
# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt. | |||
$ | # Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt. | ||
</ | # Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt. | ||
Parameter: | In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt. | ||
{| class="wikitable" | |||
Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert. | |||
Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
| | | Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$proposedName</code>''' | ||
'' | ''optional'' | ||
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann. | |||
|} | |} | ||
=== Dispatch === | |||
<ul><syntaxhighlight lang="perl"> | |||
$found = Dispatch($hash, $message); | |||
$found = Dispatch($hash, $message, $additional_values, $no_unknown); | |||
</syntaxhighlight></ul> | |||
Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird. | |||
Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.). | |||
Die Funktion | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |||
| style="vertical-align:top" | '''<code>$hash</code>''' | |||
''mandatory'' | |||
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte. | |||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$message</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | | Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen. | ||
|- | |||
| style="vertical-align:top" | '''<code>$additional_values</code>''' | |||
''optional<br>can be <code>undef</code>'' | |||
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein. | |||
|- | |||
| style="vertical-align:top" | '''<code>$no_unknown</code>''' | |||
''optional<br>can be <code>undef</code>'' | |||
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird <u>kein</u> zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und <u>kein</u> entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren. | |||
|} | |} | ||
Rückgabewerte: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert !! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$found </code>''' | ||
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben. | |||
|} | |} | ||
=== IOWrite === | |||
== | <ul><syntaxhighlight lang="perl"> | ||
$ret = IOWrite($hash, @arguments); | |||
</syntaxhighlight></ul> | |||
Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren. | |||
Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter. | |||
Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben. | |||
$ | |||
</ | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | | Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte. | ||
|- | |||
| style="vertical-align:top" | '''<code>@arguments</code>''' | |||
''mandatory'' | |||
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren. | |||
|} | |} | ||
Rückgabewerte: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabewert !! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$ret</code>''' | ||
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat. | |||
|} | |} | ||
== Timer == | |||
=== | === InternalTimer=== | ||
<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg); | |||
$timestamp | InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone); | ||
</ | </syntaxhighlight></ul> | ||
Die Funktion | Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt. | ||
Parameter: | Parameter: | ||
Zeile 983: | Zeile 1.061: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$timestamp</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten) | ||
| | |- | ||
| '''<code>$functionName</code>''' | |||
''mandatory'' | |||
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus") | |||
|- | |- | ||
| '''<code>$arg</code>''' | |||
''mandatory'' | |||
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash). | |||
|- | |- | ||
| '''<code>$waitIfInitNotDone</code>''' | |||
''optional'' | |||
|| | |||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!''' | |||
Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden. | |||
Standardwert: 0 | |||
|} | |||
=== | === RemoveInternalTimer === | ||
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg); | |||
RemoveInternalTimer($arg, $functionName); | |||
</ | </syntaxhighlight> | ||
Die Funktion | </ul> | ||
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken. | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$arg</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht. | ||
| | |- | ||
| style="vertical-align:top" | '''<code>$functionName</code>''' | |||
''optional'' | |||
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll. | |||
|} | |||
=== SetExtensionsCancel === | |||
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash); | |||
</ | </syntaxhighlight> | ||
</ul> | |||
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird. | |||
Parameter: | Parameter: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$hash</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Hash-Referenz der Definition, durch die der Timer angelegt wurde. | ||
|} | |} | ||
== Definitionen == | |||
== | === devspec2array === | ||
<ul><syntaxhighlight lang="perl"> | <ul><syntaxhighlight lang="perl"> | ||
@list = devspec2array($devspec); | |||
($ | @list = devspec2array($devspec, $client_hash); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</ul> | </ul> | ||
Die Funktion | Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen. | ||
Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen. | |||
Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück. | |||
Parameter: | Parameter: | ||
Zeile 1.058: | Zeile 1.149: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$devspec</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Die Device-Specification zum Suchen nach Definitions-Namen. | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$client_hash</code>''' | ||
'' | ''optional'' | ||
|| | || Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>). | ||
<code> | |||
|} | |} | ||
Zeile 1.077: | Zeile 1.165: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben. | ||
|} | |} | ||
=== goodDeviceName === | |||
<ul><syntaxhighlight lang="perl"> | |||
$valid = goodDeviceName($name); | |||
</syntaxhighlight> | |||
</ul> | |||
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen: | |||
* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein) | |||
* Zahlen (0-9) | |||
* Punkt <code>.</code> | |||
* Unterstrich <code>_</code> | |||
Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht. | |||
Parameter: | Parameter: | ||
Zeile 1.096: | Zeile 1.188: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Definitionsname, welcher geprüft werden soll. | ||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist. | ||
Folgende Werte sind möglich: | |||
0 - Definitionsname enthält unzulässige Zeichen<br> | |||
| | 1 - Definitionsname besteht aus zulässigen Zeichen | ||
< | |} | ||
=== makeDeviceName === | |||
<ul><syntaxhighlight lang="perl"> | |||
$validName = makeDeviceName($name); | |||
</syntaxhighlight> | |||
</ul> | |||
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |- | ||
| style="vertical-align:top" | '''<code> | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Der Definitionsname, welcher geprüft werden soll. | ||
|} | |} | ||
Zeile 1.120: | Zeile 1.230: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt. | ||
|} | |} | ||
== Daten abfragen/auslesen == | |||
=== | === ReadingsVal === | ||
:<syntaxhighlight lang="perl">$ | :<syntaxhighlight lang="perl"> | ||
Die Funktion | $value = ReadingsVal($name, $reading, $default); | ||
</syntaxhighlight> | |||
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. | |||
Parameter: | Parameter: | ||
Zeile 1.136: | Zeile 1.247: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll. | ||
|- | |- | ||
| | | '''<code>$reading</code>''' | ||
''mandatory'' | |||
|| Der Name des Readings welcher ausgelesen werden soll. | |||
|- | |||
| '''<code>$default</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | ''mandatory<br>can be <code>undef</code>'' | ||
|| | || Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. | ||
|- | |||
|} | |} | ||
Zeile 1.154: | Zeile 1.269: | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert. | ||
|} | |} | ||
=== ReadingsTimestamp=== | |||
:<syntaxhighlight lang="perl"> | |||
$timestamp = ReadingsTimestamp($name, $reading, $default); | |||
:<syntaxhighlight lang="perl">($ | </syntaxhighlight> | ||
Die Funktion | Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. | ||
Parameter: | Parameter: | ||
Zeile 1.168: | Zeile 1.284: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll. | ||
| | |- | ||
| '''<code>$reading</code>''' | |||
Rückgabewert: | ''mandatory'' | ||
{| class="wikitable" | || Der Name des Readings für welches der Zeitstempel ausgelesen werden soll. | ||
|- | |||
| '''<code>$default</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. | |||
|- | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |- | ||
! Rückgabe!! Bedeutung | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| | | style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format | ||
<code>2016-02-16 19:34:24</code> | |||
|} | |} | ||
=== ReadingsAge=== | |||
== | :<syntaxhighlight lang="perl"> | ||
$seconds = ReadingsAge($name, $reading, $default); | |||
</syntaxhighlight> | |||
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. | |||
=== | ==== Parameter ==== | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll. | ||
|- | |||
| '''<code>$reading</code>''' | |||
''mandatory'' | |||
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll. | |||
|- | |- | ||
| '''<code>$default</code>''' | |||
''mandatory'' | ''mandatory<br>can be <code>undef</code>'' | ||
|| | || Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. | ||
|- | |||
|} | |} | ||
==== Rückgabewert ==== | |||
=== | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind | ||
|} | |||
=== ReadingsNum === | |||
:<syntaxhighlight lang="perl"> | |||
$value = ReadingsNum($name, $reading, $default, $round); | |||
</syntaxhighlight> | |||
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabewert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung. | |||
==== Beispiele ==== | |||
<syntaxhighlight lang="perl" line="1"> | |||
# Device foo, Reading bar, Wert "123.45 °C" | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert)); | |||
# = 123.45 | |||
ReadingsNum(q(foo), q(baz), q(Kein Wert)); | |||
# = "Kein Wert" | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), 0); | |||
# = 123 | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), 1); | |||
# = 123.5 | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5); | |||
# = 123.45000 | |||
# Device foo, Reading bar, Wert "123 °C" | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5); | |||
# = 123.00000 | |||
</syntaxhighlight> | |||
</ | |||
Parameter | ==== Parameter ==== | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| | || Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll. | ||
| | |- | ||
| style="vertical-align:top" | '''<code>$reading</code>''' | |||
''mandatory'' | |||
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$default</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält. | |||
|- | |||
|'''<code>$round</code>''' | |||
''optional'' | |||
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet. | |||
|} | |||
==== Rückgabewert ==== | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte. | |||
|} | |||
==== Fallstricke ==== | |||
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1"> | |||
# Device foo, Reading bar, Wert "123.45 °C" | |||
# Lese aus dem Reading baz, nicht bar, wird fehlschlagen | |||
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) { | |||
say q(Wert ist 123.5); | |||
} | |||
# Argument "Kein Wert" isn't numeric in numeric eq (==) | |||
</syntaxhighlight><code>$round</code> wird direkt, d.h. ohne Validierung, in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight lang="perl" line="1"> | |||
# Device foo, Reading bar, Wert "123.45 °C" | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p}); | |||
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f | |||
ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo)); | |||
# = 123oof | |||
</syntaxhighlight> | |||
== | === AttrVal === | ||
:<syntaxhighlight lang="perl"> | :<syntaxhighlight lang="perl"> | ||
$ | $value = AttrVal($name, $attribute, $default); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Die Funktion | Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben. | ||
Parameter: | Parameter: | ||
Zeile 1.284: | Zeile 1.444: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$name</code>''' | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | |||
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$attribute</code>''' | |||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Name des Attributs, dessen Wert ausgelesen werden soll. | ||
|- | |||
| style="vertical-align:top" | '''<code>$default</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert. | |||
|- | |||
|} | |} | ||
Rückgabewert: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert. | ||
|} | |} | ||
=== InternalVal === | |||
=== | |||
:<syntaxhighlight lang="perl"> | :<syntaxhighlight lang="perl"> | ||
$ | $value = InternalVal($name, $internal, $default); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Die Funktion | Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben. | ||
Parameter: | Parameter: | ||
Zeile 1.318: | Zeile 1.481: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$name</code>''' | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | |||
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$internal</code>''' | |||
''mandatory'' | ''mandatory'' | ||
|| Der | || Der Name des Internals, dessen Wert ausgelesen werden soll. | ||
|- | |||
| style="vertical-align:top" | '''<code>$default</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert. | |||
|} | |} | ||
Rückgabewert: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert. | ||
|} | |} | ||
=== Value=== | |||
=== | |||
:<syntaxhighlight lang="perl"> | :<syntaxhighlight lang="perl"> | ||
$ | $value = Value($name); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Die Funktion | Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben. | ||
Parameter: | Parameter: | ||
Zeile 1.353: | Zeile 1.520: | ||
''mandatory'' | ''mandatory'' | ||
|| Der Definitions-Name | || Der Definitions-Name aus dem der Status ausgelesen werden soll. | ||
|} | |} | ||
Rückgabewert: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition | ||
|} | |} | ||
=== OldValue=== | |||
=== | |||
:<syntaxhighlight lang="perl"> | :<syntaxhighlight lang="perl"> | ||
$ | $value = OldValue($name); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Die Funktion | Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben. | ||
Parameter: | Parameter: | ||
Zeile 1.382: | Zeile 1.543: | ||
! Parameter !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$name</code>''' | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | ''mandatory'' | ||
|| Der Definitions-Name | || Der Definitions-Name aus dem der Status ausgelesen werden soll. | ||
|} | |} | ||
Rückgabewert: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Rückgabe!! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition | ||
|} | |||
=== OldTimestamp=== | |||
:<syntaxhighlight lang="perl"> | |||
$timestamp = OldTimestamp($name); | |||
</syntaxhighlight> | |||
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben. | |||
Parameter: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! | ! Parameter !! Bedeutung | ||
|- | |- | ||
| style="vertical-align:top" | '''<code>$ | | style="vertical-align:top" | '''<code>$name</code>''' | ||
''mandatory'' | |||
|| Der Definitions-Name aus dem der Status ausgelesen werden soll. | |||
|} | |} | ||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format | |||
<code>2016-02-16 19:34:24</code> | |||
|} | |||
== Attribute in anderen Definitionen bereitstellen == | |||
=== | === addToAttrList=== | ||
:<syntaxhighlight lang="perl"> | |||
:< | addToAttrList($attrib); | ||
$ | </syntaxhighlight> | ||
</ | Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden. | ||
Die Funktion | |||
Parameter: | |||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Rückgabewert !! Bedeutung | ! Parameter !! Bedeutung | ||
|- | |||
| style="vertical-align:top" | '''<code>$attrib</code>''' | |||
''mandatory'' | |||
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll. | |||
|} | |||
=== addToDevAttrList === | |||
:<syntaxhighlight lang="perl"> | |||
addToDevAttrList($name, $attrib); | |||
</syntaxhighlight> | |||
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$attrib</code>''' | |||
''mandatory'' | |||
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll. | |||
|} | |||
== Daten dauerhaft schreiben/lesen == | |||
=== FileRead === | |||
<ul><syntaxhighlight lang="perl"> | |||
($error, @content) = FileRead($filename); | |||
($error, @content) = FileRead($param); | |||
</syntaxhighlight> | |||
</ul> | |||
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$filename</code>''' | |||
''mandatory'' | |||
|| Der Dateisystempfad der Datei die eingelesen werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$param</code>''' | |||
''mandatory'' | |||
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden: | |||
<code>{ FileName => $filename, ForceType => "file" }</code> | |||
Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei. | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring). | |||
|- | |||
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code> | |||
|} | |||
=== FileDelete === | |||
<ul><syntaxhighlight lang="perl"> | |||
$error = FileDelete($filename); | |||
$error = FileDelete($param); | |||
</syntaxhighlight> | |||
</ul> | |||
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$filename</code>''' | |||
''mandatory'' | |||
|| Der Dateisystempfad der Datei die gelöscht werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$param</code>''' | |||
''mandatory'' | |||
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden: | |||
<code>{ FileName => $filename, ForceType => "file" }</code> | |||
Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei. | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>. | |||
|} | |||
=== FileWrite === | |||
<ul><syntaxhighlight lang="perl"> | |||
$error = FileWrite($filename, @content); | |||
$error = FileWrite($param, @content); | |||
</syntaxhighlight></ul> | |||
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$filename</code>''' | |||
''mandatory'' | |||
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$param</code>''' | |||
''mandatory'' | |||
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden: | |||
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code> | |||
Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen. | |||
|- | |||
| style="vertical-align:top" | '''<code>@content</code>''' | |||
''mandatory'' | |||
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile). | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> | |||
|} | |||
=== setKeyValue === | |||
:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight> | |||
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden. | |||
'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$key</code>''' | |||
''mandatory'' | |||
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten. | |||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten. | |||
Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht. | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> | |||
|} | |||
=== getKeyValue === | |||
:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight> | |||
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$key</code>''' | |||
''mandatory'' | |||
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden. | |||
|} | |||
Rückgabewert: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabe!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> | |||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code> | |||
|} | |||
== Logging == | |||
=== Log === | |||
<syntaxhighlight lang="perl"> | |||
Log($verbose, $message); | |||
</syntaxhighlight> | |||
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$verbose</code>''' | |||
''mandatory'' | |||
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll. | |||
Ganzzahl zwischen 0 und 5 | |||
|- | |||
| style="vertical-align:top" | '''<code>$message</code>''' | |||
''mandatory'' | |||
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. | |||
|} | |||
=== Log3 === | |||
<syntaxhighlight lang="perl"> | |||
Log3($name, $verbose, $message); | |||
</syntaxhighlight> | |||
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft. | |||
Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft. | |||
|- | |||
| style="vertical-align:top" | '''<code>$verbose</code>''' | |||
''mandatory'' | |||
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll. | |||
Ganzzahl zwischen 0 und 5 | |||
|- | |||
| style="vertical-align:top" | '''<code>$message</code>''' | |||
''mandatory'' | |||
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. | |||
|} | |||
=== Debug === | |||
<syntaxhighlight lang="perl"> | |||
Debug($message); | |||
</syntaxhighlight> | |||
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf: | |||
<syntaxhighlight lang="perl"> | |||
Log(1, "DEBUG>".$message); | |||
</syntaxhighlight> | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$message</code>''' | |||
''mandatory'' | |||
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. | |||
|} | |||
== Status-Abfragen == | |||
=== IsDevice === | |||
:<syntaxhighlight lang="perl"> | |||
$status = IsDevice($name); | |||
$status = IsDevice($name, $type); | |||
</syntaxhighlight> | |||
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$type</code>''' | |||
''optional'' | |||
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert: | |||
0 - Definition existiert nicht<br> | |||
1 - Definition existiert<br> | |||
Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen. | |||
|} | |||
=== IsDisabled === | |||
:<syntaxhighlight lang="perl"> | |||
$status = IsDisabled($name); | |||
</syntaxhighlight> | |||
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitions-Name welcher geprüft werden soll. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich: | |||
0 - Definition ist aktiv<br> | |||
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert<br> | |||
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert<br> | |||
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>. | |||
|} | |||
=== IsDummy === | |||
:<syntaxhighlight lang="perl"> | |||
$status = IsDummy($name); | |||
</syntaxhighlight> | |||
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitions-Name welcher geprüft werden soll. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich: | |||
0 - Definition ist aktiv<br> | |||
1 - Definition ist im Dummy-Modus<br> | |||
|} | |||
=== IsIgnored === | |||
:<syntaxhighlight lang="perl"> | |||
$status = IsIgnored($name); | |||
</syntaxhighlight> | |||
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitions-Name welcher geprüft werden soll. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich: | |||
0 - Definition ist aktiv<br> | |||
1 - Definition wird ignoriert<br> | |||
|} | |||
=== IsIoDummy === | |||
:<syntaxhighlight lang="perl"> | |||
$status = IsIoDummy($name); | |||
</syntaxhighlight> | |||
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitions-Name, dessen IO-Device geprüft werden soll. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich: | |||
0 - IO-Device der Definition ist aktiv<br> | |||
1 - IO-Device der Definition ist im Dummy-Modus<br> | |||
|} | |||
== Sicherheit == | |||
=== Authenticate === | |||
:<syntaxhighlight lang="perl"> | |||
$result = Authenticate($client, $argument); | |||
</syntaxhighlight> | |||
TBD | |||
=== Authorized === | |||
:<syntaxhighlight lang="perl"> | |||
$result = Authorized($client_hash, $type, $arg); | |||
</syntaxhighlight> | |||
Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben. | |||
Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt. | |||
Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit. | |||
Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$client_hash</code>''' | |||
''mandatory'' | |||
|| Der Client-Hash, welcher einen Vorgang durchführen möchte. | |||
|- | |||
| style="vertical-align:top" | '''<code>$type</code>''' | |||
''mandatory'' | |||
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden:<br> | |||
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe) | |||
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM | |||
Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann. | |||
|- | |||
| style="vertical-align:top" | '''<code>$arg</code>''' | |||
''mandatory'' | |||
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] | |||
Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$result</code>''' | |||
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist. | |||
* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden. | |||
* <code>1</code> - Vorgang ist authorisiert. | |||
|} | |||
== Modulfunktionen ausführen == | |||
=== CallFn === | |||
<ul><syntaxhighlight lang="perl"> | |||
$ret = CallFn($name, $function_name, @args); | |||
@ret = CallFn($name, $function_name, @args); | |||
</syntaxhighlight></ul> | |||
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert. | |||
Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$function_name</code>''' | |||
''mandatory'' | |||
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde. | |||
Bsp: | |||
* <code>"SetFn"</code> | |||
* <code>"DbLog_splitFn"</code> | |||
* <code>"CopyFn"</code> | |||
|- | |||
| style="vertical-align:top" | '''<code>@args</code>''' | |||
''mandatory'' | |||
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext). | |||
Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben. | |||
|} | |||
=== CallInstanceFn === | |||
<ul><syntaxhighlight lang="perl"> | |||
$ret = CallInstanceFn($name, $function_name, @args); | |||
@ret = CallInstanceFn($name, $function_name, @args); | |||
</syntaxhighlight></ul> | |||
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert. | |||
Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen. | |||
Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll. | |||
|- | |||
| style="vertical-align:top" | '''<code>$function_name</code>''' | |||
''mandatory'' | |||
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde. | |||
Bsp: | |||
* <code>"DbLog_splitFn"</code> | |||
|- | |||
| style="vertical-align:top" | '''<code>@args</code>''' | |||
''mandatory'' | |||
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext). | |||
Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben. | |||
|} | |||
== Sonstiges == | |||
=== configDBUsed === | |||
:<syntaxhighlight lang="perl"> | |||
$status = configDBUsed(); | |||
</syntaxhighlight> | |||
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter. | |||
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird. | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich:<br> | |||
0 - configDB wird nicht verwendet<br> | |||
1 - configDB wird verwendet | |||
|} | |||
=== computeClientArray === | |||
<nowiki>#</nowiki> compute the list of defined logical modules for a physical module<syntaxhighlight lang="perl"> | |||
$clientArray = computeClientArray($definitionHash, $moduleName); | |||
</syntaxhighlight>Wenn im übergebenen $definitionHash der Wert {ClientsKeepOrder}=1 gesetzt ist, dann wird der ClientArray in der Reihenfolge und mit den Namen aufgebaut, wie diese im phyischen Modul hinterlegt sind. | |||
Der Wert {ClientsKeepOrder}=0 bewirkt, dass eine Sortierung gemäß der Modulreihenfolge vorgenommen wird und dass Module auch über die Angabe einer Regex ausgewählt werden können. | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$definitionHash</code>''' | |||
''mandatory'' | |||
|| Die Hash-Referenz der Gerätedefinition, welche an diese Funktion übergeben wird | |||
|- | |||
| style="vertical-align:top" | '''<code>$moduleName</code>''' | |||
''mandatory'' | |||
|| Die Angabe eines Modulnamnes, aus welchem der Wert {Clients} verwendet wird, sollte dieser Wert in der Gerätedefinition nicht hinterlegt sein | |||
|} | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$clientArray</code>''' || Liefert auf Basis des übergebenen hashes einer Moduldefinition und des übergebenen Modulnamens einen $clientarray zurück | |||
|} | |||
=== getUniqueId === | |||
:<syntaxhighlight lang="perl"> | |||
$uniqueID = getUniqueId(); | |||
</syntaxhighlight> | |||
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren. | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |- | ||
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist. | | style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist. | ||
|} | |||
=== toJSON === | |||
:<syntaxhighlight lang="perl"> | |||
$jsonString = toJSON($value); | |||
</syntaxhighlight> | |||
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$value</code>''' | |||
''mandatory<br>can be <code>undef</code>'' | |||
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll. | |||
|} | |||
Rückgabewerte: | |||
{| class="wikitable" | |||
|- | |||
! Rückgabewert !! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt. | |||
|} | |||
=== CancelDelayedShutdown === | |||
:<syntaxhighlight lang="perl"> | |||
CancelDelayedShutdown($name); | |||
</syntaxhighlight> | |||
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann. | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$name</code>''' | |||
''mandatory'' | |||
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll | |||
|} | |} | ||
[[Kategorie:Development]] | [[Kategorie:Development]] |
Aktuelle Version vom 26. Januar 2022, 12:29 Uhr
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the FHEM forum!
Diese Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
- Wiederverwendbare Routinen leichter identifizieren zu können
- Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
- Aufwand zu verringern
- Bei Änderungen auch betroffene Module leichter identifizieren zu können
Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.
FHEM-Befehlsausführung
AnalyzeCommand
$error = AnalyzeCommand($client_hash, $cmd);
AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando $cmd ausführen darf (Vorgangs-Typ: cmd ). Der Definition-Hash muss in SNAME den zum Attribut validFor (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert undef übergeben wird, erfolgt keine Prüfung.
|
$cmd
mandatory |
Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). Beispiel:
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$error
|
Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef zurückgegeben.
|
AnalyzeCommandChain
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
$errors = AnalyzeCommandChain ($client_hash, $cmds)
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos $cmds ausführen darf (Vorgangs-Typ: cmd ).Der Definition-Hash muss in SNAME den zum Attribut validFor (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert undef übergeben wird, erfolgt keine Prüfung.
|
$cmds
mandatory |
Kommandokette, welche ausgeführt werden soll, durch ; getrennt.Beispiel:
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$errors
|
Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef zurückgegeben.
|
AnalyzePerlCommand
$errors = AnalyzePerlCommand ($client_hash, $cmds);
AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen). Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.
Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.
Sind EvalSpecials() definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden. Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos $cmds ausführen darf (Vorgangs-Typ: cmd ).Der Definition-Hash muss in SNAME den zum Attribut validFor (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert undef übergeben wird, erfolgt keine Prüfung.
|
$cmds
mandatory |
Perl-Kommando(s), welche ausgeführt werden sollen, durch ; getrennt.Beispiel:
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$errors
|
Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef zurückgegeben.
|
EvalSpecials
$final_cmd = EvalSpecials($cmd, %specials);
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von %specials
in $cmd
gesucht und durch die entsprechenden Werte aus %specials
ersetzt.
Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut featurelevel
) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.
In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.
Parameter:
Parameter | Bedeutung |
---|---|
$cmd
mandatory |
Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.
Bsp: |
%specials
mandatory |
Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (_ ) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.
Bspw: |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$final_cmd
|
Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.
Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen. In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet. |
parseParams
my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define (DefineFn), get (GetFn) und set (SetFn) verwenden. Beim Parsen werden erkannt:
- einfache, durch den Separator getrennte, Zeichenfolgen
- benannte Parameter der Form
<name>=<wert>
- Werte können in einfache (
'
) oder doppelte ("
) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten - Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
- Werte können in einfache (
- in
{...}
eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.
In der Modul X_Initialize
Routine lässt sich mit $hash->{parseParams} = 1;
festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.
Parameter:
Parameter | Bedeutung |
---|---|
$cmd
mandatory |
Die Argumente des Kommandos als String oder als Array-Referenz. |
$separator
optional |
Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.
Standardwert: ' ' (Leerzeichen) |
$joiner
optional |
|
$keyvalueseparator
optional |
Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '=' |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$a
|
Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält. |
$h
|
Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!) |
Beispiel: Die Zeile
set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }
wird in die folgenden Elemente geparst:
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];
# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
asyncOutput
asyncOutput($client_hash, $message);
Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.
Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine AsyncOutputFn bereitstellen. Dies wird aktuell nur in FHEMWEB und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf$client_hash->{canAsyncOutput}
prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der SetFn und GetFn unter $hash->{CL} bereitgestellt.
|
$message
mandatory |
Die Daten als Zeichenkette, welche ausgegeben werden sollen. |
SetExtensions
$error = SetExtensions($hash, $usage_list, @set_args);
Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen on
und off
. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der Set-Funktion verwendet.
Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur Set-Funktion.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Gerätedefinition, für die gerade die Set-Funktion ausgeführt wird. |
$usage_list
mandatory |
Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix unknown command [...] choose one of . Diese Liste muss mind. die Befehle on und off enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.
Beispiel:
|
@set_args
mandatory |
Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser $hash ). Dieses Array entspricht einem Array aus den Parametern ($name, $cmd, @args) aus dem Artikel zur Set-Funktion
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$error
|
Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden. |
Siehe auch: SetExtensionsCancel
Time / Timestamp
FmtDateTimeRFC1123
$timestampGMT = FmtDateTimeRFC1123($timestamp);
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$timestamp
mandatory |
Zeitangabe wie sie von der time() Funktion zurückgegeben wirdBsp: |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestampGMT
|
Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet.
|
FmtDateTime
$timestamp = FmtDateTime($time);
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.
Parameter:
Parameter | Bedeutung |
---|---|
$time
mandatory |
Zeitangabe wie sie von der time() Funktion zurückgegeben wird.Bsp: |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel in lokaler Zeitzone im Format
|
TimeNow
$timestamp = TimeNow();
Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format
Benutzt die Funktion |
fhemTimeGm
$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion gmtime()
erzeugt wird, in einen UNIX-Timestamp um.
Parameter:
Parameter | Bedeutung |
---|---|
$sec
mandatory |
Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. |
$min
mandatory |
Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. |
$hour
mandatory |
Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. |
$mday
mandatory |
Die Tag-Komponente als Ganzzahl zwischen 1 und 31. |
$month
mandatory |
Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11. |
$year
mandatory |
Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) Bsp: |
fhemTimeLocal
$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion localtime()
erzeugt wird in einen UNIX-Timestamp um.
Parameter:
Parameter | Bedeutung |
---|---|
$sec
mandatory |
Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. |
$min
mandatory |
Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. |
$hour
mandatory |
Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. |
$mday
mandatory |
Die Tag-Komponente als Ganzzahl zwischen 1 und 31. |
$month
mandatory |
Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11. |
$year
mandatory |
Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) Bsp: |
Readings / Events
readingsBeginUpdate
readingsBeginUpdate($hash);
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash $hash
auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.
Parameter:
Parameter | Bedeutung |
---|---|
$hash |
Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen |
readingsBulkUpdate
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition $hash
durch. Dabei wird das Readings $reading
auf den Wert $value
gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen |
$reading
mandatory |
Name des Readings, welches geupdatet werden soll |
$value
mandatory |
Der Wert, welchen das Reading annehmen soll |
$changed
optional |
Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: 1 ). Oder ob definitiv kein Event erzeugt werden soll (Wert: 0 ). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von $hash entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$rv |
Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. |
readingsBulkUpdateIfChanged
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition $hash
durch, sofern sich der neue Wert $value
gegenüber dem vorherigen Wert verändert. Dabei wird das Readings $reading
auf den Wert $value
gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen |
$reading
mandatory |
Name des Readings, welches geupdatet werden soll |
$value
mandatory |
Der Wert, welchen das Reading annehmen soll |
$changed
optional |
Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: 1 ). Oder ob definitiv kein Event erzeugt werden soll (Wert: 0 ). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von $hash entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$rv |
Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird undef zurückgegeben.
|
readingsEndUpdate
readingsEndUpdate($hash, $do_trigger);
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition $hash
. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: userReadings
), sowie die Erzeugung des STATE aufgrund des Attributs stateFormat
durchgeführt. Sofern $do_trigger
gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo Readings geupdatet wurden. |
$do_trigger
mandatory |
Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: 1 ). Wenn dieses Flag den Wert 0 oder undef besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|
readingsSingleUpdate
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll |
$reading
mandatory |
Name des Readings, welches geupdatet werden soll |
$value
mandatory |
Der Wert, welchen das Reading annehmen soll |
$do_trigger
mandatory |
Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: 1 , Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert 0 oder undef besitzt, wird kein Event erzeugt.
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$rv |
Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. |
readingsDelete
readingsDelete($hash, $reading);
Die Funktion readingsDelete() löscht das Reading $reading
aus der Definition $hash
.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll |
$reading
mandatory |
Name des Readings, welches gelöscht werden soll |
DoTrigger
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
Die Funktion DoTrigger() triggert alle angesammelten Events in $hash->{CHANGED}
sowie zusätzlich das Event $new_state
für die Definition $name
und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in $hash->{CHANGED}
keine zu bearbeitenden Änderungen enthalten sind, wird lediglich $new_state
getriggert (sofern gesetzt).
Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Name der Definition deren Events durchgeführt werden sollen. |
$new_state
mandatory |
Das Event welches zusätzlich zu bereits anstehenden Events aus $hash->{CHANGED} getriggert werden soll. Wenn dieser Wert undef ist, werden nur alle Events aus $hash->{CHANGED} bearbeitet, sofern $hash->{CHANGED} gefüllt ist.
|
$no_replace
optional |
Optionales Flag, welches die Ersetzung von Events durch das Attribut eventMap verhindert (Wert: 1 ).
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$ret |
Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben. |
deviceEvents
$events = deviceEvents($hash, $with_state);
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition $hash
als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der NotifyFn vorgesehen, um die anstehenden Events zu ermitteln.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen. |
$with_state
mandatory |
Flag, ob das Reading state mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: 1 ) oder nur der Wert ohne dem vorangestellten Readingnamen "state: " (Wert: 0 ) in der Event-Liste angezeigt werden soll.
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$events |
Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert undef .
Bsp. (mit [
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
Bsp. (mit [
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
|
notifyRegexpChanged
notifyRegexpChanged($hash, $event_regexp, $disableNotifyFn);
Die Funktion notifyRegexpChanged() setzt für $hash
einen passenden Eintrag in $hash->{NOTIFYDEV}
basierend auf dem regulären Ausdruck $event_regexp
, welcher üblicherweise in der Define-Funktion als Argument übergeben wird. Dadurch wird die Notify-Funktion nur für Events der entsprechenden Gerätedefinition aufgerufen.
Je nach dem, wie $event_regexp
formuliert ist, setzt notifyRegexpChanged() einen Eintrag in $hash->{NOTIFYDEV}
. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.
Diese Funktion kann nur verwendet werden, wenn $event_regexp
auf <Definitionsnamen>
bzw. <Definitionsnamen>:<Event>
matcht (Event Regexp-Syntax aus notify). Ansonsten kann der Eintrag in $hash->{NOTIFYDEV}
über setNotifyDev() erfolgen.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde. |
$event_regexp
mandatory |
Die Regexp, welche für $hash gesetzt wurde (i.d.R via Define-Funktion)
|
$disableNotifyFn
optional |
Wahrheitswert, wenn wahr, wird die NotifyFn() für diese Modulinstanz deaktiviert. |
setNotifyDev
setNotifyDev($hash, $devspec);
Die Funktion setNotifyDev() setzt für $hash
einen Eintrag in $hash->{NOTIFYDEV}
auf $devspec (ohne die vorgenannten Einschränkungen bei notifyRegexpChanged()) und veranlasst einen Neuaufbau der allgemeinen Filterstruktur.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Hash-Referenz der Definition, für welche der neue/geänderte NOTIFYDEV-Eintrag gesetzt werden soll. |
$devspec
mandatory |
Die devspec zur Ermittlung der zu überwachenden Geräte, welche für $hash gesetzt werden soll (i.d.R via Define-Funktion)
|
setDisableNotifyFn
($hash, 1)
setDisableNotifyFn($hash, $doit);
Die Funktion setDisableNotifyFn() setzt für $hash
einen Eintrag in $hash->{disableNotifyFn}
bzw. entfernt diesen Schlüssel und veranlasst einen Neuaufbau der allgemeinen Filterstruktur für NOTIFYDEV.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Hash-Referenz der Definition, für welche der disableNotifyFn-Eintrag gesetzt bzw. gelöscht werden soll. |
$doit
mandatory |
Wahrheitswert. Wenn wahr, wird der Eintrag gesetzt, diese Instanz erhält dann keine Aufrufe der NotifyFn() mehr. |
goodReadingName
$valid = goodReadingName($name);
Die Funktion goodReadingName() prüft, ob der Readingname $name
ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:
- Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
- Zahlen (0-9)
- Punkt
.
- Unterstrich
_
- Bindestrich
-
- Schrägstrich
/
Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert 1
zurück, andernfalls 0
. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Readingname, welcher geprüft werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$return |
Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich: 0 - Readingname enthält unzulässige Zeichen |
makeReadingName
$validName = makeReadingName($name);
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname $name
alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Readingname, welcher geprüft werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$validName |
Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt. |
zweistufige Modulkommunikation
AssignIoPort
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:
- Sofern
$proposedName
angegeben ist und der Gerätename existiert und nicht disabled ist (Attributedisable
auf 1 gesetzt), wird$proposedName
als IO-Gerät ausgewählt. - Sofern der Nutzer über das Attribut
IODev
einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt. - Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von
$hash
als IO-Gerät annehmen (via Client-Liste). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.
In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von IOWrite() eine Fehlermeldung im Logfile erzeugt.
Das gefundene IO-Gerät wird mittels Hash-Referenz unter $hash->{IODev}
gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.
Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der Define-Funktion aufgerufen werden, da sonst kein Senden von Daten via IOWrite() möglich ist. Für den Empfang ist $hash->{IODev}
ohne Bedeutung.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll. |
$proposedName
optional |
Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann. |
Dispatch
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
Die Funktion Dispatch() versucht die Nachricht $message
, welche die Definition mit dem Hash $hash
erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in $additional_values
mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut addvaltrigger
in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag $no_unknown
kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes Event erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.
Die Funktion prüft dabei alle Module aus der Client-Liste, ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via Fingerprint-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via Parse-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte. |
$message
mandatory |
Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen. |
$additional_values
optional |
Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <IO-Gerätname>_<Schlüssel>: <Wert> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|
$no_unknown
optional |
Flag. Wenn gesetzt (Wert: 1 ), wird kein zugehöriges Modul basierend auf der Match-Liste nachgeladen und kein entsprechendes Event erzeugt, sollte die Nachricht $message nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert 0 oder undef besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der Match-Liste nachgeladen und ein entsprechendes Event erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$found
|
Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird undef zurückgegeben.
|
IOWrite
$ret = IOWrite($hash, @arguments);
Die Funktion IOWrite() übergibt die Daten @arguments
der logischen Definition $hash
an das ausgewählte IO-Gerät indem es die Write-Funktion mit den Daten @arguments
aufruft. In @arguments
ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der Write-Funktion des entsprechenden physikalischen Moduls harmonieren.
Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels AssignIoPort() zugewiesen werden. Dieser Aufruf wird üblicherweise in der Define-Funktion oder der Notify-Funktion (Trigger auf global:INITIALIZED
bzw. global:REREADCFG
) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.
Der Inhalt von $hash
wird nicht an die Write-Funktion übergeben. Sollte man $hash
des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man $hash>
mit in @arguments
übergeben.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte. |
@arguments
mandatory |
Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$ret
|
Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat. |
Timer
InternalTimer
InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion $functionName
wird dabei zum Zeitpunkt $timestamp
mit dem Parameter $arg
ausgeführt.
Parameter:
Parameter | Bedeutung |
---|---|
$timestamp
mandatory |
Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: gettimeofday() + 30 um in 30 Sekunden etwas zu starten)
|
$functionName
mandatory |
Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus") |
$arg
mandatory |
Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash). |
$waitIfInitNotDone
optional |
ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden! Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt Standardwert: 0 |
RemoveInternalTimer
RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter $arg
gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion $functionName
weiter einschränken.
Parameter:
Parameter | Bedeutung |
---|---|
$arg
mandatory |
Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht. |
$functionName
optional |
Der Funktionsname der zusätzlich zu $arg gesucht werden soll.
|
SetExtensionsCancel
SetExtensionsCancel($hash);
Die Funktion SetExtensionsCancel löscht möglicherweise noch anstehenden Timer, der durch ein on-for-timer, off-for-timer, ... über die SetExtensions angelegt wurde. Sollte in der SetFn aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, durch die der Timer angelegt wurde. |
Definitionen
devspec2array
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification $devspec
matchen.
Sollte keine Definition auf die übergebene Spezifikation passen, so wird $devspec
als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in %defs
zu prüfen.
Die genaue Syntax einer Device-Specification ist in der commandref/devspec erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$devspec
mandatory |
Die Device-Specification zum Suchen nach Definitions-Namen. |
$client_hash
optional |
Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: devicename ).
|
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
@list |
Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird $devspec unverändert zurückgegeben. Wenn $client_hash gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird "" (Leerstring) zurückgegeben.
|
goodDeviceName
$valid = goodDeviceName($name);
Die Funktion goodDeviceName() prüft, ob der Definitionsname $name
ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:
- Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
- Zahlen (0-9)
- Punkt
.
- Unterstrich
_
Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert 1
zurück, andernfalls 0
. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitionsname, welcher geprüft werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$return |
Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich: 0 - Definitionsname enthält unzulässige Zeichen |
makeDeviceName
$validName = makeDeviceName($name);
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen $name
alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitionsname, welcher geprüft werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$validName |
Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt. |
Daten abfragen/auslesen
ReadingsVal
$value = ReadingsVal($name, $reading, $default);
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings $reading
der Definition $name
zurück. Sollte das gewünschte Reading nicht existieren, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings welcher ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Readings oder $default , wenn es nicht existiert.
|
ReadingsTimestamp
$timestamp = ReadingsTimestamp($name, $reading, $default);
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings $reading
der Definition $name
zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings für welches der Zeitstempel ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$timestamp |
Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
|
ReadingsAge
$seconds = ReadingsAge($name, $reading, $default);
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings $reading
der Definition $name
zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird $default
zurückgegeben.
Parameter
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert
Rückgabe | Bedeutung |
---|---|
$seconds |
Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind |
ReadingsNum
$value = ReadingsNum($name, $reading, $default, $round);
Die Funktion ReadingsNum
extrahiert den numerischen Teil des Readings $reading
der Definition $name
und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird $default
zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls $default
zurückgegeben. Es ist möglich, den Rückgabewert durch Angabe von $round
auf $round
Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion round
; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.
Beispiele
# Device foo, Reading bar, Wert "123.45 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45
ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123
ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000
# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
Parameter
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält. |
$round
optional |
Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf $round Anzahl Stellen gerundet. |
Rückgabewert
Rückgabe | Bedeutung |
---|---|
$value |
Wert des gewünschten Readings oder $default , wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|
Fallstricke
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als $default
kein numerischer Wert oder undef
übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.
# Device foo, Reading bar, Wert "123.45 °C"
# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}
# Argument "Kein Wert" isn't numeric in numeric eq (==)
$round
wird direkt, d.h. ohne Validierung, in den format string in round
übernommen und ausgewertet.
# Device foo, Reading bar, Wert "123.45 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f
ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo));
# = 123oof
AttrVal
$value = AttrVal($name, $attribute, $default);
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut $attribute
der Definition $name
zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll. |
$attribute
mandatory |
Der Name des Attributs, dessen Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Attributs oder $default , wenn es nicht existiert.
|
InternalVal
$value = InternalVal($name, $internal, $default);
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals $internal
der Definition $name
zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll. |
$internal
mandatory |
Der Name des Internals, dessen Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Internal oder $default , wenn es nicht existiert.
|
Value
$value = Value($name);
Die Funktion Value() gibt den aktuellen Status von Definition $name
zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Status der gewünschten Definition |
OldValue
$value = OldValue($name);
Die Funktion OldValue() gibt den Status der Definition $name
zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
vorheriger Status der gewünschten Definition |
OldTimestamp
$timestamp = OldTimestamp($name);
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition $name
als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$timestamp |
Zeitstempel in lokaler Zeitzone im Format
|
Attribute in anderen Definitionen bereitstellen
addToAttrList
addToAttrList($attrib);
Die Funktion addToAttrList() fügt das Attribut mit dem Namen $attrib
zu dem Attribut userattr
der Definition global
hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.
Parameter:
Parameter | Bedeutung |
---|---|
$attrib
mandatory |
Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll. |
addToDevAttrList
addToDevAttrList($name, $attrib);
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen $attrib
zu dem Attribut userattr
der Definition $name
hinzu. Damit kann dieses Attribut in der Definition $name
verwendet und gesetzt werden.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll. |
$attrib
mandatory |
Der Name des Attributs, welches für die Definition $name verfügbar gemacht werden soll.
|
Daten dauerhaft schreiben/lesen
FileRead
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
Die Funktion FileRead() liest den Inhalt der Datei $filename
ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash $param
gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.
Parameter:
Parameter | Bedeutung |
---|---|
$filename
mandatory |
Der Dateisystempfad der Datei die eingelesen werden soll. |
$param
mandatory |
Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
Die Variable |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält $error den Wert undef oder "" (Leerstring).
|
@content |
Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert undef
|
FileDelete
$error = FileDelete($filename);
$error = FileDelete($param);
Die Funktion FileDelete() löscht die Datei $filename
. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash $param
gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.
Parameter:
Parameter | Bedeutung |
---|---|
$filename
mandatory |
Der Dateisystempfad der Datei die gelöscht werden soll. |
$param
mandatory |
Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
Die Variable |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält $error den Wert undef .
|
FileWrite
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
Die Funktion FileWrite() schreibt den übergebenen Inhalt @content
in die Datei $filename
. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash $param
gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.
Parameter:
Parameter | Bedeutung |
---|---|
$filename
mandatory |
Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll. |
$param
mandatory |
Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
Die Variable |
@content
mandatory |
Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile). |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält $error den Wert undef
|
setKeyValue
$error = setKeyValue($key, $value)
Die Funktion setKeyValue() speichert die Daten $value
unter dem Schlüssel $key
ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in $value
enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.
ACHTUNG: Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.
Parameter:
Parameter | Bedeutung |
---|---|
$key
mandatory |
Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten. |
$value
mandatory |
Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.
Wenn |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält $error den Wert undef
|
getKeyValue
($error, $value) = getKeyValue($key)
Die Funktion getKeyValue() gibt Daten, welche zuvor per setKeyValue()
gespeichert wurden, zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$key
mandatory |
Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält $error den Wert undef
|
$value |
Die Daten, welche unter dem gegebenen Schlüssel $key hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt $value den Wert undef
|
Logging
Log
Log($verbose, $message);
Die Funktion Log() schreibt die Meldung $message
in das FHEM-Logfile, sofern $verbose
kleiner gleich dem globalen Attribut verbose
ist. Wenn $verbose
größer ist als das globale Attribut verbose
, wird die Meldung nicht geloggt.
Parameter:
Parameter | Bedeutung |
---|---|
$verbose
mandatory |
Der Verbose-Level unter dem die Nachricht $message geloggt werden soll.
Ganzzahl zwischen 0 und 5 |
$message
mandatory |
Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Log3
Log3($name, $verbose, $message);
Die Funktion Log3() schreibt die Meldung $message
in das FHEM-Logfile, sofern $verbose
kleiner gleich dem Attribut verbose
der Definition $name
ist. Wenn das Attribut verbose
in der Definition $name
nicht gesetzt ist, wird gegen das globale Attribut verbose
geprüft.
Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition wogegen geprüft werden soll. Wenn $name in FHEM nicht existiert, oder den Wert undef besitzt, wird der Parameter $verbose gegen das globale Attribut verbose geprüft.
|
$verbose
mandatory |
Der Verbose-Level unter dem die Nachricht $message geloggt werden soll.
Ganzzahl zwischen 0 und 5 |
$message
mandatory |
Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Debug
Debug($message);
Die Funktion Debug() schreibt die Meldung $message
mit dem Präfix DEBUG>
in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
Log(1, "DEBUG>".$message);
Parameter:
Parameter | Bedeutung |
---|---|
$message
mandatory |
Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Status-Abfragen
IsDevice
$status = IsDevice($name); $status = IsDevice($name, $type);
Die Funktion IsDevice() prüft, ob die Definition $name
existiert. Optional kann man prüfen, ob die Definition $name
dem Modultyp $type
entspricht.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher auf Vorhandensein geprüft werden soll. |
$type
optional |
Ein regulärer Ausdruck der gegen den Modulnamen ($hash->{TYPE} ) der Definition $name geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit ^ und $ umschlossen wird.
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Das Ergebnis, ob eine solche Definition existiert:
0 - Definition existiert nicht Wenn nur |
IsDisabled
$status = IsDisabled($name);
Die Funktion IsDisabled() prüft, ob die Definition $name
aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: inactive
). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer 0
zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert 0
zurück.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsDummy
$status = IsDummy($name);
Die Funktion IsDummy() prüft, ob die Definition $name
in den Dummy-Modus versetzt wurde (Attribut: dummy
). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert 1
zurück, andernfalls 0
.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsIgnored
$status = IsIgnored($name);
Die Funktion IsIgnored() prüft, ob die Definition $name
durch den User ignoriert wird (Attribut: ignore
). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert 1
zurück, andernfalls 0
.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsIoDummy
$status = IsIoDummy($name);
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition $name
in den Dummy-Modus versetzt wurde (Attribut: dummy
). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert 1
zurück, andernfalls 0
.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name, dessen IO-Device geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:
0 - IO-Device der Definition ist aktiv |
Sicherheit
Authenticate
$result = Authenticate($client, $argument);
TBD
Authorized
$result = Authorized($client_hash, $type, $arg);
Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash $client_hash
die Aktion $type
/$arg
ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion X_Authorize() bereitstellen. Die beiden Argumente $type
/$arg
werden dabei 1:1 an die Authorize-Funktion der jeweiligen Module übergeben.
Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert 0
zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert 1
zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von 1
. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.
Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul allowed stellt dabei die entsprechende Modulfunktion X_Authorize() bereit.
Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Client-Hash, welcher einen Vorgang durchführen möchte. |
$type
mandatory |
Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden:
Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit Authorize-Funktion gibt, welches diese Vorgänge verarbeiten kann. |
$arg
mandatory |
Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von $arg in Verbindung mit den bereits vorhandenen Vorgangstypen (cmd /devicename ) gibt es in der Beschreibung von $arg zur Modulfunktion X_Authorize()
Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit Authorize-Funktion gibt, welches diese Vorgänge verarbeiten kann. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$result
|
Ergebnis, ob der zu prüfende Vorgang authorisiert ist.
|
Modulfunktionen ausführen
CallFn
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
Die Funktion CallFn() ruft von der Definition $name
die im Modul registrierte Funktion $function_name
mit den Argumenten @args
auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von $name
gesucht. Entsprechende Funktionen werden im Rahmen der Initialize-Funktion beim Laden eines Moduls registriert.
Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird undef
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll. |
$function_name
mandatory |
Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von X_Initialize() im Modul-Hash registriert wurde.
Bsp:
|
@args
mandatory |
Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$ret / @ret |
Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).
Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur |
CallInstanceFn
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
Die Funktion CallInstanceFn() ist eine Erweiterung zu CallFn(). Die auszuführende Funktion $function_name
wird dabei zuerst in dem Definitions-Hash von $name
gesucht. Der Funktionsname muss dabei direkt in $hash
definiert sein (ähnlich wie beim Modul-Hash im Rahmen von X_Initialize()). Der Funktionsname kann in $hash
dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion $function_name
innerhalb des Definitions-Hash von $name
nicht existieren, wird CallFn() mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.
Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.
Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird undef
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll. |
$function_name
mandatory |
Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in $hash und, im Rahmen von X_Initialize(), im Modul-Hash registriert wurde.
Bsp:
|
@args
mandatory |
Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$ret / @ret |
Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).
Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur |
Sonstiges
configDBUsed
$status = configDBUsed();
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert 1
zurück. Die Funktion besitzt keinerlei Übergabeparameter.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Folgende Werte sind möglich: 0 - configDB wird nicht verwendet |
computeClientArray
# compute the list of defined logical modules for a physical module
$clientArray = computeClientArray($definitionHash, $moduleName);
Wenn im übergebenen $definitionHash der Wert {ClientsKeepOrder}=1 gesetzt ist, dann wird der ClientArray in der Reihenfolge und mit den Namen aufgebaut, wie diese im phyischen Modul hinterlegt sind.
Der Wert {ClientsKeepOrder}=0 bewirkt, dass eine Sortierung gemäß der Modulreihenfolge vorgenommen wird und dass Module auch über die Angabe einer Regex ausgewählt werden können.
Parameter | Bedeutung |
---|---|
$definitionHash
mandatory |
Die Hash-Referenz der Gerätedefinition, welche an diese Funktion übergeben wird |
$moduleName
mandatory |
Die Angabe eines Modulnamnes, aus welchem der Wert {Clients} verwendet wird, sollte dieser Wert in der Gerätedefinition nicht hinterlegt sein |
Rückgabewert | Bedeutung |
---|---|
$clientArray |
Liefert auf Basis des übergebenen hashes einer Moduldefinition und des übergebenen Modulnamens einen $clientarray zurück |
getUniqueId
$uniqueID = getUniqueId();
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$uniqueID |
Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist. |
toJSON
$jsonString = toJSON($value);
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument $value
kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$value
mandatory |
Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$jsonString |
Der JSON-String, welcher das Objekt samt Inhalt darstellt. |
CancelDelayedShutdown
CancelDelayedShutdown($name);
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten DelayedShutdown-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition $name
abgeschlossen sind und FHEM sich nun beenden kann.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll |