Events subscription

Plugin can be subscribed for module events (zwave, core, network, …) using a subscriber_id = subscribe( script_name[, events_filter] ) method. When some module event happens, a subscribed script gets called with an appropriate event (or, which is the same, a plugin gets notified by this event) if this event passes specified events filter, if events filter omitted, a plugin will be notified about ALL module events. To block all events specify no filter rules: (events_filter = { rules = {} } or events_filter = { exclude = false, rules = {} })

A subscribe method returns an id (subscriber_id) which identifies a subscription created by the method call. This id can be used with set_set_subscription_filters() and unsubscribe() methods.

At this moment a subscriber_id equals to a name of an event handling script passed to a subscribe method, so it’s possible to use a script name as a subscriber_id argument for methods requiring it.

Change subscription events filter rules

It’s possible to change (add, modify, remove) subscription’s events filter rules using a set_subscription_filters( subscriber_id, filter_rules ) method. To specify a filter rule to modify/remove a rule id is used (it should be specified during filter rule creation within a subscribe() method). filter_rules is an array of filter rules.

To add a rule, specify its id(if this rule is going to be changed) and a rule body.

To modify a rule, specify its id and a new rule body.

To remove a rule, specify its id and set an event field to “” or {}.

Examples:

This example removes a filter rule with an id == “1”, modifies a rule with an id == “100500” and adds a new rule.

				
					[
  { 
    "id": "1",
    "event": ""
  },
  { 
    "id": "100500",
    "event": "the best event",
    "accepts": [
      {
        "id": 42
      }
    ]
  },
  { 
    "event": "event_1"
  },
]

Format of an events_filter:

				
					{
  "exclude": "bool",
  "rules": [
    {
      "id": "event_id",
      "event": "event_name",
      "accepts": [
        {
          "some_id": 42,
          "some_name": {}
        },
        {
          "some_stuff": "the best stuff"
        }
      ]
    },
    {
      "event": "event_name_2",
    },
    ...
  ]
}

fields	type	required	description
exclude	bool	–	event filter rules policy
rules	table(array)	+	table specifying event filter rules
rules[i].id	string	–	rule id (to change it in the future)
rules[i].event	string	+	event name to match
rules[i].accepts	table(array)	–	event parameters to match

An event filter rules policy specifies how to treat event filter rules:

exclude == true: pass only events NON-matching ANY event filter rules
exclude == false(default): pass only events matching ANY event filter rules

Event matches a rule if:

rules[i].event == event.event [ && ( rules[i].accepts[0].pair_1 == event.pair_1 && rules[i].accepts[0].pair_2 == event.pair_2 … && rules[i].accepts[0].pair_n == event.pair_n ) || ( rules[i].accepts[1].pair_1 == event.pair_1 && rules[i].accepts[1].pair_2 == event.pair_2 … && rules[i].accepts[1].pair_n == event.pair_n ) … || ( rules[i].accepts[n].pair_1 == event.pair_1 && rules[i].accepts[n].pair_2 == event.pair_2 … && rules[i].accepts[n].pair_n == event.pair_n ) ]

accepts[i].pair_1 == event.pair_1 if accepts[i].key_1 == event.key_1 && accepts[i].value_1 == event.value_1 || accepts[i].key_1 == event.key_1 && accepts[i].value_1 == any( event.value_1 )

Examples of event filter rules:

Pass only node_added and event_1 events:

				
					{
  "exclude": false,
  "rules": [
    {
      "event": "node_added",
    },
    {
      "event": "event_1",
    },
  ]
}

Pass only event_1 events if they have (id == 42 and name == “the best name ever”) or ( age == 100500 and city == any value ) event data, events which have some date alongside with mention early, will pass too.

				
					{
  "rules": [
    {
      "event": "event_1",
      "accepts": [
        {
          "id": 42,
          "name": "the best name ever"
        },
        {
          "age": 100500,
          "city": {}
        }
      ]
    }
  ]
}

Block only events event_1 and events_2:

				
					{
  "exclude": true,
  "rules": [
    {
      "event": "event_1",
    },
    {
      "event": "event_2",
    },
  ]
}

Block all events:

				
					{
  "exclude": false,
  "rules": []
}
  or
{
  "rules": []
}

Format of a generic event:

				
					{
  "event": "string",
  ...
}

fields	type	description
event	string	type of an event
…		data specific to the event

Example of a generic event:

				
					{
  "event": "the best event",
  "id": 42,
  "some_key": "some_value",
  "info": {
    "key_1": 100500,
    "key_2": "value_2"
  }
}