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 }
The link unit operates normally.
Definition: CascadeManager.idl:39
LinkUnitStatus
Link Unit Communication Status.
Definition: CascadeManager.idl:36
LinkUnitStatus oldStatus
Previous communication status.
Definition: CascadeManager.idl:81
string host
Host name or IP address.
Definition: CascadeManager.idl:68
string host
Link unit host name or IP address.
Definition: CascadeManager.idl:47
Master unit controlling other devices.
Definition: CascadeManager.idl:31
The status of the link unit is unknown.
Definition: CascadeManager.idl:38
Role
JSON-RPC Cascade Role.
Definition: CascadeManager.idl:29
LinkUnitStatus status
Communication status.
Definition: CascadeManager.idl:48
Raritan JSON-RPC.
Definition: CascadeManager.idl:9
JSON-RPC Cascade Manager.
Definition: CascadeManager.idl:12
Basic IDL definitions.
Definition: Event.idl:10
string master
The master IP address (if role is link unit)
Definition: CascadeManager.idl:54
The link unit is unreachable.
Definition: CascadeManager.idl:40
Standalone unit, not in cascade.
Definition: CascadeManager.idl:30
Link Unit Status.
Definition: CascadeManager.idl:46
map< int, LinkUnit > linkUnits
The list of link units (if role is master)
Definition: CascadeManager.idl:55
string master
Master IP address (if new role is link unit)
Definition: CascadeManager.idl:62
LinkUnitStatus newStatus
New communication status.
Definition: CascadeManager.idl:82
The link unit denies access.
Definition: CascadeManager.idl:41
Role role
This unit&#39;s role in the JSON-RPC cascade.
Definition: CascadeManager.idl:53
Full Cascading Status.
Definition: CascadeManager.idl:52
Role newRole
New role after the change.
Definition: CascadeManager.idl:61