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