Raritan / Server Technology Xerus™ PDU JSON-RPC API
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 
11 module 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  */
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 }
There is a single event engine instance reachable by a well known reference.
Definition: EventEngine.idl:53
int modifyRule(in Rule rule)
Modify a rule.
int testAction(in Action action, out string errMsg, in vector< KeyValue > context)
Test an action.
vector< string > listActionTypes()
List all available action types.
int modifyAction(in Action action)
Modify an action.
int listEventDescs(in vector< string > eventIdPrefix, out vector< EventDesc > eventDescs)
Query existing event descriptors.
int disableRule(in string ruleId)
Disable a rule.
int addAction(in Action action, out string actionId)
Add a new action.
int enableRule(in string ruleId)
Enable a rule.
vector< Rule > listRules()
List all rules.
int rearmRule(in string ruleId)
Rearm an event rule that is active.
vector< Action > listActions()
List all actions currently know to this event engine.
int triggerAction(in string actionId, out string errMsg, in vector< KeyValue > context)
Trigger an action.
int addRule(in Rule rule, out string ruleId)
Add a new rule.
int deleteAction(in string actionId)
Remove an action.
int deliverEvent(in Event event)
Deliver an event.
int deleteRule(in string ruleId)
Delete a rule.
Event interface.
Definition: AlarmManager.idl:12
An action is a tuple of 'id' (unique within the scope of this event engine), 'name' which is unique a...
Definition: EventEngine.idl:114
boolean isSystem
true for system-defined actions
Definition: EventEngine.idl:117
string type
Action type.
Definition: EventEngine.idl:118
string name
User-defined name.
Definition: EventEngine.idl:116
vector< KeyValue > arguments
Action argument map.
Definition: EventEngine.idl:119
string id
Action ID.
Definition: EventEngine.idl:115
Condition is a logical combination of multiple events.
Definition: EventEngine.idl:210
vector< string > eventId
Event ID.
Definition: EventEngine.idl:229
boolean negate
Negate the result.
Definition: EventEngine.idl:226
Op
logical operation to be applied over all conditions and event
Definition: EventEngine.idl:213
@ AND
Logical And.
Definition: EventEngine.idl:214
@ OR
Logical Or.
Definition: EventEngine.idl:215
MatchType
the match type how to match the event assertion state
Definition: EventEngine.idl:220
@ DEASSERTED
Match if the event is deasserted.
Definition: EventEngine.idl:222
@ ASSERTED
Match if the event is asserted.
Definition: EventEngine.idl:221
Op operation
Logical operation to be applied.
Definition: EventEngine.idl:227
vector< Condition > conditions
List of subordinate conditions.
Definition: EventEngine.idl:230
MatchType matchType
Match type.
Definition: EventEngine.idl:228
An event descriptor.
Definition: EventEngine.idl:68
string idComp
Event ID component.
Definition: EventEngine.idl:80
Event::Type eventType
Event type.
Definition: EventEngine.idl:78
string name
User-defined name.
Definition: EventEngine.idl:81
vector< EventDesc > entries
Child nodes.
Definition: EventEngine.idl:82
Type
Event descriptor type.
Definition: EventEngine.idl:71
@ NODE
Intermediate node.
Definition: EventEngine.idl:72
@ DYN_NODE
Dynamic node.
Definition: EventEngine.idl:73
Type eventDescType
Event descriptor type.
Definition: EventEngine.idl:77
string dynNodeContext
Dynamic node context.
Definition: EventEngine.idl:79
A Rule binds an action to a condition.
Definition: EventEngine.idl:246
vector< string > actionIds
List of action IDs.
Definition: EventEngine.idl:254
boolean isEnabled
true if the rule is enabled
Definition: EventEngine.idl:250
boolean hasMatched
true if the rule has matched since being armed
Definition: EventEngine.idl:252
boolean isSystem
true for system-defined rules
Definition: EventEngine.idl:249
vector< KeyValue > arguments
Argument map.
Definition: EventEngine.idl:255
string name
User-defined name.
Definition: EventEngine.idl:248
string id
Rule ID.
Definition: EventEngine.idl:247
boolean isAutoRearm
true for auto-rearming rules
Definition: EventEngine.idl:251
Condition condition
Trigger condition.
Definition: EventEngine.idl:253
Event has a type: a STATE event indicates that a boolean state has been changed, i....
Definition: EventEngine.idl:34
vector< string > id
Event id vector.
Definition: EventEngine.idl:43
time timeStamp
UNIX timestamp (UTC)
Definition: EventEngine.idl:45
Type
Event type.
Definition: EventEngine.idl:37
@ STATE
State event.
Definition: EventEngine.idl:38
vector< KeyValue > context
Context map.
Definition: EventEngine.idl:46
boolean asserted
Assertion value.
Definition: EventEngine.idl:44
Type type
Event type.
Definition: EventEngine.idl:42
Helper that is used wherever key/value pairs are required.
Definition: EventEngine.idl:18
string key
Key.
Definition: EventEngine.idl:19
string value
Value.
Definition: EventEngine.idl:20