DevelopmentModuleAPI: Unterschied zwischen den Versionen

Aus FHEMWiki
(Anpassung von <source>-Tags nach <syntaxhighlight>)
(→‎Definitionen suchen: Umbenennen in "Definitionen", hinzufügen von goodDeviceName())
Zeile 958: Zeile 958:




== Definitionen suchen ==
== Definitionen ==


=== devspec2array ===
=== devspec2array ===
Zeile 997: Zeile 997:
|}
|}


=== 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:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''
''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}
Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
|  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
|}


== Daten abfragen/auslesen ==
== Daten abfragen/auslesen ==

Version vom 19. August 2017, 14:28 Uhr

X mark.svgBitte 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 FHEM-Forum angemerkt werden!
Please note: This list of functions is not official 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!

Dieses 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 identifiziern zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über einen 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
can be undef

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:

  • define dummy1 dummy
  • {Log3(undef, 1, "Hallo")}

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

$errors = AnalyzeCommandChain ($client_hash, $cmds);

AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.

Parameter:

Parameter Bedeutung
$client_hash

mandatory
can be undef

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:

  • define dummy1 dummy; list dummy1; {Log(3,"dummy created")}

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: set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}

%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: ("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2")

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);

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.
  • in {...} eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleichen 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)

Rückgabewerte:

Rückgabewert Bedeutung
$a Eine Referenz auf ein Array, dass 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:

  • "on off statusRequest"
  • "on:noArg off:noArg input:av1,av2,av3 volume"
@set_args

mandatory

Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser $hash). Dieses Array entspricht einen 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 wird

Bsp: 1457201868

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.

Sat, 05 Mar 2016 18:17:48 GMT


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: 1457201868

Rückgabewerte:

Rückgabe Bedeutung
$timestamp Zeitstempel in lokaler Zeitzone im Format

2016-02-16 19:34:24


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

2016-02-16 19:34:24

Benutzt die Funktion FmtDateTime()


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 als 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: 1457201868


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 als 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: 1457201868


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.


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
can be undef

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 $with_state = 0): 

    [ 
    "humidity: 84",
    "T: 10.5 H: 84",
    "temperature: 10.5"
]

Bsp. (mit $with_state = 1): 

    [ 
    "humidity: 84",
    "state: T: 10.5 H: 84",
    "temperature: 10.5"
]


notifyRegexpChanged

    notifyRegexpChanged($hash, $event_regexp);

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 (Regexp-Syntax aus notify.

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)


zweistufige Modulkommunikation

AssignIoPort

    AssignIoPort($hash);
AssignIoPort($hash, $proposedName);

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

  1. Sofern $proposedName angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute disable auf 1 gesetzt), wird $proposedName als IO-Gerät ausgewählt.
  2. Sofern der Nutzer über das Attribut IODev einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
  3. 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 passenden 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, $additional_values);

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. Dabei 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!).

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

mandatory
can be undef

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.

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 in dem 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 physikalishen 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 sein 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 $timestamp 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 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 global:INITIALIZED in der Notify-Funktion gewartet werden.

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 wem 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 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
1 - Definitionsname besteht aus zulässigen Zeichen

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-Namen aus dem das gewünschte Reading ausgelesen werden soll.
$reading

mandatory

Der Name des Readings welcher ausgelesen werden soll.
$default

mandatory
can be undef

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-Namen 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
can be undef

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

2016-02-16 19:34:24


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-Namen 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
can be undef

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

$number = ReadingsNum($name, $reading, $default);

Die Funktion ReadingsNum() extrahiert einen numerischen Wert aus dem Reading $reading der Definition $name und gibt diesen zurück. 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.

Parameter:

Parameter Bedeutung
$name

mandatory

Der Definitions-Namen aus dem ein numerischer 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
can be undef

Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.

Rückgabewert:

Rückgabe Bedeutung
$number Numerischer Wert des gewünschten Readings oder $default, wenn es nicht existiert.


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-Namen aus dem das gewünschte Attribut ausgelesen werden soll.
$attribute

mandatory

Der Name des Attributs, dessen Wert ausgelesen werden soll.
$default

mandatory
can be undef

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-Namen aus dem das gewünschte Internal ausgelesen werden soll.
$internal

mandatory

Der Name des Internals, dessen Wert ausgelesen werden soll.
$default

mandatory
can be undef

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 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-Namen 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-Namen aus dem der Status ausgelesen werden soll.

Rückgabewert:

Rückgabe Bedeutung
$value vorherige 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-Namen aus dem der Status ausgelesen werden soll.

Rückgabewert:

Rückgabe Bedeutung
$timestamp Zeitstempel in lokaler Zeitzone im Format

2016-02-16 19:34:24


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 wiefolgt übergeben werden:

{ FileName => $filename, ForceType => "file" }

Die Variable $filename enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.

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


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 wiefolgt übergeben werden:

{ FileName => $filename, ForceType => "file", NoNL => 0 }

Die Variable $filename enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert NoNL auf 1 setzen um kein Newline (\n) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.

@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 einen 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
can be undef

Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn $value den Wert undef besitzt, werden zuvor gespeicherte Daten gelöscht.

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
can be undef

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

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
1 - Definition ist durch das Attribut disable deaktiviert
2 - Definition ist durch das Attribut disabledForIntervals deaktiviert
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet $hash->{STATE} oder das Reading state der Definition besitzt den Wert inactive.


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
1 - Definition ist im Dummy-Modus


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
1 - Definition wird ignoriert


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
1 - IO-Device der Definition ist im Dummy-Modus


Sicherheit

Authenticate

$result = Authorized($client, $argument);

TBD

Authorize

$result = Authorized($client, $argument);

TBD


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:

  • "SetFn"
  • "DbLog_splitFn"
  • "CopyFn"
@args

mandatory

Ein oder mehrer Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden soll. 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 undef zurückgegeben.

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:

  • "DbLog_splitFn"
@args

mandatory

Ein oder mehrer Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden soll. 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 Defintion, als auch im zugrunde liegenden Modul nicht existieren, wird nur undef zurückgegeben.


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
1 - configDB wird verwendet


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
can be undef

Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalaren Wert, welcher in JSON zurückgeben werden soll.

Rückgabewerte:

Rückgabewert Bedeutung
$jsonString Der JSON-String, welcher das Objekt samt Inhalt darstellt.
Abgerufen von „http://wiki.fhem.de/w/index.php?title=DevelopmentModuleAPI&oldid=22258“