Legrand / Raritan / Server Technology Xerus™ JSON-RPC API

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 vector<EventDesc> entries; ///< Child nodes
83 };
84
85 /**
86 * Query existing event descriptors.
87 *
88 * @return 0 if OK
89 * @return 1 if id was not found
90 */
91 int listEventDescs(in vector<string> eventIdPrefix,
92 out vector<EventDesc> eventDescs);
93
94
95 /* Action definition and query */
96 /* --------------------------- */
97
98 /**
99 * List all available action types. The action type is intentionally
100 * defined generically so that implementation can be extensible without
101 * changing interface.
102 */
103 vector<string> listActionTypes();
104
105 /**
106 * An action is a tuple of 'id' (unique within the scope of this event
107 * engine), 'name' which is unique as well and used by the GUI as user
108 * readable identificator, 'isSystem' which denotes the action as
109 * system action, 'type' which defines what it is, and an argument
110 * vector that vary depending on type and which is passed to the action.
111 * The 'isSystem' flag is readonly and if set marks the action as not
112 * deletable.
113 */
114 structure Action {
115 string id; ///< Action ID
116 string name; ///< User-defined name
117 boolean isSystem; ///< \c true for system-defined actions
118 string type; ///< Action type
119 vector<KeyValue> arguments; ///< Action argument map
120 };
121
122 /**
123 * Add a new action.
124 *
125 * The id and isSystem fields are ignored. The actions's id field is
126 * allocated automatically and returned in the actionId parameter.
127 *
128 * @return 0 if OK
129 * @return 1 if the name of the new action already exists
130 * @return 2 if generating the action id failed
131 * @return 3 if the maximum number of actions have been created
132 */
133 int addAction(in Action action, out string actionId);
134
135 /**
136 * Modify an action.
137 *
138 * @return 0 if OK
139 * @return 1 if the name of the new action already exists
140 * @return 2 if the action id does not exist
141 */
142 int modifyAction(in Action action);
143
144 /**
145 * Remove an action.
146 *
147 * @return 0 if OK
148 * @return 1 if id is unknown
149 * @return 2 if the action is not deletable
150 */
151 int deleteAction(in string actionId);
152
153 /**
154 * List all actions currently know to this event engine.
155 */
156 vector<Action> listActions();
157
158 /**
159 * Trigger an action.
160 *
161 * This is mainly used for test and debugging. The operation will
162 * block until the action has been performed or an error occurred.
163 * In the latter case errMsg will contain an error message. The
164 * context is passed to the actions.
165 *
166 * NOTE: Currently this function doesn't block!
167 *
168 * @return 0 if OK
169 * @return 1 if id is unknown
170 * @return 2 if no actor was found for the action
171 * @return 3 if performing the action failed, errmsg will be set
172 */
173 int triggerAction(in string actionId, out string errMsg,
174 in vector<KeyValue> context);
175
176 /**
177 * Test an action.
178 *
179 * This is similar to {@link triggerAction}, except that an action
180 * that is not yet saved can be passed in. Therefore this method
181 * can be used for testing actions to be newly created. The
182 * operation will block until the action has been performed or an
183 * error occurred. In the latter case errMsg will contain an error
184 * message. The context is passed to the actions.
185 *
186 * NOTE: Currently this function doesn't block!
187 *
188 * @return 0 if OK
189 * @return 1 if the action name is invalid
190 * @return 2 if no actor was found for the action
191 * @return 3 if performing the action failed, errmsg will be set
192 */
193 int testAction(in Action action, out string errMsg,
194 in vector<KeyValue> context);
195
196
197 /* Rule Definition and query */
198 /* ------------------------- */
199
200 /**
201 * Condition is a logical combination of multiple events. Normally you
202 * should use STATE events in logical conditions. In case a TRIGGER
203 * event is part of a condition or logical operation it will per
204 * default be interpreted as deasserted. The TRIGGER will evaluate as
205 * asserted if that exact event was raised and is matched against the
206 * event rules. In some sense the 'assertion state' of the TRIGGER is
207 * true only at the moment the Event exists and set to false again once
208 * it passed.
209 */
210 structure Condition {
211
212 /** logical operation to be applied over all conditions and event */
213 enumeration Op {
214 AND, ///< Logical And
215 OR, ///< Logical Or
216 XOR ///< Exclusive Or
217 };
218
219 /** the match type how to match the event assertion state */
220 enumeration MatchType {
221 ASSERTED, ///< Match if the event is asserted
222 DEASSERTED, ///< Match if the event is deasserted
223 BOTH ///< Match both (for trigger events)
224 };
225
226 boolean negate; ///< Negate the result
227 Op operation; ///< Logical operation to be applied
228 MatchType matchType; ///< Match type
229 vector<string> eventId; ///< Event ID
230 vector<Condition> conditions; ///< List of subordinate conditions
231 };
232
233 /**
234 * A Rule binds an action to a condition.
235 *
236 * The 'id' is an unique identification within the scope of this event
237 * engine. The 'name' is unique as well and used by the GUI as user
238 * readable identificator. The flag 'isAutoRearm' determines whether
239 * actions are triggered again after condition reoccurres. The
240 * 'hasMatched' flag is true if the condition was true once and the rule
241 * is not rearmed yet. The 'isSystem' flag is readonly and if set marks
242 * the action as not deletable. The 'actionIds' are the actions to
243 * perform if the rule evaluates to true. The arguments are passed to
244 * the actions.
245 */
246 structure Rule {
247 string id; ///< Rule ID
248 string name; ///< User-defined name
249 boolean isSystem; ///< \c true for system-defined rules
250 boolean isEnabled; ///< \c true if the rule is enabled
251 boolean isAutoRearm; ///< \c true for auto-rearming rules
252 boolean hasMatched; ///< \c true if the rule has matched since being armed
253 Condition condition; ///< Trigger condition
254 vector<string> actionIds; ///< List of action IDs
255 vector<KeyValue> arguments; ///< Argument map
256 };
257
258 /**
259 * Add a new rule.
260 *
261 * The id, hasMatched and isSystem fields are ignored. The rule's
262 * id field is allocated automatically and returned in the the ruleId
263 * parameter.
264 *
265 * @return 0 if OK
266 * @return 1 if the name of the new rule already exists
267 * @return 2 if generating the rule id failed
268 * @return 3 if the rule condition contains an invalid event id
269 * @return 4 if the maximum number of rules have been created
270 * @return 5 if the maximum number of actions per rule is exceeded
271 */
272 int addRule(in Rule rule, out string ruleId);
273
274 /**
275 * Modify a rule.
276 *
277 * The hasMatched and isSystem fields are ignored.
278 *
279 * @return 0 if OK
280 * @return 1 if the name of the new rule already exists
281 * @return 2 if the rule id does not exist
282 * @return 3 if the rule condition contains an invalid event id
283 * @return 4 if the maximum number of actions per rule is exceeded
284 */
285 int modifyRule(in Rule rule);
286
287 /**
288 * Enable a rule.
289 *
290 * An enabled rule will be evaluated when processing events.
291 *
292 * @return 0 if OK
293 * @return 1 if id is unknown
294 */
295 int enableRule(in string ruleId);
296
297 /**
298 * Disable a rule.
299 *
300 * A disabled rule will be ignored when processing events.
301 *
302 * @return 0 if OK
303 * @return 1 if ruleId is unknown
304 */
305 int disableRule(in string ruleId);
306
307 /**
308 * Delete a rule.
309 *
310 * @return 0 if OK
311 * @return 1 if ruleId is unknown
312 * @return 2 if the rule is not deletable
313 */
314 int deleteRule(in string ruleId);
315
316 /**
317 * List all rules.
318 *
319 * Question: will number of rules be small enough to list them
320 * all in a single operation.
321 * A single Rule may be quite large...
322 * See below for alternative interface using iterator.
323 */
324 vector<Rule> listRules();
325
326
327 /* Deliver and confirm events. */
328 /* --------------------------- */
329
330 /**
331 * Deliver an event.
332 *
333 * @return 0 if OK
334 * @return 1 if event is unknown
335 */
336 int deliverEvent(in Event event);
337
338 /**
339 * Rearm an event rule that is active.
340 *
341 * Once a Rule triggers its actions it is done once. If the condition
342 * of the rules becomes false and back again true, no action will be
343 * performed unless the rule is rearmed. Rules may be auto-rearmed what
344 * means whenever the rule's conditions changes from false to true
345 * actions are triggered over and again.
346 *
347 * @return 0 if OK
348 * @return 1 if the rule is unknown
349 * @return 2 if the rule is not enabled
350 */
351 int rearmRule(in string ruleId);
352
353 };
354
355}
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 AlarmManager.idl:12
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:114
event::Engine::Action::isSystem
boolean isSystem
true for system-defined actions
Definition EventEngine.idl:117
event::Engine::Action::type
string type
Action type.
Definition EventEngine.idl:118
event::Engine::Action::name
string name
User-defined name.
Definition EventEngine.idl:116
event::Engine::Action::arguments
vector< KeyValue > arguments
Action argument map.
Definition EventEngine.idl:119
event::Engine::Action::id
string id
Action ID.
Definition EventEngine.idl:115
event::Engine::Condition
Condition is a logical combination of multiple events.
Definition EventEngine.idl:210
event::Engine::Condition::eventId
vector< string > eventId
Event ID.
Definition EventEngine.idl:229
event::Engine::Condition::negate
boolean negate
Negate the result.
Definition EventEngine.idl:226
event::Engine::Condition::Op
Op
logical operation to be applied over all conditions and event
Definition EventEngine.idl:213
event::Engine::Condition::AND
@ AND
Logical And.
Definition EventEngine.idl:214
event::Engine::Condition::OR
@ OR
Logical Or.
Definition EventEngine.idl:215
event::Engine::Condition::MatchType
MatchType
the match type how to match the event assertion state
Definition EventEngine.idl:220
event::Engine::Condition::DEASSERTED
@ DEASSERTED
Match if the event is deasserted.
Definition EventEngine.idl:222
event::Engine::Condition::ASSERTED
@ ASSERTED
Match if the event is asserted.
Definition EventEngine.idl:221
event::Engine::Condition::operation
Op operation
Logical operation to be applied.
Definition EventEngine.idl:227
event::Engine::Condition::conditions
vector< Condition > conditions
List of subordinate conditions.
Definition EventEngine.idl:230
event::Engine::Condition::matchType
MatchType matchType
Match type.
Definition EventEngine.idl:228
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::name
string name
User-defined name.
Definition EventEngine.idl:81
event::Engine::EventDesc::entries
vector< EventDesc > entries
Child nodes.
Definition EventEngine.idl:82
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::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:246
event::Engine::Rule::actionIds
vector< string > actionIds
List of action IDs.
Definition EventEngine.idl:254
event::Engine::Rule::isEnabled
boolean isEnabled
true if the rule is enabled
Definition EventEngine.idl:250
event::Engine::Rule::hasMatched
boolean hasMatched
true if the rule has matched since being armed
Definition EventEngine.idl:252
event::Engine::Rule::isSystem
boolean isSystem
true for system-defined rules
Definition EventEngine.idl:249
event::Engine::Rule::arguments
vector< KeyValue > arguments
Argument map.
Definition EventEngine.idl:255
event::Engine::Rule::name
string name
User-defined name.
Definition EventEngine.idl:248
event::Engine::Rule::id
string id
Rule ID.
Definition EventEngine.idl:247
event::Engine::Rule::isAutoRearm
boolean isAutoRearm
true for auto-rearming rules
Definition EventEngine.idl:251
event::Engine::Rule::condition
Condition condition
Trigger condition.
Definition EventEngine.idl:253
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::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