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

Loading...
Searching...
No Matches
CascadeManager.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2018 Raritan Inc. All rights reserved.
4 */
5
6#include <UserEvent.idl>
7
8/** Raritan JSON-RPC */
9module cascading {
10
11 /** JSON-RPC Cascade Manager */
12 interface CascadeManager {
13
14 constant int NO_ERROR = 0; ///< Operation successful, no error
15 constant int ERR_INVALID_PARAM = 1; ///< A parameter was invalid
16 constant int ERR_UNSUPPORTED_ON_PRIMARY_UNIT = 2; ///< Operation not allowed for a primary unit
17 constant int ERR_UNSUPPORTED_ON_LINK_UNIT = 3; ///< Operation not allowed for a link unit
18 constant int ERR_LINK_ID_IN_USE = 4; ///< The specified link ID is already used
19 constant int ERR_HOST_IN_USE = 5; ///< The specified host is already in use
20 constant int ERR_LINK_UNIT_UNREACHABLE = 6; ///< Could not connect to the link device
21 constant int ERR_LINK_UNIT_ACCESS_DENIED = 7; ///< Login to link device failed
22 constant int ERR_LINK_UNIT_REFUSED = 8; ///< Remote device refused to become a link unit
23 constant int ERR_UNIT_BUSY = 9; ///< The unit could not respond because it was busy
24 constant int ERR_NOT_SUPPORTED = 10; ///< Operation not supported on this device
25 constant int ERR_PASSWORD_CHANGE_REQUIRED = 11; ///< The unit requires a password change
26 constant int ERR_PASSWORD_POLICY = 12; ///< The given password did not meet the requirements
27 constant int ERR_LINK_UNIT_COMM_FAILED = 13; ///< Communication with the link unit failed
28 constant int ERR_LINK_UNIT_NOT_SUPPORTED = 14; ///< Link unit does not support cascading
29 constant int ERR_FIRMWARE_VERSION_MISMATCH = 15; ///< The firmware versions between primary and link unit do not match
30
31 /** Settings for primary unit */
32 structure PrimaryUnitSettings {
33 string caCertChain; ///< CA certificate chain that signs the link unit TLS certs
34 boolean allowOffTimeRangeCerts; ///< allow expired and not yet valid TLS certs
35 };
36
37 /** JSON-RPC Cascade Role */
38 enumeration Role {
39 STANDALONE, ///< Standalone unit, not in cascade
40 PRIMARY_UNIT, ///< Primary unit controlling other devices
41 LINK_UNIT ///< Link unit under primary unit control
42 };
43
44 enumeration LinkUnitType {
45 NETWORK, ///< High-level linking via JSON-RPC API
46 SECURE_SERIAL ///< Linking via encrypted serial bus (ScalePoint)
47 };
48
49 /** Link Unit Communication Status */
50 [unknown_fallback("UNKNOWN")]
51 enumeration LinkUnitStatus {
52 UNKNOWN, ///< The status of the link unit is unknown
53 OK, ///< The link unit operates normally
54 UNREACHABLE, ///< The link unit is unreachable
55 ACCESS_DENIED, ///< The link unit denies access
56 FIRMWARE_UPDATE, ///< This link unit is performing a firmware update
57 FIRMWARE_MISMATCH, ///< This link unit's firmware version does not match that of the primary unit
58 PENDING ///< The link unit becomes active after the next reboot
59 };
60
61 /** Link Unit Status */
62 structure LinkUnit {
63 LinkUnitType type; ///< Link unit type
64 string host; ///< Link unit host name, IP address or bus address
65 LinkUnitStatus status; ///< Communication status
66 string fwVersion; ///< Firmware version of the link unit
67 };
68
69 /** Full Cascading Status */
70 structure Status {
71 Role role; ///< This unit's role in the JSON-RPC cascade
72 string primaryUnit; ///< The primary unit IP address (if role is link unit)
73 map<int, LinkUnit> linkUnits; ///< The list of link units (if role is primary unit)
74 };
75
76 /** Status of the Link Port */
77 structure LinkPortStatus {
78 boolean isSupported; ///< true, if Link Port is supported on this device
79 boolean isLinkDetected; ///< true, if a link on the Link Port was detected
80 boolean isLinkingConfirmationNeeded; ///< true, if confirmation for linking via Link Port is needed
81 string connectedNeighborAddr; ///< link-local IPv6 address of the currently connected neighbor, or empty
82 };
83
84 /** Event: This unit's role in the cascade has changed */
85 valueobject RoleChangedEvent extends idl.Event {
86 Role oldRole; ///< Previous role before the change
87 Role newRole; ///< New role after the change
88 string primaryUnit; ///< Primary unit IP address (if new role is link unit)
89 };
90
91 /** Event: A new link unit has been added */
92 valueobject LinkUnitAddedEvent extends event.UserEvent {
93 int linkId; ///< Link ID
94 LinkUnitType type; ///< Link unit type
95 string host; ///< Host name, IP address or bus address
96 };
97
98 /** Event: A link unit has been released */
99 valueobject LinkUnitReleasedEvent extends event.UserEvent {
100 int linkId; ///< Link ID
101 LinkUnitType type; ///< Link unit type
102 string host; ///< Host name, IP address or bus address
103 };
104
105 /** Event: A link unit's communication status has changed */
106 valueobject LinkUnitStatusChangedEvent extends idl.Event {
107 int linkId; ///< Link ID
108 LinkUnitType type; ///< Link unit type
109 string host; ///< Host name, IP address or bus address
110 LinkUnitStatus oldStatus; ///< Previous communication status
111 LinkUnitStatus newStatus; ///< New communication status
112 };
113
114 /** Link Port Status changed */
115 valueobject LinkPortStatusChangedEvent extends idl.Event {
116 LinkPortStatus oldStatus; ///< Old Link Port status
117 LinkPortStatus newStatus; ///< New Link Port status
118 };
119
120 /**
121 * Retrieve settings for the primary unit.
122 *
123 * @return Primary unit settings
124 */
125 PrimaryUnitSettings getPrimaryUnitSettings();
126
127 /**
128 * Set settings for the primary unit.
129 *
130 * @param primaryUnitSettings Primary unit settings
131 *
132 * @return NO_ERROR The operation was successful
133 * @return ERR_INVALID_PARAM At least one of the parameters had an invalid value
134 */
135 int setPrimaryUnitSettings(in PrimaryUnitSettings primaryUnitSettings);
136
137 /**
138 * Retrieve the full cascading status for this unit.
139 *
140 * @return Full cascading status
141 */
142 Status getStatus();
143
144 /**
145 * Retrieve the current Link Port status
146 *
147 * @return Current Link Port status
148 */
149 LinkPortStatus getLinkPortStatus();
150
151 /**
152 * Put a new link unit under this primary unit's control.
153 *
154 * The login credentials must have administrator privileges on the link
155 * unit. They are only used to establish a trust relationship between
156 * primary and link unit and not stored.
157 *
158 * This method can also be used to re-authenticate a link unit that
159 * denies access. In that case the linkId and host parameter must
160 * exactly match the existing values.
161 *
162 * @param linkId The ID for the new link unit
163 * @param host The link unit's host name or IP address
164 * @param login The administrator login for the link unit
165 * @param password The administrator password for the link unit
166 * @param newPassword The new default administrator password for the unit.
167 * This is needed for adding a link unit that still has default
168 * settings and requires a password change. Otherwise it can be
169 * left empty. \c login must be the default admin.
170 *
171 * @return NO_ERROR The operation was successful
172 * @return ERR_INVALID_PARAM One of the parameters had an invalid value
173 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
174 * @return ERR_LINK_ID_IN_USE The specified link ID is already in use
175 * @return ERR_HOST_IN_USE The specified host is already in use
176 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
177 * @return ERR_LINK_UNIT_ACCESS_DENIED The credentials for the link unit were invalid
178 * @return ERR_LINK_UNIT_REFUSED The remote unit refused to become our link unit because it's a primary unit itself
179 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
180 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
181 * @return ERR_PASSWORD_CHANGE_REQUIRED The specified link unit requires a password change
182 * @return ERR_PASSWORD_POLICY The new password did not meet the requirements
183 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
184 * @return ERR_LINK_UNIT_NOT_SUPPORTED Link unit does not support cascading
185 * @return ERR_FIRMWARE_VERSION_MISMATCH The firmware version of the link unit does not match that of the primary unit
186 */
187 int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword);
188
189 /**
190 * Put a new link unit under this primary unit's control.
191 *
192 * The login credentials must have administrator privileges on the link
193 * unit. They are only used to establish a trust relationship between
194 * primary and link unit and not stored.
195 *
196 * This method can also be used to re-authenticate a link unit that
197 * denies access. In that case the linkId and host parameter must
198 * exactly match the existing values.
199 *
200 * @param linkId The ID for the new link unit
201 * @param host The link unit's host name or IP address
202 * @param login The administrator login for the link unit
203 * @param password The administrator password for the link unit
204 * @param newPassword The new default administrator password for the unit.
205 * This is needed for adding a link unit that still has default
206 * settings and requires a password change. Otherwise it can be
207 * left empty. \c login must be the default admin.
208 * @param disableStrongPasswordReq if \c true, this disables the strong password
209 * requirements on the link unit if \c newPassword is set
210 *
211 * @return see \ref addLinkUnit
212 */
213 int addLinkUnit2(in int linkId, in string host, in string login, in string password, in string newPassword, in boolean disableStrongPasswordReq);
214
215 /**
216 * Release a link unit from this primary unit's control.
217 *
218 * @param linkId The ID of the link unit
219 *
220 * @return NO_ERROR The operation was successful
221 * @return ERR_INVALID_PARAM The specified link ID is invalid
222 */
223 int releaseLinkUnit(in int linkId);
224
225 /**
226 * Request to make this unit a link unit and put it under the remote
227 * primary unit's control.
228 *
229 * This method is usually called by the primary unit when adding a new
230 * link unit. The link will only be established once finalizeLink() is
231 * successfully called.
232 *
233 * @param token Authorization token for future requests
234 *
235 * @return NO_ERROR The operation was successful
236 * @return ERR_UNSUPPORTED_ON_PRIMARY_UNIT This unit is a primary unit and can't become a link unit
237 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
238 */
239 int requestLink(in string token);
240
241 /**
242 * Finalize the link with this link unit.
243 *
244 * @param token same authorization token as used for requestLink()
245 *
246 * This method should only be called by the primary unit in order to
247 * acknowledge the establishment of the link to the link unit and
248 * finalize the link build-up. The linking will only take effect once
249 * the link unit received this acknowledgement.
250 *
251 * If this method fails, you will get the ACCESS_DENIED status for this
252 * link unit and you will have to re-authenticate it.
253 */
254 void finalizeLink(in string token);
255
256 /**
257 * Release this link unit from the remote primary unit's control.
258 *
259 * This method is usually called by the primary unit when releasing a
260 * link unit. This unit will become a standalone unit.
261 */
262 void unlink();
263
264 /**
265 * Check which cascading roles this unit supports.
266 *
267 * @return vector with Roles that are supported by this unit
268 */
269 vector<Role> getSupportedRoles();
270
271 /**
272 * Check which type of link units this unit supports.
273 *
274 * @return vector with supported link unit types
275 */
276 vector<LinkUnitType> getSupportedLinkUnitTypes();
277
278 /**
279 * Can be called on a network cascade primary unit to add expansion
280 * units of the network cascade as link units.
281 *
282 * @param linkId The ID for the new link unit
283 * @param nodeIndex The expansion unit's index in the network cascade (1 - 15)
284 * @param login The administrator login for the link unit
285 * @param password The administrator password for the link unit
286 * @param positionDependent If true, host names that depend on the nodex index will be used.
287 * If false, unique link-local IPv6 addresses will be used for linking.
288 *
289 * @return see \ref addLinkUnit
290 *
291 */
292 int addCascadeLinkUnit(in int linkId, in int nodeIndex, in string login, in string password, in boolean positionDependent);
293
294 /**
295 * Add a neighbor that was discovered on the link port as link unit. If
296 * a new password needs to be set, it will be generated.
297 *
298 * @return NO_ERROR The operation was successful
299 * @return ERR_INVALID_PARAM No neighbor currently discovered or no link id left
300 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
301 * @return ERR_HOST_IN_USE The link port neighbor was already added
302 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
303 * @return ERR_LINK_UNIT_ACCESS_DENIED The credentials for the link unit were invalid
304 * @return ERR_LINK_UNIT_REFUSED The remote unit refused to become our link unit because it's a primary unit itself
305 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
306 * @return ERR_NOT_SUPPORTED This device does not support PDU linking via link port
307 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
308 * @return ERR_LINK_UNIT_NOT_SUPPORTED Link unit does not support cascading
309 * @return ERR_FIRMWARE_VERSION_MISMATCH The firmware version of the link unit does not match that of the primary unit
310 */
311 int addLinkPortLinkUnit();
312
313 /**
314 * Add a serial link unit (ScalePoint Base).
315 *
316 * As a special case, link ID 1 is used to pair the primary unit on the
317 * "internal" RS485 bus. It will not be added to the list of link units.
318 *
319 * @param linkId The ID for the new link unit
320 * @param installKey The install key from the Base unit's label
321 *
322 * @return NO_ERROR The operation was successful
323 * @return ERR_INVALID_PARAM One of the parameters had an invalid value
324 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
325 * @return ERR_LINK_ID_IN_USE The specified link ID is already in use
326 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
327 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
328 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
329 * @return ERR_LINK_UNIT_COMM_FAILED Communication with the link unit failed
330 */
331 int addSecureSerialLinkUnit(in int linkId, in string installKey);
332
333 };
334
335}
cascading::CascadeManager
JSON-RPC Cascade Manager.
Definition CascadeManager.idl:12
cascading::CascadeManager::getSupportedRoles
vector< Role > getSupportedRoles()
Check which cascading roles this unit supports.
cascading::CascadeManager::setPrimaryUnitSettings
int setPrimaryUnitSettings(in PrimaryUnitSettings primaryUnitSettings)
Set settings for the primary unit.
cascading::CascadeManager::getStatus
Status getStatus()
Retrieve the full cascading status for this unit.
cascading::CascadeManager::addLinkUnit2
int addLinkUnit2(in int linkId, in string host, in string login, in string password, in string newPassword, in boolean disableStrongPasswordReq)
Put a new link unit under this primary unit's control.
cascading::CascadeManager::addLinkUnit
int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword)
Put a new link unit under this primary unit's control.
cascading::CascadeManager::getPrimaryUnitSettings
PrimaryUnitSettings getPrimaryUnitSettings()
Retrieve settings for the primary unit.
cascading::CascadeManager::addLinkPortLinkUnit
int addLinkPortLinkUnit()
Add a neighbor that was discovered on the link port as link unit.
cascading::CascadeManager::requestLink
int requestLink(in string token)
Request to make this unit a link unit and put it under the remote primary unit's control.
cascading::CascadeManager::getLinkPortStatus
LinkPortStatus getLinkPortStatus()
Retrieve the current Link Port status.
cascading::CascadeManager::getSupportedLinkUnitTypes
vector< LinkUnitType > getSupportedLinkUnitTypes()
Check which type of link units this unit supports.
cascading::CascadeManager::Role
Role
JSON-RPC Cascade Role.
Definition CascadeManager.idl:38
cascading::CascadeManager::STANDALONE
@ STANDALONE
Standalone unit, not in cascade.
Definition CascadeManager.idl:39
cascading::CascadeManager::PRIMARY_UNIT
@ PRIMARY_UNIT
Primary unit controlling other devices.
Definition CascadeManager.idl:40
cascading::CascadeManager::finalizeLink
void finalizeLink(in string token)
Finalize the link with this link unit.
cascading::CascadeManager::unlink
void unlink()
Release this link unit from the remote primary unit's control.
cascading::CascadeManager::LinkUnitStatus
LinkUnitStatus
Link Unit Communication Status.
Definition CascadeManager.idl:51
cascading::CascadeManager::FIRMWARE_UPDATE
@ FIRMWARE_UPDATE
This link unit is performing a firmware update.
Definition CascadeManager.idl:56
cascading::CascadeManager::FIRMWARE_MISMATCH
@ FIRMWARE_MISMATCH
This link unit's firmware version does not match that of the primary unit.
Definition CascadeManager.idl:57
cascading::CascadeManager::ACCESS_DENIED
@ ACCESS_DENIED
The link unit denies access.
Definition CascadeManager.idl:55
cascading::CascadeManager::OK
@ OK
The link unit operates normally.
Definition CascadeManager.idl:53
cascading::CascadeManager::UNKNOWN
@ UNKNOWN
The status of the link unit is unknown.
Definition CascadeManager.idl:52
cascading::CascadeManager::UNREACHABLE
@ UNREACHABLE
The link unit is unreachable.
Definition CascadeManager.idl:54
cascading::CascadeManager::addCascadeLinkUnit
int addCascadeLinkUnit(in int linkId, in int nodeIndex, in string login, in string password, in boolean positionDependent)
Can be called on a network cascade primary unit to add expansion units of the network cascade as link...
cascading::CascadeManager::LinkUnitType
LinkUnitType
Definition CascadeManager.idl:44
cascading::CascadeManager::NETWORK
@ NETWORK
High-level linking via JSON-RPC API.
Definition CascadeManager.idl:45
cascading::CascadeManager::releaseLinkUnit
int releaseLinkUnit(in int linkId)
Release a link unit from this primary unit's control.
cascading::CascadeManager::addSecureSerialLinkUnit
int addSecureSerialLinkUnit(in int linkId, in string installKey)
Add a serial link unit (ScalePoint Base).
cascading
Raritan JSON-RPC.
Definition CascadeManager.idl:9
idl
Basic IDL definitions.
Definition Event.idl:10
cascading::CascadeManager::LinkPortStatusChangedEvent
Link Port Status changed.
Definition CascadeManager.idl:115
cascading::CascadeManager::LinkPortStatusChangedEvent::oldStatus
LinkPortStatus oldStatus
Old Link Port status.
Definition CascadeManager.idl:116
cascading::CascadeManager::LinkPortStatusChangedEvent::newStatus
LinkPortStatus newStatus
New Link Port status.
Definition CascadeManager.idl:117
cascading::CascadeManager::LinkPortStatus
Status of the Link Port.
Definition CascadeManager.idl:77
cascading::CascadeManager::LinkPortStatus::isLinkingConfirmationNeeded
boolean isLinkingConfirmationNeeded
true, if confirmation for linking via Link Port is needed
Definition CascadeManager.idl:80
cascading::CascadeManager::LinkPortStatus::isSupported
boolean isSupported
true, if Link Port is supported on this device
Definition CascadeManager.idl:78
cascading::CascadeManager::LinkPortStatus::connectedNeighborAddr
string connectedNeighborAddr
link-local IPv6 address of the currently connected neighbor, or empty
Definition CascadeManager.idl:81
cascading::CascadeManager::LinkPortStatus::isLinkDetected
boolean isLinkDetected
true, if a link on the Link Port was detected
Definition CascadeManager.idl:79
cascading::CascadeManager::LinkUnitAddedEvent
Event: A new link unit has been added.
Definition CascadeManager.idl:92
cascading::CascadeManager::LinkUnitAddedEvent::type
LinkUnitType type
Link unit type.
Definition CascadeManager.idl:94
cascading::CascadeManager::LinkUnitAddedEvent::linkId
int linkId
Link ID.
Definition CascadeManager.idl:93
cascading::CascadeManager::LinkUnitAddedEvent::host
string host
Host name, IP address or bus address.
Definition CascadeManager.idl:95
cascading::CascadeManager::LinkUnitReleasedEvent
Event: A link unit has been released.
Definition CascadeManager.idl:99
cascading::CascadeManager::LinkUnitReleasedEvent::linkId
int linkId
Link ID.
Definition CascadeManager.idl:100
cascading::CascadeManager::LinkUnitReleasedEvent::host
string host
Host name, IP address or bus address.
Definition CascadeManager.idl:102
cascading::CascadeManager::LinkUnitReleasedEvent::type
LinkUnitType type
Link unit type.
Definition CascadeManager.idl:101
cascading::CascadeManager::LinkUnitStatusChangedEvent
Event: A link unit's communication status has changed.
Definition CascadeManager.idl:106
cascading::CascadeManager::LinkUnitStatusChangedEvent::oldStatus
LinkUnitStatus oldStatus
Previous communication status.
Definition CascadeManager.idl:110
cascading::CascadeManager::LinkUnitStatusChangedEvent::host
string host
Host name, IP address or bus address.
Definition CascadeManager.idl:109
cascading::CascadeManager::LinkUnitStatusChangedEvent::newStatus
LinkUnitStatus newStatus
New communication status.
Definition CascadeManager.idl:111
cascading::CascadeManager::LinkUnitStatusChangedEvent::linkId
int linkId
Link ID.
Definition CascadeManager.idl:107
cascading::CascadeManager::LinkUnitStatusChangedEvent::type
LinkUnitType type
Link unit type.
Definition CascadeManager.idl:108
cascading::CascadeManager::LinkUnit
Link Unit Status.
Definition CascadeManager.idl:62
cascading::CascadeManager::LinkUnit::type
LinkUnitType type
Link unit type.
Definition CascadeManager.idl:63
cascading::CascadeManager::LinkUnit::status
LinkUnitStatus status
Communication status.
Definition CascadeManager.idl:65
cascading::CascadeManager::LinkUnit::fwVersion
string fwVersion
Firmware version of the link unit.
Definition CascadeManager.idl:66
cascading::CascadeManager::LinkUnit::host
string host
Link unit host name, IP address or bus address.
Definition CascadeManager.idl:64
cascading::CascadeManager::PrimaryUnitSettings
Settings for primary unit.
Definition CascadeManager.idl:32
cascading::CascadeManager::PrimaryUnitSettings::caCertChain
string caCertChain
CA certificate chain that signs the link unit TLS certs.
Definition CascadeManager.idl:33
cascading::CascadeManager::PrimaryUnitSettings::allowOffTimeRangeCerts
boolean allowOffTimeRangeCerts
allow expired and not yet valid TLS certs
Definition CascadeManager.idl:34
cascading::CascadeManager::RoleChangedEvent
Event: This unit's role in the cascade has changed.
Definition CascadeManager.idl:85
cascading::CascadeManager::RoleChangedEvent::primaryUnit
string primaryUnit
Primary unit IP address (if new role is link unit)
Definition CascadeManager.idl:88
cascading::CascadeManager::RoleChangedEvent::oldRole
Role oldRole
Previous role before the change.
Definition CascadeManager.idl:86
cascading::CascadeManager::RoleChangedEvent::newRole
Role newRole
New role after the change.
Definition CascadeManager.idl:87
cascading::CascadeManager::Status
Full Cascading Status.
Definition CascadeManager.idl:70
cascading::CascadeManager::Status::primaryUnit
string primaryUnit
The primary unit IP address (if role is link unit)
Definition CascadeManager.idl:72
cascading::CascadeManager::Status::linkUnits
map< int, LinkUnit > linkUnits
The list of link units (if role is primary unit)
Definition CascadeManager.idl:73
cascading::CascadeManager::Status::role
Role role
This unit's role in the JSON-RPC cascade.
Definition CascadeManager.idl:71
idl::Event
Common base for all events.
Definition Event.idl:13