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

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