Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
EventEngine.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2009 Raritan Inc. All rights reserved.
4 */
5
6/**
7 * Event interface
8 *
9 */
10
11module event {
12
13 /**
14 * Helper that is used wherever key/value pairs are required.
15 *
16 * @note This interface was designed before IDL maps were supported.
17 */
18 structure KeyValue {
19 string key; ///< Key
20 string value; ///< Value
21 };
22
23 /**
24 * Event has a type:
25 * a STATE event indicates that a boolean state has been
26 * changed, i.e. asserted or deasserted
27 * a TRIGGER event is one that has no state assigned.
28 * conceptually it is asserted and deasserted at once.
29 * The id has multiple components that form a path into a hierarchy.
30 * The value ("asserted") indicates whether the state has become
31 * true (assertion) or false (deassertion). For events of type TRIGGER
32 * this will be true always.
33 */
34 structure Event {
35
36 /** Event type */
37 enumeration Type {
38 STATE, ///< State event
39 TRIGGER ///< Trigger event
40 };
41
42 Type type; ///< Event type
43 vector<string> id; ///< Event id vector
44 boolean asserted; ///< Assertion value
45 time timeStamp; ///< UNIX timestamp (UTC)
46 vector<KeyValue> context; ///< Context map
47 };
48
49 /**
50 * There is a single event engine instance reachable by a well known
51 * reference.
52 */
53 interface Engine {
54
55 /* Event registration and query */
56 /* ---------------------------- */
57
58 /**
59 * An event descriptor.
60 *
61 * In case eventDescType is LEAF then the descriptor refers to a
62 * 'real' event. In this case eventType is set and the entries vector
63 * is empty. Otherwise eventType is a don't care and the entries vector
64 * contains sub-entries. In case eventDescType is DYN_NODE then the
65 * dynNodeContext contains a key which is used to generate a dynamic
66 * node.
67 */
68 structure EventDesc {
69
70 /** Event descriptor type */
71 enumeration Type {
72 NODE, ///< Intermediate node
73 DYN_NODE, ///< Dynamic node
74 LEAF ///< Leaf node
75 };
76
77 Type eventDescType; ///< Event descriptor type
78 Event.Type eventType; ///< Event type
79 string dynNodeContext; ///< Dynamic node context
80 string idComp; ///< Event ID component
81 string name; ///< User-defined name
82 boolean hasSnmpTrap; ///< Whether an SNMP trap is defined for the event
83 vector<EventDesc> entries; ///< Child nodes
84 };
85
86 /**
87 * Query existing event descriptors.
88 *
89 * @return 0 if OK
90 * @return 1 if id was not found
91 */
92 int listEventDescs(in vector<string> eventIdPrefix,
93 out vector<EventDesc> eventDescs);
94
95
96 /* Action definition and query */
97 /* --------------------------- */
98
99 /**
100 * List all available action types. The action type is intentionally
101 * defined generically so that implementation can be extensible without
102 * changing interface.
103 */
104 vector<string> listActionTypes();
105
106 /**
107 * An action is a tuple of 'id' (unique within the scope of this event
108 * engine), 'name' which is unique as well and used by the GUI as user
109 * readable identificator, 'isSystem' which denotes the action as
110 * system action, 'type' which defines what it is, and an argument
111 * vector that vary depending on type and which is passed to the action.
112 * The 'isSystem' flag is readonly and if set marks the action as not
113 * deletable.
114 */
115 structure Action {
116 string id; ///< Action ID
117 string name; ///< User-defined name
118 boolean isSystem; ///< \c true for system-defined actions
119 string type; ///< Action type
120 vector<KeyValue> arguments; ///< Action argument map
121 };
122
123 /**
124 * Add a new action.
125 *
126 * The id and isSystem fields are ignored. The actions's id field is
127 * allocated automatically and returned in the actionId parameter.
128 *
129 * @return 0 if OK
130 * @return 1 if the name of the new action already exists
131 * @return 2 if generating the action id failed
132 * @return 3 if the maximum number of actions have been created
133 */
134 int addAction(in Action action, out string actionId);
135
136 /**
137 * Modify an action.
138 *
139 * @return 0 if OK
140 * @return 1 if the name of the new action already exists
141 * @return 2 if the action id does not exist
142 */
143 int modifyAction(in Action action);
144
145 /**
146 * Remove an action.
147 *
148 * @return 0 if OK
149 * @return 1 if id is unknown
150 * @return 2 if the action is not deletable
151 */
152 int deleteAction(in string actionId);
153
154 /**
155 * List all actions currently know to this event engine.
156 */
157 vector<Action> listActions();
158
159 /**
160 * Trigger an action.
161 *
162 * This is mainly used for test and debugging. The operation will
163 * block until the action has been performed or an error occurred.
164 * In the latter case errMsg will contain an error message. The
165 * context is passed to the actions.
166 *
167 * NOTE: Currently this function doesn't block!
168 *
169 * @return 0 if OK
170 * @return 1 if id is unknown
171 * @return 2 if no actor was found for the action
172 * @return 3 if performing the action failed, errmsg will be set
173 */
174 int triggerAction(in string actionId, out string errMsg,
175 in vector<KeyValue> context);
176
177 /**
178 * Test an action.
179 *
180 * This is similar to {@link triggerAction}, except that an action
181 * that is not yet saved can be passed in. Therefore this method
182 * can be used for testing actions to be newly created. The
183 * operation will block until the action has been performed or an
184 * error occurred. In the latter case errMsg will contain an error
185 * message. The context is passed to the actions.
186 *
187 * NOTE: Currently this function doesn't block!
188 *
189 * @return 0 if OK
190 * @return 1 if the action name is invalid
191 * @return 2 if no actor was found for the action
192 * @return 3 if performing the action failed, errmsg will be set
193 */
194 int testAction(in Action action, out string errMsg,
195 in vector<KeyValue> context);
196
197
198 /* Rule Definition and query */
199 /* ------------------------- */
200
201 /**
202 * Condition is a logical combination of multiple events. Normally you
203 * should use STATE events in logical conditions. In case a TRIGGER
204 * event is part of a condition or logical operation it will per
205 * default be interpreted as deasserted. The TRIGGER will evaluate as
206 * asserted if that exact event was raised and is matched against the
207 * event rules. In some sense the 'assertion state' of the TRIGGER is
208 * true only at the moment the Event exists and set to false again once
209 * it passed.
210 */
211 structure Condition {
212
213 /** logical operation to be applied over all conditions and event */
214 enumeration Op {
215 AND, ///< Logical And
216 OR, ///< Logical Or
217 XOR ///< Exclusive Or
218 };
219
220 /** the match type how to match the event assertion state */
221 enumeration MatchType {
222 ASSERTED, ///< Match if the event is asserted
223 DEASSERTED, ///< Match if the event is deasserted
224 BOTH ///< Match both (for trigger events)
225 };
226
227 boolean negate; ///< Negate the result
228 Op operation; ///< Logical operation to be applied
229 MatchType matchType; ///< Match type
230 vector<string> eventId; ///< Event ID
231 vector<Condition> conditions; ///< List of subordinate conditions
232 };
233
234 /**
235 * A Rule binds an action to a condition.
236 *
237 * The 'id' is an unique identification within the scope of this event
238 * engine. The 'name' is unique as well and used by the GUI as user
239 * readable identificator. The flag 'isAutoRearm' determines whether
240 * actions are triggered again after condition reoccurres. The
241 * 'hasMatched' flag is true if the condition was true once and the rule
242 * is not rearmed yet. The 'isSystem' flag is readonly and if set marks
243 * the action as not deletable. The 'actionIds' are the actions to
244 * perform if the rule evaluates to true. The arguments are passed to
245 * the actions.
246 */
247 structure Rule {
248 string id; ///< Rule ID
249 string name; ///< User-defined name
250 boolean isSystem; ///< \c true for system-defined rules
251 boolean isEnabled; ///< \c true if the rule is enabled
252 boolean isAutoRearm; ///< \c true for auto-rearming rules
253 boolean hasMatched; ///< \c true if the rule has matched since being armed
254 Condition condition; ///< Trigger condition
255 vector<string> actionIds; ///< List of action IDs
256 vector<KeyValue> arguments; ///< Argument map
257 };
258
259 /**
260 * Add a new rule.
261 *
262 * The id, hasMatched and isSystem fields are ignored. The rule's
263 * id field is allocated automatically and returned in the the ruleId
264 * parameter.
265 *
266 * @return 0 if OK
267 * @return 1 if the name of the new rule already exists
268 * @return 2 if generating the rule id failed
269 * @return 3 if the rule condition contains an invalid event id
270 * @return 4 if the maximum number of rules have been created
271 * @return 5 if the maximum number of actions per rule is exceeded
272 */
273 int addRule(in Rule rule, out string ruleId);
274
275 /**
276 * Modify a rule.
277 *
278 * The hasMatched and isSystem fields are ignored.
279 *
280 * @return 0 if OK
281 * @return 1 if the name of the new rule already exists
282 * @return 2 if the rule id does not exist
283 * @return 3 if the rule condition contains an invalid event id
284 * @return 4 if the maximum number of actions per rule is exceeded
285 */
286 int modifyRule(in Rule rule);
287
288 /**
289 * Enable a rule.
290 *
291 * An enabled rule will be evaluated when processing events.
292 *
293 * @return 0 if OK
294 * @return 1 if id is unknown
295 */
296 int enableRule(in string ruleId);
297
298 /**
299 * Disable a rule.
300 *
301 * A disabled rule will be ignored when processing events.
302 *
303 * @return 0 if OK
304 * @return 1 if ruleId is unknown
305 */
306 int disableRule(in string ruleId);
307
308 /**
309 * Delete a rule.
310 *
311 * @return 0 if OK
312 * @return 1 if ruleId is unknown
313 * @return 2 if the rule is not deletable
314 */
315 int deleteRule(in string ruleId);
316
317 /**
318 * List all rules.
319 *
320 * Question: will number of rules be small enough to list them
321 * all in a single operation.
322 * A single Rule may be quite large...
323 * See below for alternative interface using iterator.
324 */
325 vector<Rule> listRules();
326
327
328 /* Deliver and confirm events. */
329 /* --------------------------- */
330
331 /**
332 * Deliver an event.
333 *
334 * @return 0 if OK
335 * @return 1 if event is unknown
336 */
337 int deliverEvent(in Event event);
338
339 /**
340 * Rearm an event rule that is active.
341 *
342 * Once a Rule triggers its actions it is done once. If the condition
343 * of the rules becomes false and back again true, no action will be
344 * performed unless the rule is rearmed. Rules may be auto-rearmed what
345 * means whenever the rule's conditions changes from false to true
346 * actions are triggered over and again.
347 *
348 * @return 0 if OK
349 * @return 1 if the rule is unknown
350 * @return 2 if the rule is not enabled
351 */
352 int rearmRule(in string ruleId);
353
354 };
355
356}
event::Engine
There is a single event engine instance reachable by a well known reference.
Definition EventEngine.idl:53
event::Engine::modifyRule
int modifyRule(in Rule rule)
Modify a rule.
event::Engine::testAction
int testAction(in Action action, out string errMsg, in vector< KeyValue > context)
Test an action.
event::Engine::modifyAction
int modifyAction(in Action action)
Modify an action.
event::Engine::listEventDescs
int listEventDescs(in vector< string > eventIdPrefix, out vector< EventDesc > eventDescs)
Query existing event descriptors.
event::Engine::disableRule
int disableRule(in string ruleId)
Disable a rule.
event::Engine::addAction
int addAction(in Action action, out string actionId)
Add a new action.
event::Engine::enableRule
int enableRule(in string ruleId)
Enable a rule.
event::Engine::listActionTypes
vector< string > listActionTypes()
List all available action types.
event::Engine::rearmRule
int rearmRule(in string ruleId)
Rearm an event rule that is active.
event::Engine::triggerAction
int triggerAction(in string actionId, out string errMsg, in vector< KeyValue > context)
Trigger an action.
event::Engine::addRule
int addRule(in Rule rule, out string ruleId)
Add a new rule.
event::Engine::listActions
vector< Action > listActions()
List all actions currently know to this event engine.
event::Engine::deleteAction
int deleteAction(in string actionId)
Remove an action.
event::Engine::deliverEvent
int deliverEvent(in Event event)
Deliver an event.
event::Engine::listRules
vector< Rule > listRules()
List all rules.
event::Engine::deleteRule
int deleteRule(in string ruleId)
Delete a rule.
event
Event interface.
Definition EventEngine.idl:11
event::Engine::Action
An action is a tuple of 'id' (unique within the scope of this event engine), 'name' which is unique a...
Definition EventEngine.idl:115
event::Engine::Action::isSystem
boolean isSystem
true for system-defined actions
Definition EventEngine.idl:118
event::Engine::Action::type
string type
Action type.
Definition EventEngine.idl:119
event::Engine::Action::name
string name
User-defined name.
Definition EventEngine.idl:117
event::Engine::Action::arguments
vector< KeyValue > arguments
Action argument map.
Definition EventEngine.idl:120
event::Engine::Action::id
string id
Action ID.
Definition EventEngine.idl:116
event::Engine::Condition
Condition is a logical combination of multiple events.
Definition EventEngine.idl:211
event::Engine::Condition::eventId
vector< string > eventId
Event ID.
Definition EventEngine.idl:230
event::Engine::Condition::negate
boolean negate
Negate the result.
Definition EventEngine.idl:227
event::Engine::Condition::Op
Op
logical operation to be applied over all conditions and event
Definition EventEngine.idl:214
event::Engine::Condition::AND
@ AND
Logical And.
Definition EventEngine.idl:215
event::Engine::Condition::XOR
@ XOR
Exclusive Or.
Definition EventEngine.idl:217
event::Engine::Condition::OR
@ OR
Logical Or.
Definition EventEngine.idl:216
event::Engine::Condition::MatchType
MatchType
the match type how to match the event assertion state
Definition EventEngine.idl:221
event::Engine::Condition::BOTH
@ BOTH
Match both (for trigger events)
Definition EventEngine.idl:224
event::Engine::Condition::DEASSERTED
@ DEASSERTED
Match if the event is deasserted.
Definition EventEngine.idl:223
event::Engine::Condition::ASSERTED
@ ASSERTED
Match if the event is asserted.
Definition EventEngine.idl:222
event::Engine::Condition::operation
Op operation
Logical operation to be applied.
Definition EventEngine.idl:228
event::Engine::Condition::conditions
vector< Condition > conditions
List of subordinate conditions.
Definition EventEngine.idl:231
event::Engine::Condition::matchType
MatchType matchType
Match type.
Definition EventEngine.idl:229
event::Engine::EventDesc
An event descriptor.
Definition EventEngine.idl:68
event::Engine::EventDesc::idComp
string idComp
Event ID component.
Definition EventEngine.idl:80
event::Engine::EventDesc::eventType
Event::Type eventType
Event type.
Definition EventEngine.idl:78
event::Engine::EventDesc::hasSnmpTrap
boolean hasSnmpTrap
Whether an SNMP trap is defined for the event.
Definition EventEngine.idl:82
event::Engine::EventDesc::name
string name
User-defined name.
Definition EventEngine.idl:81
event::Engine::EventDesc::entries
vector< EventDesc > entries
Child nodes.
Definition EventEngine.idl:83
event::Engine::EventDesc::Type
Type
Event descriptor type.
Definition EventEngine.idl:71
event::Engine::EventDesc::NODE
@ NODE
Intermediate node.
Definition EventEngine.idl:72
event::Engine::EventDesc::LEAF
@ LEAF
Leaf node.
Definition EventEngine.idl:74
event::Engine::EventDesc::DYN_NODE
@ DYN_NODE
Dynamic node.
Definition EventEngine.idl:73
event::Engine::EventDesc::eventDescType
Type eventDescType
Event descriptor type.
Definition EventEngine.idl:77
event::Engine::EventDesc::dynNodeContext
string dynNodeContext
Dynamic node context.
Definition EventEngine.idl:79
event::Engine::Rule
A Rule binds an action to a condition.
Definition EventEngine.idl:247
event::Engine::Rule::actionIds
vector< string > actionIds
List of action IDs.
Definition EventEngine.idl:255
event::Engine::Rule::isEnabled
boolean isEnabled
true if the rule is enabled
Definition EventEngine.idl:251
event::Engine::Rule::hasMatched
boolean hasMatched
true if the rule has matched since being armed
Definition EventEngine.idl:253
event::Engine::Rule::isSystem
boolean isSystem
true for system-defined rules
Definition EventEngine.idl:250
event::Engine::Rule::arguments
vector< KeyValue > arguments
Argument map.
Definition EventEngine.idl:256
event::Engine::Rule::name
string name
User-defined name.
Definition EventEngine.idl:249
event::Engine::Rule::id
string id
Rule ID.
Definition EventEngine.idl:248
event::Engine::Rule::isAutoRearm
boolean isAutoRearm
true for auto-rearming rules
Definition EventEngine.idl:252
event::Engine::Rule::condition
Condition condition
Trigger condition.
Definition EventEngine.idl:254
event::Event
Event has a type: a STATE event indicates that a boolean state has been changed, i....
Definition EventEngine.idl:34
event::Event::id
vector< string > id
Event id vector.
Definition EventEngine.idl:43
event::Event::timeStamp
time timeStamp
UNIX timestamp (UTC)
Definition EventEngine.idl:45
event::Event::Type
Type
Event type.
Definition EventEngine.idl:37
event::Event::TRIGGER
@ TRIGGER
Trigger event.
Definition EventEngine.idl:39
event::Event::STATE
@ STATE
State event.
Definition EventEngine.idl:38
event::Event::context
vector< KeyValue > context
Context map.
Definition EventEngine.idl:46
event::Event::asserted
boolean asserted
Assertion value.
Definition EventEngine.idl:44
event::Event::type
Type type
Event type.
Definition EventEngine.idl:42
event::KeyValue
Helper that is used wherever key/value pairs are required.
Definition EventEngine.idl:18
event::KeyValue::key
string key
Key.
Definition EventEngine.idl:19
event::KeyValue::value
string value
Value.
Definition EventEngine.idl:20