DeclareAction/Event und EndOfList

Nach Anfrage durch NeuroomNet via GetActions meldet eine Komponente alle bekannten Aktionen und Ereignisse durch DeclareAction/Event zurück. Dabei erfolgt jede Meldung in einem gesonderten Paket und die Meldungen werden durch ein spezielles EndOfList Paket abgeschlossen. Es ist durchaus zulässig auch keine Aktionen und/oder Ereignisse zu melden, lediglich EndOfList ist immer zwingend erforderlich.

Aktion melden

{
    "command": "DeclareAction",
    "description": "Schaltet das Licht in der gesamten Halle aus.",
    "displayName": "Ausschalten",
    "id": "de.insynergie.lights-off",
    "parameters": [
        {
            "array": false,
            "description": "Verzögert die Ausführung zwischen den einzelnen Lampen.",
            "displayName": "Verzögerung",
            "id": "delay",
            "required": false,
            "type": "Float",
            "validation": "{min: 0, max: 5}"
        }
    ]
}

Codierung String: DeclareAction<TAB>id<TAB>de.insynergie.lights-off<TAB>displayName<TAB>Ausschalten<TAB>description<TAB>Schaltet das List in der gesamten Halle aus.<TAB>parameters<TAB>id<TAB>delay<TAB>required<TAB>false<TAB>array<TAB>false<TAB>description<TAB>Verzögert die Ausführung zwischen den einzelnen Lampen.<TAB>displayName<TAB>Verzögerung<TAB>type<TAB>Float<TAB>validation<TAB>{min: 0, max: 5}

Hinweis: Die Reihenfolge der Felder ist bis auf parameters egal, das immer als letztes kommen muss. Sind mehrere Parameter angegeben, so werden diese durch ein einzelnes <TAB> getrennt. Zudem ist darauf zu achten, dass keiner der Texte einen Tabulator enthält - das gilt natürlich insbesondere für die Beschreibungen und die Prüfregeln. In diesem Sinne wäre auch folgendes eine gültige Anmeldung in der Codierung String:

DeclareAction<TAB>id<TAB>off<TAB>parameters<TAB>id<TAB>p1<TAB>required<TAB>true<TAB>type<TAB>Float<TAB><TAB>id<TAB>p2<TAB>required<TAB>true<TAB>type<TAB>String

displayName, description und parameters sind optional. Die id der Aktion muss eindeutig unter allen Aktionen im NeuroomNet-Kontext sein. In größeren NeuroomNet-Installationen empfiehlt sich hier z.B., den Geräte- / Komponententyp mit einzubauen, um Eindeutigkeit zu garantieren (wie z.B. "de.insynergie.EnvironmentalSensorType0815.Activate").

Anmerkung: Es darf durchaus mehrere Komponenten geben, welche Aktionen mit demselben Aktionsnamen haben, aber es sollte sich dabei um dieselbe Aktion handeln (auf verschiedenen Komponenten, vom normalerweise selben Typ, ausgeführt). Technisch darf es nicht denselben Aktionsnamen geben mit verschiedenen Parametern, weil dies zur Laufzeit zu merkwürdigen Fehlern führen kann.

Für jeden Parameter in parameters sind array, description, displayName und validation optional. In der Liste darf jede id nur einmal vorkommen und bezeichnet den eindeutigen Namen des Parameters, so wir er auch bei der Ausführung über DoAction Pakete verwendet wird, die der Dienst an die Komponente meldet. Diese id des parameters muss nur eindeutig im Rahmen der jeweiligen Aktion sein.

Als elementare Datentypen type werden nur Int, Float, Boolean und String unterstützt. validation kann zu weiteren Einschränkungen der Werte für den Parameter eingesetzt werden, als Notation wird das Regelwerk der fastest-validator Bibliothek verwendet. Mit array können auch Felder auf Basis der elementaren Datentypen verwendet werden.

Ereignis melden

Analog zum Melden von Aktionen, nur dass hier command immer DeclareEvent sein muss. Die Komponente kann dann Ereignisse mit DoEvent Paketen an den Dienst melden.

Meldungen einer Art abschließen

{
    "command": "EndOfList"
}

Codierung String: EndOfList