Raritan / Server Technology Xerus™ PDU JSON-RPC API
DoorAccessControl.idl
1 #ifndef __SMARTLOCK_DOOR_ACCESS_CONTROL_IDL__
2 #define __SMARTLOCK_DOOR_ACCESS_CONTROL_IDL__
3 
4 #include <Event.idl>
5 #include <UserEvent.idl>
6 #include <PeripheralDeviceSlot.idl>
7 
8 module smartlock {
9 
10  /** Access control for door locks */
11  interface DoorAccessControl {
12 
13  constant int ERR_INVALID_SETTINGS = 1; ///< Invalid settings
14  constant int ERR_NO_SUCH_ID = 2; ///< No such ID
15  constant int ERR_MAX_RULES_REACHED = 3; ///< Maximum number of rules
16 
17  /**
18  * A condition representing an absolute time range.
19  *
20  * Timestamps are UNIX timestamps (UTC)
21  */
23  boolean enabled; ///< Condition is enabled
24  time validFrom; ///< Time range starting from this date or 0 if not set
25  time validTill; ///< Time range valid until this date or 0 if not set
26  };
27 
28  /**
29  * A condition representing a periodic time range.
30  *
31  * Once this condition is enabled, weekdays have to be specified in
32  * order to get granted access. A specific clock time range can be set
33  * to allow access only certain times of the day. The system's local time
34  * will be used (as defined by the configured time zone).
35  *
36  * The clock time range will wrap over into the next day if
37  * fromHourOfDay:fromMinuteOfHour >= tillHourOfDay:tillMinuteOfHour,
38  * meaning that the weekday of fromHourOfDay:fromMinuteOfHour will be checked.
39  */
41  boolean enabled; ///< Condition is enabled
42  vector<int> daysOfWeek; ///< Range for these days of the week (valid values are 0 - 6, 0 is Sunday)
43  int fromHourOfDay; ///< Range periodically starts from this hour of the day (0 - 23)
44  int tillHourOfDay; ///< Range periodically ends this hour of the day (0 - 23)
45  int fromMinuteOfHour; ///< Specify minute of starting hour (0 - 59)
46  int tillMinuteOfHour; ///< Specify minute of ending hour (0 - 59)
47  };
48 
49  /**
50  * Information in order to refer to a specific card reader
51  */
52  structure CardReaderInfo {
53  int linkId; ///< Unit the card reader is attached to
54  string position; ///< Position of the card reader.
55  ///< This can be fetched from the CardReader MetaData
56  };
57 
58  /**
59  * Information in order to refer to a specific keypad
60  */
61  structure KeypadInfo {
62  int linkId; ///< Unit the keypad is attached to
63  string position; ///< Position of the keypad
64  ///< This can be fetched from the Keypad MetaData
65  };
66 
67  /**
68  * A condition for specific cards and card readers.
69  */
70  structure CardCondition {
71  boolean enabled; ///< Condition is enabled
72  string cardUid; ///< Matching card uid
73  CardReaderInfo cardReader; ///< The card reader that has to be used
74  };
75 
76  /**
77  * A condition for keypads with a secret pin
78  */
79  structure KeypadCondition {
80  boolean enabled; ///< Condition is enabled
81  string pin; ///< Pin that has to be entered
82  KeypadInfo keypad; ///< The keypad that has to be used
83  };
84 
85 
86  /**
87  * Data representing a rule to control access to certain doors.
88  *
89  * Access is granted (i.e. the defined locks are opened) if the defined
90  * and enabled conditions are met. At least one CardCondition or one
91  * KeypadCondition must be enabled. If multiple conditions are enabled, all
92  * conditions have to be met during the timeout that is defined in
93  * conditionsTimeout.
94  */
95  structure DoorAccessRule {
96  string name; ///< A name to describe this rule
97  vector<peripheral.DeviceSlot> doorHandleLocks; ///< Open these door handle locks
98  CardCondition cardCondition1; ///< Condition that has to be fulfilled when inserting a card
99  CardCondition cardCondition2; ///< Additional card condition that is needed
100  KeypadCondition keypadCondition1; ///< Condition that has to be fulfilled when using a keypad
101  KeypadCondition keypadCondition2; ///< Additional keypad condition that is needed
102  int conditionsTimeout; ///< Timeout for matching multiple card / keypad conditions
103  AbsoluteTimeCondition absoluteTime; ///< Absolute time range condition
104  PeriodicTimeCondition periodicTime; ///< Periodic time range condition
105  };
106 
107  /**
108  * Door Access Denial Reason
109  */
111  DENIED_NO_MATCHING_RULE, ///< No rule that matches the triggering event
112  DENIED_ABSOLUTE_TIME_CONDITION, ///< Absolute time condition was not met
113  DENIED_PERIODIC_TIME_CONDITION, ///< Periodic time condition was not met
114  DENIED_CONDITIONS_TIMEOUT ///< A needed condition was not fulfilled during conditionsTimeout
115  };
116 
117  /**
118  * Event: Door access granted
119  *
120  * This Event will be triggered for every rule whose conditions were fulfilled.
121  */
122  valueobject DoorAccessGrantedEvent extends idl.Event {
123  int ruleId; ///< Rule id of rule that granted access
124  DoorAccessRule rule; ///< Rule settings of rule that granted access, cardUid and pin will be filtered
125  };
126 
127  /**
128  * Event: Door access denied
129  *
130  * This event will only be triggered if at least one DoorAccessRule
131  * exists and a card was inserted or keypad PIN entered, but none of
132  * the defined rules were sufficiently fulfilled to grant access.
133  *
134  * If matching rules are found, this will be triggered for every
135  * matching rule that could not be fulfilled. Otherwise it will only be
136  * triggered once with the according DoorAccessDenialReason.
137  */
138  valueobject DoorAccessDeniedEvent extends idl.Event {
139  DoorAccessDenialReason reason; ///< A DoorAccessDenialReason, specifying why the access was denied
140  int ruleId; ///< A matching rule that could not be fulfilled or -1 if no matching rule
141  string ruleName; ///< Name of the rule that could not be fulfilled or empty if no matching rule
142  };
143 
144  /**
145  * Event: Door access rule added
146  */
147  valueobject DoorAccessRuleAddedEvent extends event.UserEvent {
148  int ruleId; ///< New rule id
149  DoorAccessRule rule; ///< Rule that was added, cardUid and pin will be filtered
150  };
151 
152  /**
153  * Event: Door access rule modified
154  */
155  valueobject DoorAccessRuleChangedEvent extends event.UserEvent {
156  int ruleId; ///< Id of modified rule
157  DoorAccessRule oldRule; ///< Old rule settings, cardUid and pin will be filtered
158  DoorAccessRule newRule; ///< New rule settings, cardUid and pin will be filtered
159  };
160 
161  /**
162  * Event: Door access rule deleted
163  */
164  valueobject DoorAccessRuleDeletedEvent extends event.UserEvent {
165  int ruleId; ///< Id of deleted rule
166  DoorAccessRule rule; ///< Rule that was deleted, cardUid and pin will be filtered
167  };
168 
169  /**
170  * Get all stored door access control rules
171  *
172  * @return list of rules by id
173  */
174  map<int, DoorAccessRule> getDoorAccessRules();
175 
176  /**
177  * Replace all the currently existing rules. Note that this not only
178  * adds and modifies rules, but also deletes existing rules that are
179  * not present in the given rule set.
180  *
181  * In case of any rule being invalid, no changes will be made at all.
182  *
183  * @param rules the new rule set
184  * @param invalidRules in case of an error, return ids of invalid rules
185  *
186  * @return 0 if OK
187  * @return 1 if the rule set contains a rule with invalid values
188  */
189  int setAllDoorAccessRules(in map<int, DoorAccessRule> rules, out vector<int> invalidRuleIds);
190 
191  /**
192  * Add a door access control rule. If successful, the id of the new
193  * rule will be returned.
194  *
195  * @param rule the new rule
196  *
197  * @return 0 if OK
198  * @return 1 if rule has invalid values
199  * @return 3 if maximum number of rules reached
200  */
201  int addDoorAccessRule(in DoorAccessRule rule, out int ruleId);
202 
203  /**
204  * Modify an existing door access control rule
205  *
206  * @param id id of the rule to modify
207  * @param modifiedRule rule containing the new settings
208  *
209  * @return 0 if OK
210  * @return 1 if modifiedRule has invalid values
211  * @return 2 if no rule with this id
212  */
213  int modifyDoorAccessRule(in int id, in DoorAccessRule modifiedRule);
214 
215  /**
216  * Delete an existing door access control rule
217  *
218  * @param id id of the rule to delete
219  *
220  * @return 0 if OK
221  * @return 2 if no rule with this id
222  */
223  int deleteDoorAccessRule(in int id);
224  };
225 }
226 
227 #endif /* __SMARTLOCK_DOOR_ACCESS_CONTROL_IDL__ */
Peripheral Device Slot.
Definition: PeripheralDeviceSlot.idl:65
Access control for door locks.
Definition: DoorAccessControl.idl:11
int setAllDoorAccessRules(in map< int, DoorAccessRule > rules, out vector< int > invalidRuleIds)
Replace all the currently existing rules.
string ruleName
Name of the rule that could not be fulfilled or empty if no matching rule.
Definition: DoorAccessControl.idl:141
DoorAccessRule newRule
New rule settings, cardUid and pin will be filtered.
Definition: DoorAccessControl.idl:158
map< int, DoorAccessRule > getDoorAccessRules()
Get all stored door access control rules.
DoorAccessRule oldRule
Old rule settings, cardUid and pin will be filtered.
Definition: DoorAccessControl.idl:157
DoorAccessDenialReason
Door Access Denial Reason.
Definition: DoorAccessControl.idl:110
@ DENIED_NO_MATCHING_RULE
No rule that matches the triggering event.
Definition: DoorAccessControl.idl:111
@ DENIED_ABSOLUTE_TIME_CONDITION
Absolute time condition was not met.
Definition: DoorAccessControl.idl:112
@ DENIED_PERIODIC_TIME_CONDITION
Periodic time condition was not met.
Definition: DoorAccessControl.idl:113
int ruleId
A matching rule that could not be fulfilled or -1 if no matching rule.
Definition: DoorAccessControl.idl:140
int deleteDoorAccessRule(in int id)
Delete an existing door access control rule.
DoorAccessRule rule
Rule settings of rule that granted access, cardUid and pin will be filtered.
Definition: DoorAccessControl.idl:124
int addDoorAccessRule(in DoorAccessRule rule, out int ruleId)
Add a door access control rule.
int modifyDoorAccessRule(in int id, in DoorAccessRule modifiedRule)
Modify an existing door access control rule.
Basic IDL definitions.
Definition: Event.idl:10
Peripheral Devices.
Definition: PeripheralDeviceManager.idl:18
Keypad.
Definition: DoorAccessControl.idl:8
A condition representing an absolute time range.
Definition: DoorAccessControl.idl:22
time validFrom
Time range starting from this date or 0 if not set.
Definition: DoorAccessControl.idl:24
time validTill
Time range valid until this date or 0 if not set.
Definition: DoorAccessControl.idl:25
boolean enabled
Condition is enabled.
Definition: DoorAccessControl.idl:23
A condition for specific cards and card readers.
Definition: DoorAccessControl.idl:70
string cardUid
Matching card uid.
Definition: DoorAccessControl.idl:72
CardReaderInfo cardReader
The card reader that has to be used.
Definition: DoorAccessControl.idl:73
boolean enabled
Condition is enabled.
Definition: DoorAccessControl.idl:71
Information in order to refer to a specific card reader.
Definition: DoorAccessControl.idl:52
int linkId
Unit the card reader is attached to.
Definition: DoorAccessControl.idl:53
string position
Position of the card reader.
Definition: DoorAccessControl.idl:54
Data representing a rule to control access to certain doors.
Definition: DoorAccessControl.idl:95
int conditionsTimeout
Timeout for matching multiple card / keypad conditions.
Definition: DoorAccessControl.idl:102
PeriodicTimeCondition periodicTime
Periodic time range condition.
Definition: DoorAccessControl.idl:104
AbsoluteTimeCondition absoluteTime
Absolute time range condition.
Definition: DoorAccessControl.idl:103
KeypadCondition keypadCondition1
Condition that has to be fulfilled when using a keypad.
Definition: DoorAccessControl.idl:100
vector< peripheral::DeviceSlot > doorHandleLocks
Open these door handle locks.
Definition: DoorAccessControl.idl:97
KeypadCondition keypadCondition2
Additional keypad condition that is needed.
Definition: DoorAccessControl.idl:101
CardCondition cardCondition2
Additional card condition that is needed.
Definition: DoorAccessControl.idl:99
string name
A name to describe this rule.
Definition: DoorAccessControl.idl:96
CardCondition cardCondition1
Condition that has to be fulfilled when inserting a card.
Definition: DoorAccessControl.idl:98
A condition for keypads with a secret pin.
Definition: DoorAccessControl.idl:79
boolean enabled
Condition is enabled.
Definition: DoorAccessControl.idl:80
KeypadInfo keypad
The keypad that has to be used.
Definition: DoorAccessControl.idl:82
string pin
Pin that has to be entered.
Definition: DoorAccessControl.idl:81
Information in order to refer to a specific keypad.
Definition: DoorAccessControl.idl:61
string position
Position of the keypad This can be fetched from the Keypad MetaData.
Definition: DoorAccessControl.idl:63
int linkId
Unit the keypad is attached to.
Definition: DoorAccessControl.idl:62
A condition representing a periodic time range.
Definition: DoorAccessControl.idl:40
int fromHourOfDay
Range periodically starts from this hour of the day (0 - 23)
Definition: DoorAccessControl.idl:43
int tillMinuteOfHour
Specify minute of ending hour (0 - 59)
Definition: DoorAccessControl.idl:46
int tillHourOfDay
Range periodically ends this hour of the day (0 - 23)
Definition: DoorAccessControl.idl:44
int fromMinuteOfHour
Specify minute of starting hour (0 - 59)
Definition: DoorAccessControl.idl:45
vector< int > daysOfWeek
Range for these days of the week (valid values are 0 - 6, 0 is Sunday)
Definition: DoorAccessControl.idl:42
boolean enabled
Condition is enabled.
Definition: DoorAccessControl.idl:41