DevelopmentModuleAPI: Unterschied zwischen den Versionen
(→Datenabfrage-/auslesen: ReadingsNum, AttrVal hinzugefügt) |
|||
Zeile 293: | Zeile 293: | ||
* InternalVal | * InternalVal | ||
* <strike>ReadingsVal</strike> | * <strike>ReadingsVal</strike> | ||
* ReadingsNum | * <strike>ReadingsNum</strike> | ||
* <strike>ReadingsTimestamp</strike> | * <strike>ReadingsTimestamp</strike> | ||
* Value | * Value | ||
* OldValue | * OldValue | ||
* OldTimestamp | * OldTimestamp | ||
* AttrVal | * <strike>AttrVal</strike> | ||
* readingsBeginUpdate | * readingsBeginUpdate | ||
* readingsBulkUpdate | * readingsBulkUpdate |
Version vom 3. März 2016, 14:11 Uhr
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:
|
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:
|
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
|
Rückgabe | Bedeutung |
---|---|
$timestampGMT
|
Zeitstempel GMT (Greenwich Mean Time) wie er in RFC1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet.
|
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
|
TimeNow
$timestamp = TimeNow( )
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format
|
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. |
ReadingsNum
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 | Bedeutung |
---|---|
$name |
Der Definitions-Namen aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll. |
$reading |
Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll. |
$default |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
AttrVal
AttrVal($name, $attribute, $default)
Die Funktion AttrNum() 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 | Bedeutung |
---|---|
$name |
Der Definitions-Namen aus dem das gewünschte Attribut ausgelesen werden soll. |
$attribute |
Der Name des Attributs, dessen Wert ausgelesen werden soll. |
$default |
Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert. |
Fehlt noch
- Log3
- IsDisabled
- IsDummy
- IsIgnored
- IsIoDummy
InternalTimerRemoveInternalTimer- configDBUsed
- devspec2array
FmtTime- EvalSpecials
- DoTrigger
- InternalVal
ReadingsValReadingsNumReadingsTimestamp- Value
- OldValue
- OldTimestamp
AttrVal- readingsBeginUpdate
- readingsBulkUpdate
- readingsEndUpdate
- readingsSingleUpdate
- FileRead
- FileWrite
- getUniqueId
- getKeyValue
- setKeyValue
- Debug