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  */
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 }
JSON-RPC Cascade Manager.
Definition: CascadeManager.idl:12
LinkUnitStatus newStatus
New communication status.
Definition: CascadeManager.idl:87
void unlink()
Release this link unit from the remote master's control.
void finalizeLink(in string token)
Finalize the link with this link unit.
Status getStatus()
Retrieve the full cascading status for this unit.
string master
Master IP address (if new role is link unit)
Definition: CascadeManager.idl:67
int requestLink(in string token)
Request to make this unit a link unit and put it under the remote master's control.
int releaseLinkUnit(in int linkId)
Release a link unit from this master's control.
Role newRole
New role after the change.
Definition: CascadeManager.idl:66
LinkUnitStatus
Link Unit Communication Status.
Definition: CascadeManager.idl:40
@ ACCESS_DENIED
The link unit denies access.
Definition: CascadeManager.idl:44
@ UNKNOWN
The status of the link unit is unknown.
Definition: CascadeManager.idl:41
@ FIRMWARE_UPDATE
This link unit is performing a firmware update.
Definition: CascadeManager.idl:45
@ UNREACHABLE
The link unit is unreachable.
Definition: CascadeManager.idl:43
@ OK
The link unit operates normally.
Definition: CascadeManager.idl:42
int addLinkUnit(in int linkId, in string host, in string login, in string password, in string newPassword)
Put a new link unit under this master's control.
LinkUnitStatus oldStatus
Previous communication status.
Definition: CascadeManager.idl:86
string host
Host name or IP address.
Definition: CascadeManager.idl:73
Role
JSON-RPC Cascade Role.
Definition: CascadeManager.idl:32
@ MASTER
Master unit controlling other devices.
Definition: CascadeManager.idl:34
@ STANDALONE
Standalone unit, not in cascade.
Definition: CascadeManager.idl:33
Raritan JSON-RPC.
Definition: CascadeManager.idl:9
Basic IDL definitions.
Definition: Event.idl:10
Link Unit Status.
Definition: CascadeManager.idl:50
LinkUnitStatus status
Communication status.
Definition: CascadeManager.idl:52
string host
Link unit host name or IP address.
Definition: CascadeManager.idl:51
string fwVersion
Firmware version of the link unit.
Definition: CascadeManager.idl:53
Full Cascading Status.
Definition: CascadeManager.idl:57
map< int, LinkUnit > linkUnits
The list of link units (if role is master)
Definition: CascadeManager.idl:60
string master
The master IP address (if role is link unit)
Definition: CascadeManager.idl:59
Role role
This unit's role in the JSON-RPC cascade.
Definition: CascadeManager.idl:58