Loading...
Searching...
No Matches
EventEngine.idl
/* SPDX-License-Identifier: BSD-3-Clause */
/*
* Copyright 2009 Raritan Inc. All rights reserved.
*/
/**
* Event interface
*
*/
module event {
/**
* Helper that is used wherever key/value pairs are required.
*
* @note This interface was designed before IDL maps were supported.
*/
structure KeyValue {
string key; ///< Key
string value; ///< Value
};
/**
* Event has a type:
* a STATE event indicates that a boolean state has been
* changed, i.e. asserted or deasserted
* a TRIGGER event is one that has no state assigned.
* conceptually it is asserted and deasserted at once.
* The id has multiple components that form a path into a hierarchy.
* The value ("asserted") indicates whether the state has become
* true (assertion) or false (deassertion). For events of type TRIGGER
* this will be true always.
*/
structure Event {
/** Event type */
enumeration Type {
STATE, ///< State event
TRIGGER ///< Trigger event
};
Type type; ///< Event type
vector<string> id; ///< Event id vector
boolean asserted; ///< Assertion value
time timeStamp; ///< UNIX timestamp (UTC)
vector<KeyValue> context; ///< Context map
};
/**
* There is a single event engine instance reachable by a well known
* reference.
*/
interface Engine {
/* Event registration and query */
/* ---------------------------- */
/**
* An event descriptor.
*
* In case eventDescType is LEAF then the descriptor refers to a
* 'real' event. In this case eventType is set and the entries vector
* is empty. Otherwise eventType is a don't care and the entries vector
* contains sub-entries. In case eventDescType is DYN_NODE then the
* dynNodeContext contains a key which is used to generate a dynamic
* node.
*/
structure EventDesc {
/** Event descriptor type */
enumeration Type {
NODE, ///< Intermediate node
DYN_NODE, ///< Dynamic node
LEAF ///< Leaf node
};
Type eventDescType; ///< Event descriptor type
Event.Type eventType; ///< Event type
string dynNodeContext; ///< Dynamic node context
string idComp; ///< Event ID component
string name; ///< User-defined name
vector<EventDesc> entries; ///< Child nodes
};
/**
* Query existing event descriptors.
*
* @return 0 if OK
* @return 1 if id was not found
*/
int listEventDescs(in vector<string> eventIdPrefix,
out vector<EventDesc> eventDescs);
/* Action definition and query */
/* --------------------------- */
/**
* List all available action types. The action type is intentionally
* defined generically so that implementation can be extensible without
* changing interface.
*/
vector<string> listActionTypes();
/**
* An action is a tuple of 'id' (unique within the scope of this event
* engine), 'name' which is unique as well and used by the GUI as user
* readable identificator, 'isSystem' which denotes the action as
* system action, 'type' which defines what it is, and an argument
* vector that vary depending on type and which is passed to the action.
* The 'isSystem' flag is readonly and if set marks the action as not
* deletable.
*/
structure Action {
string id; ///< Action ID
string name; ///< User-defined name
boolean isSystem; ///< \c true for system-defined actions
string type; ///< Action type
vector<KeyValue> arguments; ///< Action argument map
};
/**
* Add a new action.
*
* The id and isSystem fields are ignored. The actions's id field is
* allocated automatically and returned in the actionId parameter.
*
* @return 0 if OK
* @return 1 if the name of the new action already exists
* @return 2 if generating the action id failed
* @return 3 if the maximum number of actions have been created
*/
int addAction(in Action action, out string actionId);
/**
* Modify an action.
*
* @return 0 if OK
* @return 1 if the name of the new action already exists
* @return 2 if the action id does not exist
*/
int modifyAction(in Action action);
/**
* Remove an action.
*
* @return 0 if OK
* @return 1 if id is unknown
* @return 2 if the action is not deletable
*/
int deleteAction(in string actionId);
/**
* List all actions currently know to this event engine.
*/
vector<Action> listActions();
/**
* Trigger an action.
*
* This is mainly used for test and debugging. The operation will
* block until the action has been performed or an error occurred.
* In the latter case errMsg will contain an error message. The
* context is passed to the actions.
*
* NOTE: Currently this function doesn't block!
*
* @return 0 if OK
* @return 1 if id is unknown
* @return 2 if no actor was found for the action
* @return 3 if performing the action failed, errmsg will be set
*/
int triggerAction(in string actionId, out string errMsg,
in vector<KeyValue> context);
/**
* Test an action.
*
* This is similar to {@link triggerAction}, except that an action
* that is not yet saved can be passed in. Therefore this method
* can be used for testing actions to be newly created. The
* operation will block until the action has been performed or an
* error occurred. In the latter case errMsg will contain an error
* message. The context is passed to the actions.
*
* NOTE: Currently this function doesn't block!
*
* @return 0 if OK
* @return 1 if the action name is invalid
* @return 2 if no actor was found for the action
* @return 3 if performing the action failed, errmsg will be set
*/
int testAction(in Action action, out string errMsg,
in vector<KeyValue> context);
/* Rule Definition and query */
/* ------------------------- */
/**
* Condition is a logical combination of multiple events. Normally you
* should use STATE events in logical conditions. In case a TRIGGER
* event is part of a condition or logical operation it will per
* default be interpreted as deasserted. The TRIGGER will evaluate as
* asserted if that exact event was raised and is matched against the
* event rules. In some sense the 'assertion state' of the TRIGGER is
* true only at the moment the Event exists and set to false again once
* it passed.
*/
structure Condition {
/** logical operation to be applied over all conditions and event */
enumeration Op {
AND, ///< Logical And
OR, ///< Logical Or
XOR ///< Exclusive Or
};
/** the match type how to match the event assertion state */
enumeration MatchType {
ASSERTED, ///< Match if the event is asserted
DEASSERTED, ///< Match if the event is deasserted
BOTH ///< Match both (for trigger events)
};
boolean negate; ///< Negate the result
Op operation; ///< Logical operation to be applied
MatchType matchType; ///< Match type
vector<string> eventId; ///< Event ID
vector<Condition> conditions; ///< List of subordinate conditions
};
/**
* A Rule binds an action to a condition.
*
* The 'id' is an unique identification within the scope of this event
* engine. The 'name' is unique as well and used by the GUI as user
* readable identificator. The flag 'isAutoRearm' determines whether
* actions are triggered again after condition reoccurres. The
* 'hasMatched' flag is true if the condition was true once and the rule
* is not rearmed yet. The 'isSystem' flag is readonly and if set marks
* the action as not deletable. The 'actionIds' are the actions to
* perform if the rule evaluates to true. The arguments are passed to
* the actions.
*/
structure Rule {
string id; ///< Rule ID
string name; ///< User-defined name
boolean isSystem; ///< \c true for system-defined rules
boolean isEnabled; ///< \c true if the rule is enabled
boolean isAutoRearm; ///< \c true for auto-rearming rules
boolean hasMatched; ///< \c true if the rule has matched since being armed
Condition condition; ///< Trigger condition
vector<string> actionIds; ///< List of action IDs
vector<KeyValue> arguments; ///< Argument map
};
/**
* Add a new rule.
*
* The id, hasMatched and isSystem fields are ignored. The rule's
* id field is allocated automatically and returned in the the ruleId
* parameter.
*
* @return 0 if OK
* @return 1 if the name of the new rule already exists
* @return 2 if generating the rule id failed
* @return 3 if the rule condition contains an invalid event id
* @return 4 if the maximum number of rules have been created
* @return 5 if the maximum number of actions per rule is exceeded
*/
int addRule(in Rule rule, out string ruleId);
/**
* Modify a rule.
*
* The hasMatched and isSystem fields are ignored.
*
* @return 0 if OK
* @return 1 if the name of the new rule already exists
* @return 2 if the rule id does not exist
* @return 3 if the rule condition contains an invalid event id
* @return 4 if the maximum number of actions per rule is exceeded
*/
int modifyRule(in Rule rule);
/**
* Enable a rule.
*
* An enabled rule will be evaluated when processing events.
*
* @return 0 if OK
* @return 1 if id is unknown
*/
int enableRule(in string ruleId);
/**
* Disable a rule.
*
* A disabled rule will be ignored when processing events.
*
* @return 0 if OK
* @return 1 if ruleId is unknown
*/
int disableRule(in string ruleId);
/**
* Delete a rule.
*
* @return 0 if OK
* @return 1 if ruleId is unknown
* @return 2 if the rule is not deletable
*/
int deleteRule(in string ruleId);
/**
* List all rules.
*
* Question: will number of rules be small enough to list them
* all in a single operation.
* A single Rule may be quite large...
* See below for alternative interface using iterator.
*/
vector<Rule> listRules();
/* Deliver and confirm events. */
/* --------------------------- */
/**
* Deliver an event.
*
* @return 0 if OK
* @return 1 if event is unknown
*/
int deliverEvent(in Event event);
/**
* Rearm an event rule that is active.
*
* Once a Rule triggers its actions it is done once. If the condition
* of the rules becomes false and back again true, no action will be
* performed unless the rule is rearmed. Rules may be auto-rearmed what
* means whenever the rule's conditions changes from false to true
* actions are triggered over and again.
*
* @return 0 if OK
* @return 1 if the rule is unknown
* @return 2 if the rule is not enabled
*/
int rearmRule(in string ruleId);
};
}
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::XOR
@ XOR
Exclusive Or.
Definition EventEngine.idl:216
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::BOTH
@ BOTH
Match both (for trigger events)
Definition EventEngine.idl:223
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::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: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::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