Raritan PX2/PX3 JSON-RPC API

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 */
9 module 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_MASTER = 2; ///< Operation not allowed for a master 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
28 /** JSON-RPC Cascade Role */
29 enumeration Role {
30 STANDALONE, ///< Standalone unit, not in cascade
31 MASTER, ///< Master unit controlling other devices
32 LINK_UNIT ///< link unit under master control
33 };
34
35 /** Link Unit Communication Status */
36 [unknown_fallback("UNKNOWN")]
37 enumeration LinkUnitStatus {
38 UNKNOWN, ///< The status of the link unit is unknown
39 OK, ///< The link unit operates normally
40 UNREACHABLE, ///< The link unit is unreachable
41 ACCESS_DENIED, ///< The link unit denies access
42 FIRMWARE_UPDATE ///< Ths link unit is performing a firmware update
43 };
44
45 /** Link Unit Status */
46 structure LinkUnit {
47 string host; ///< Link unit host name or IP address
48 LinkUnitStatus status; ///< Communication status
49 };
50
51 /** Full Cascading Status */
52 structure Status {
53 Role role; ///< This unit's role in the JSON-RPC cascade
54 string master; ///< The master IP address (if role is link unit)
55 map<int, LinkUnit> linkUnits; ///< The list of link units (if role is master)
56 };
57
58 /** Event: This unit's role in the cascade has changed */
59 valueobject RoleChangedEvent extends idl.Event {
60 Role oldRole; ///< Previous role before the change
61 Role newRole; ///< New role after the change
62 string master; ///< Master IP address (if new role is link unit)
63 };
64
65 /** Event: A new link unit has been added */
66 valueobject LinkUnitAddedEvent extends event.UserEvent {
67 int linkId; ///< Link ID
68 string host; ///< Host name or IP address
69 };
70
71 /** Event: A link unit has been released */
72 valueobject LinkUnitReleasedEvent extends event.UserEvent {
73 int linkId; ///< Link ID
74 string host; ///< Host name or IP address
75 };
76
77 /** Event: A link unit's communication status has changed */
78 valueobject LinkUnitStatusChangedEvent extends idl.Event {
79 int linkId; ///< Link ID
80 string host; ///< Host name or IP address
81 LinkUnitStatus oldStatus; ///< Previous communication status
82 LinkUnitStatus newStatus; ///< New communication status
83 };
84
85 /**
86 * Retrieve the full cascading status for this unit.
87 *
88 * @return Full cascading status
89 */
90 Status getStatus();
91
92 /**
93 * Put a new link unit under this master's control.
94 *
95 * The login credentials must have administrator privileges on the link
96 * unit. They are only used to establish a trust relationship between
97 * master and link unit and not stored.
98 *
99 * This method can also be used to re-authenticate a link unit that
100 * denies access. In that case the linkId and host parameter must
101 * exactly match the existing values.
102 *
103 * @param linkId The ID for the new link unit
104 * @param host The link unit's host name or IP address
105 * @param login The administrator login for the link unit
106 * @param password The administrator password for the link unit
107 * @param newPassword The new administrator password for the unit.
108 * This is needed for adding a link unit that still has default
109 * settings and requires a password change. Otherwise it can be
110 * left empty.
111 *
112 * @return NO_ERROR The operation was successful
113 * @return ERR_INVALID_PARAM One of the parameters had an invalid value
114 * @return ERR_UNSUPPORTED_ON_LINK_UNIT This unit is currently a link unit and can't have link units of its own
115 * @return ERR_LINK_ID_IN_USE The specified link ID is already in use
116 * @return ERR_HOST_IN_USE The specified host is already in use
117 * @return ERR_LINK_UNIT_UNREACHABLE Connection to the link unit failed
118 * @return ERR_LINK_UNIT_ACCESS_DENIED The credentials for the link unit were invalid
119 * @return ERR_LINK_UNIT_REFUSED The remote unit refused to become our link unit, e.g. because it's a master itself
120 * @return ERR_UNIT_BUSY This unit is currently busy with handling another request
121 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
122 * @return ERR_PASSWORD_CHANGE_REQUIRED The specified link unit requires a password change
123 * @return ERR_PASSWORD_POLICY The new password did not meet the requirements
124 */
125 int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword);
126
127 /**
128 * Release a link unit from this master's control.
129 *
130 * @param linkId The ID of the link unit
131 *
132 * @return NO_ERROR The operation was successful
133 * @return ERR_INVALID_PARAM The specified link ID is invalid
134 */
135 int releaseLinkUnit(in int linkId);
136
137 /**
138 * Request to make this unit a link unit and put it under the remote
139 * master's control.
140 *
141 * This method is usually called by the master unit when adding a new
142 * link unit. The link will only be established once finalizeLink() is
143 * successfully called.
144 *
145 * @param token Authorization token for future requests
146 *
147 * @return NO_ERROR The operation was successful
148 * @return ERR_UNSUPPORTED_ON_MASTER This unit is a master and can't become a link unit
149 * @return ERR_NOT_SUPPORTED This device does not support PDU linking
150 */
151 int requestLink(in string token);
152
153 /**
154 * Finalize the link with this link unit.
155 *
156 * @param token same authorization token as used for requestLink()
157 *
158 * This method should only be called by the master unit in order to
159 * acknowledge the establishment of the link to the link unit and
160 * finalize the link build-up. The linking will only take effect once
161 * the link unit received this acknowledgement.
162 *
163 * If this method fails, you will get the ACCESS_DENIED status for this
164 * link unit and you will have to re-authenticate it.
165 */
166 void finalizeLink(in string token);
167
168 /**
169 * Release this link unit from the remote master's control.
170 *
171 * This method is usually called by the master unit when releasing a
172 * link unit. This unit will become a standalone unit.
173 */
174 void unlink();
175
176 };
177
178 }
cascading::CascadeManager::OK
The link unit operates normally.
Definition: CascadeManager.idl:39
cascading::CascadeManager::LinkUnitStatus
LinkUnitStatus
Link Unit Communication Status.
Definition: CascadeManager.idl:36
cascading::CascadeManager::oldStatus
LinkUnitStatus oldStatus
Previous communication status.
Definition: CascadeManager.idl:81
cascading::CascadeManager::host
string host
Host name or IP address.
Definition: CascadeManager.idl:68
cascading::CascadeManager::LinkUnit::host
string host
Link unit host name or IP address.
Definition: CascadeManager.idl:47
cascading::CascadeManager::MASTER
Master unit controlling other devices.
Definition: CascadeManager.idl:31
cascading::CascadeManager::UNKNOWN
The status of the link unit is unknown.
Definition: CascadeManager.idl:38
cascading::CascadeManager::Role
Role
JSON-RPC Cascade Role.
Definition: CascadeManager.idl:29
cascading::CascadeManager::LinkUnit::status
LinkUnitStatus status
Communication status.
Definition: CascadeManager.idl:48
cascading
Raritan JSON-RPC.
Definition: CascadeManager.idl:9
cascading::CascadeManager
JSON-RPC Cascade Manager.
Definition: CascadeManager.idl:12
idl
Basic IDL definitions.
Definition: Event.idl:10
cascading::CascadeManager::Status::master
string master
The master IP address (if role is link unit)
Definition: CascadeManager.idl:54
cascading::CascadeManager::UNREACHABLE
The link unit is unreachable.
Definition: CascadeManager.idl:40
cascading::CascadeManager::STANDALONE
Standalone unit, not in cascade.
Definition: CascadeManager.idl:30
cascading::CascadeManager::LinkUnit
Link Unit Status.
Definition: CascadeManager.idl:46
cascading::CascadeManager::Status::linkUnits
map< int, LinkUnit > linkUnits
The list of link units (if role is master)
Definition: CascadeManager.idl:55
cascading::CascadeManager::master
string master
Master IP address (if new role is link unit)
Definition: CascadeManager.idl:62
cascading::CascadeManager::newStatus
LinkUnitStatus newStatus
New communication status.
Definition: CascadeManager.idl:82
cascading::CascadeManager::ACCESS_DENIED
The link unit denies access.
Definition: CascadeManager.idl:41
cascading::CascadeManager::Status::role
Role role
This unit&#39;s role in the JSON-RPC cascade.
Definition: CascadeManager.idl:53
cascading::CascadeManager::Status
Full Cascading Status.
Definition: CascadeManager.idl:52
cascading::CascadeManager::newRole
Role newRole
New role after the change.
Definition: CascadeManager.idl:61