DevelopmentModuleAPI: Unterschied zwischen den Versionen

Aus FHEMWiki
(Hinzufügen von ReadingsVal() und ReadingsTimestamp())
Zeile 198: Zeile 198:
|-
|-
| style="vertical-align:top" | '''<code>$arg</code>''' || Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
| style="vertical-align:top" | '''<code>$arg</code>''' || Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|}
== Datenabfrage-/auslesen ==
=== ReadingsVal ===
<source lang="perl">
ReadingsVal($name, $reading, $default)
</source>
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.
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>''' || Der Definitions-Namen aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>''' || Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>''' || Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}
=== ReadingsTimestamp===
<source lang="perl">
ReadingsTimestamp($name, $reading, $default)
</source>
Die Funktion ReadingsTimestamp() gibt den UNIX-Timestamp 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.
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>''' || Der Definitions-Namen aus dem der Zeitstempe für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>''' || Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>''' || Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}
|}


Zeile 214: Zeile 255:
* DoTrigger
* DoTrigger
* InternalVal
* InternalVal
* ReadingsVal
* <strike>ReadingsVal</strike>
* ReadingsNum
* ReadingsNum
* ReadingsTimestamp
* <strike>ReadingsTimestamp</strike>
* Value
* Value
* OldValue
* OldValue

Version vom 3. März 2016, 14:01 Uhr


X mark.svgBitte beachten: letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im Fhem-Forum angemerkt (oder hier berichtigt) werden!
Please note: in the end it is always the Perl code itself that is relevant; please report errors and omissions in the fhem forum (or correct them here)!

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.


Command handling

AnalyzeCommand

AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in FHEMWEB im Kommandoeingabefeld enthalten.

AnalyzeCommand ($cl, $cmd)
Parameter Bedeutung
$cl

might be undef

Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
$cmd

mandatory

Kommandos, die ausgeführt werden sollen.

Beispiel:

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


AnalyzeCommandChain

AnalyzeCommandChain ermöglicht das Parsen und die Ausführung von FHEM-Befehlen, wie in FHEMWeb im Kommandoeingabefeld enthalten.

AnalyzeCommandChain ($cl, $cmds)
Parameter Bedeutung
$cl

might be undef

Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
$cmds

mandatory

Kommandos, das ausgeführt werden soll, durch ; getrennt.

Beispiel:

  • define dummy1 dummy; list dummy1


Diverse

ReplaceSetMagic

ReplaceSetMagic

($err, @result) = ReplaceSetMagic($hash, $nsplit, @elements)
Parameter Bedeutung
$hash

might be undef

Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
$nsplit

Zahl

Begrenzung für den Split des Ergebnisstrings nach erfolgter Ersetzung (siehe elements)
@elements

mandatory

Parameterarray mit Strings Die Elemente des übergebenen Arrays werden in einem String getrennt duch Leerzeichen zusammengefasst.


Rückgabe Bedeutung
$err Im Fehlerfall: Fehlermeldung sonst undef
@result Ergebnis der Ersetzung von Readings und Perl Aufrufen im Parameterarray. Die Elemente des übergebenen Arrays werden in einem String, getrennt durch Leerzeichen, zusammengefasst und im Rückgabewert wieder in ein Array (unter Berücksichtigung von nsplit als Begrenzung für den perl-Split-Aufruf) zerlegt.


Time / Timestamp

FmtDateTimeRFC1123

$timestampGMT = FmtDateTimeRFC1123($time)
Parameter Bedeutung
$time

might be undef

Zeitangabe wie sie von der time Funktion zurückgegeben wird

Mon, 15 Feb 2016 20:52:20 GMT


Rückgabe Bedeutung
$timestampGMT Zeitstempel GMT (Greenwich Mean Time) wie er in RFC1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet.

Mon, 15 Feb 2016 20:52:20 GMT


FmtDateTime

$timestamp = FmtDateTime($time)
Parameter Bedeutung
$time Zeitangabe wie sie von der time Funktion zurückgegeben wird


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

2016-02-16 19:34:24


TimeNow

$timestamp = TimeNow( )
Rückgabe Bedeutung
$timestamp Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format

2016-02-16 19:34:24
Benutzt FmtDateTime


Readings

Die verschiedenen Funktionen zu Readings sind hier beschrieben:

DevelopmentIntroduction und DevelopmentModuleIntro

Timer

InternalTimer

InternalTimer($timestamp, $functionName, $args)
InternalTimer($timestamp, $functionName, $args, $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 Bedeutung
$timestamp Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: gettimeofday() + 30 um in 30 Sekunden etwas zu starten)
$functionName Der Name der Funktion welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
$arg Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash.
$waitIfInitNotDone VORSICHT! NUR BENUTZEN WENN MAN ES WIRKLICH BENÖTIGT. Wenn dieser Wert auf 1 ist und die Funktion ausgeführt wird, während FHEM startet ($init_done == 0), dann wird InternalTimer direkt solange warten bis der angegebene Zeitpunkt erreicht ist, UND DIE FUNKION DIREKT AUSFÜHREN. Das bedeutet, dass InternalTimer() dann solange läuft, bis der Zeitpunkt erreicht ist und die angegebene Funktion ausgeführt wurde. (Standardwert: 0)

RemoveInternalTimer

RemoveInternalTimer($arg)

Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter $arg gescheduled sind.

Parameter Bedeutung
$arg Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.


Datenabfrage-/auslesen

ReadingsVal

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 Bedeutung
$name Der Definitions-Namen aus dem das gewünschte Reading ausgelesen werden soll.
$reading Der Name des Readings welcher ausgelesen werden soll.
$default Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.

ReadingsTimestamp

ReadingsTimestamp($name, $reading, $default)

Die Funktion ReadingsTimestamp() gibt den UNIX-Timestamp 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 Bedeutung
$name Der Definitions-Namen aus dem der Zeitstempe für das gewünschte Reading ausgelesen werden soll.
$reading Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
$default Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.

Fehlt noch

  • Log3
  • IsDisabled
  • IsDummy
  • IsIgnored
  • IsIoDummy
  • InternalTimer
  • RemoveInternalTimer
  • configDBUsed
  • devspec2array
  • FmtTime
  • EvalSpecials
  • DoTrigger
  • InternalVal
  • ReadingsVal
  • ReadingsNum
  • ReadingsTimestamp
  • Value
  • OldValue
  • OldTimestamp
  • AttrVal
  • readingsBeginUpdate
  • readingsBulkUpdate
  • readingsEndUpdate
  • readingsSingleUpdate
  • FileRead
  • FileWrite
  • getUniqueId
  • getKeyValue
  • setKeyValue
  • Debug