1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Raritan PX2/PX3 JSON-RPC API: Perl JSON-RPC Client Binding</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Raritan PX2/PX3 JSON-RPC API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Perl JSON-RPC Client Binding </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Pre-Requirements</h2>
<p>Raritan's JSON-RPC Perl bindings require the following perl packages:</p><ul>
<li>LWP::Protocol::https</li>
<li>LWP::UserAgent</li>
<li>HTTP::Request::Common</li>
<li>JSON</li>
<li>JSON::RPC::Common::Marshal::HTTP</li>
<li>Error</li>
<li>Data::Dumper</li>
<li>parent</li>
</ul>
<h3>Linux</h3>
<p>In dnf-based Linux distributions the following command will install the required packages:</p>
<div class="fragment"><div class="line">dnf install "perl(LWP::Protocol::https)" "perl(LWP::UserAgent)" \</div><div class="line"> "perl(HTTP::Request::Common)" "perl(JSON)" \</div><div class="line"> "perl(JSON::RPC::Common::Marshal::HTTP)" "perl(Error)" \</div><div class="line"> "perl(Data::Dumper)" "perl(parent)"</div></div><!-- fragment --><h3>Windows</h3>
<p>There are various Perl distributions available for Windows (see <a href="http://perl.org/get.html">http://perl.org/get.html</a>). The bindings were tested with ActiveState Perl (<a href="http://www.activestate.com/activeperl/downloads">http://www.activestate.com/activeperl/downloads</a>). After installing ActiveState Perl, the required modules can be installed with the following command:</p>
<div class="fragment"><div class="line">ppm install LWP::Protocol::https LWP::UserAgent HTTP::Request::Common \</div><div class="line"> JSON JSON::RPC::Common::Marshal::HTTP Error Data::Dumper parent</div></div><!-- fragment --><h2>Note on SSL Certificate Verification</h2>
<p>All Raritan devices enforce use of HTTPS when accessing the JSON-RPC service. By default, programs written with this client binding try to verify the authenticity of the server when connecting. This requires a valid SSL certificate to be installed on the device. When trying to connect to a device without a valid SSL certificate the client program will terminate with an error message.</p>
<p>It is possible to disable the SSL certificate verification by setting the 4th parameter of Raritan::RPC::Agent() to 1.</p>
<p>Code: </p><div class="fragment"><div class="line">my $agent = new Raritan::RPC::Agent($url, "admin", "raritan", 1)</div></div><!-- fragment --> <h2>Examples</h2>
<h3>Getting device information:</h3>
<p>Code: </p><div class="fragment"><div class="line">use Raritan::RPC;</div><div class="line">use Data::Dumper;</div><div class="line"></div><div class="line">my $agent = new Raritan::RPC::Agent('https://my-px.example.com', 'admin', 'raritan');</div><div class="line">my $pdu = $agent->createProxy('/model/pdu/0');</div><div class="line">my $metadata = $pdu->getMetaData();</div><div class="line">print Dumper($metadata);</div></div><!-- fragment --><p>Result: </p><div class="fragment"><div class="line">$VAR1 = {</div><div class="line"> 'hwRevision' => '0x64',</div><div class="line"> 'hasSwitchableOutlets' => 1,</div><div class="line"> 'hasLatchingOutletRelays' => 0,</div><div class="line"> 'isInlineMeter' => 0,</div><div class="line"> 'ctrlBoardSerial' => 'PKI9050003',</div><div class="line"> 'hasMeteredOutlets' => 0,</div><div class="line"> 'fwRevision' => '3.0.2.5-41550',</div><div class="line"> 'nameplate' => {</div><div class="line"> 'model' => 'PX2-2630U-A1',</div><div class="line"> 'imageFileURL' => '',</div><div class="line"> 'manufacturer' => 'Raritan',</div><div class="line"> 'rating' => {</div><div class="line"> 'voltage' => '360-415V',</div><div class="line"> 'current' => '24A',</div><div class="line"> 'power' => '15.0-17.3kVA',</div><div class="line"> 'frequency' => '50/60Hz'</div><div class="line"> },</div><div class="line"> 'partNumber' => '',</div><div class="line"> 'serialNumber' => 'PKE0954001'</div><div class="line"> },</div><div class="line"> 'macAddress' => '00:0d:5d:07:87:5c'</div><div class="line"> };</div></div><!-- fragment --><h3>Power-cycling an outlet:</h3>
<div class="fragment"><div class="line">use Raritan::RPC;</div><div class="line"></div><div class="line">my $agent = new Raritan::RPC::Agent('https://my-px.example.com', 'admin', 'raritan');</div><div class="line">my $pdu = $agent->createProxy('/model/pdu/0');</div><div class="line">my $outlets = $pdu->getOutlets();</div><div class="line">$outlets->[0]->cyclePowerState();</div></div><!-- fragment --><h3>Configuring the SNMP agent:</h3>
<div class="fragment"><div class="line">use Raritan::RPC;</div><div class="line"></div><div class="line">my $agent = new Raritan::RPC::Agent('https://my-device.example.com', 'admin', 'raritan');</div><div class="line">my $snmp_proxy = $agent->createProxy('/snmp');</div><div class="line">my $config = $snmp_proxy->getConfiguration();</div><div class="line">$config->{v2enable} = 0;</div><div class="line">$config->{readComm} = 'public';</div><div class="line">$config->{writeComm} = 'private';</div><div class="line">$snmp_proxy->setConfiguration($config);</div></div><!-- fragment --><h2>IDL-to-Perl Mapping</h2>
<h3>IDL Modules and Perl Package Names</h3>
<p>All classes dealing with Raritan JSON-RPC communication are located in Perl packages starting with <code>Raritan::RPC</code>. All named sections in IDL files (<code>module</code>, <code>interface</code> and <code>enumeration</code>) provide a scope for their included identifiers and are added as further components to the Perl package name.</p>
<h3>Interfaces and Methods</h3>
<p>IDL interfaces are mapped to Perl proxy classes which provide all methods defined by the IDL interface and its bases. Perl methods require the same number of scalar arguments as defined in the IDL signature. Simple types like integers, strings or enumerations are passed by scalar value; structures, vectors and maps are passed by reference. Output parameters are passed as references to a scalar variable which will be modified to point to the returned value. If the method is declared to have a non-void return type the Perl method will return a single scalar value.</p>
<p>Examples:</p>
<div class="fragment"><div class="line"># no parameters, no return value</div><div class="line">$firmware->reboot();</div><div class="line"></div><div class="line"># two input parameters, integer return value</div><div class="line">$ret = $user_manager->createAccount('newuser', 'newpassword');</div><div class="line"></div><div class="line"># one output parameter, integer return value</div><div class="line">my $results;</div><div class="line">$ret = $diagnostics->listTcpConnections(\$results);</div></div><!-- fragment --><h3>Structures</h3>
<p>IDL structures are mapped as scalar references to Perl hashes. Each element of the structure results in a hash entry whose key is the element identifier and whose value is a Perl scalar. When passing a structure to a method call addtional hash entries are ignored.</p>
<p>Example:</p>
<div class="fragment"><div class="line">$ssh_settings = {</div><div class="line"> 'allowPasswordAuth' => 1,</div><div class="line"> 'allowPublicKeyAuth' => 0</div><div class="line">};</div><div class="line">$security->setSSHSettings($ssh_settings);</div></div><!-- fragment --><h3>Enumerations</h3>
<p>Enumerated values are referenced by their fully-qualified name:</p>
<div class="fragment"><div class="line">$ret = $outlet->setPowerState(Raritan::RPC::pdumodel::Outlet::PowerState::PS_ON);</div></div><!-- fragment --><h3>Vectors</h3>
<p>Vectors are mapped as scalar references to Perl lists. Each list entry must be a scalar.</p>
<div class="fragment"><div class="line">$recipients = [ 'somebody@invalid.com', 'somebody.else@invalid.com' ];</div><div class="line">$smtp->testConfiguration($cfg, $recipients);</div></div><!-- fragment --><h3>Maps</h3>
<p>Maps are mapped as scalar references to Perl hashes:</p>
<div class="fragment"><div class="line">$priorities = {</div><div class="line"> 'important_client' => Raritan::RPC::webcam::Priority::VERY_HIGH,</div><div class="line"> 'other_client' => Raritan::RPC::webcam::Priority::LOW</div><div class="line">};</div><div class="line">$ret = $webcam->setClientTypePriorities($priorities);</div></div><!-- fragment --><h2>Exceptions</h2>
<p>In case of error conditions during a proxy method call or the <code>createProxy</code> funtion exceptions will be thrown. They can be caught using the <code>try</code> statement from the <code>Perl::Error</code> module.</p>
<p>The following exceptions are defined:</p>
<ul>
<li><p class="startli"><code>Raritan::RPC::HttpException</code></p>
<p class="startli">An error occured during HTTP communication, e.g. in case the connection was refused or the authentication failed. Please check the agent URL, the resource ID and your authentication credentials.</p>
</li>
<li><p class="startli"><code>Raritan::RPC::JsonRpcSyntaxException</code></p>
<p class="startli">The response from the server was not a valid JSON object. Please check the agent URL and the resource ID.</p>
</li>
<li><p class="startli"><code>Raritan::RPC::JsonRpcErrorException</code></p>
<p class="startli">The method call failed. This should not happen under normal circumstances and indicates a problem on the device.</p>
</li>
</ul>
<p>Example for catching an exception: </p><div class="fragment"><div class="line">use Raritan::RPC;</div><div class="line">use Error qw(:try);</div><div class="line"></div><div class="line">try {</div><div class="line"> print "Querying firmware version ... ";</div><div class="line"> my $agent = new Raritan::RPC::Agent('https://my-device.example.com', 'admin', 'raritan');</div><div class="line"> my $firmware_proxy = $agent->createProxy('/firmware');</div><div class="line"> my $version = $firmware_proxy->getVersion();</div><div class="line"> print "Success\n";</div><div class="line"> print "Firmware version: $version\n";</div><div class="line">} catch Raritan::RPC::HttpException with {</div><div class="line"> my $e = shift;</div><div class="line"> print "ERROR: ", $e;</div><div class="line">};</div></div><!-- fragment --><h2>Raritan::RPC::Agent Method Reference</h2>
<h3>Constructor: new Raritan::RPC::Agent($url, $user, $password, $no_cert_check)</h3>
<p>Creates a new agent.</p>
<p>Parameters:</p><ul>
<li><b>$url</b> Base URL of the device (e.g. "https://my-device.example.com")</li>
<li><b>$user</b> User Name (optional, use 'undef' when last parameter is used)</li>
<li><b>$password</b> Password (optional, use 'undef' when last parameter is used)</li>
<li><b>$no_cert_check</b> Set to 1 to disable TLS certificate check (optional)</li>
</ul>
<p>If username or password are omitted, it is necessary to call either set_auth_basic() or set_auth_token() before the first request.</p>
<h3>set_auth_basic($user, $password)</h3>
<p>This method enables HTTP basic authentication using username and password.</p>
<p>Parameters:</p><ul>
<li><b>$user</b> User Name</li>
<li><b>$password</b> Password</li>
</ul>
<h3>set_auth_token($token)</h3>
<p>This method enables HTTP authentication using a session token. A session token can be obtained by calling the newSession method of the session.SessionManager interface.</p>
<p>Parameters:</p><ul>
<li><b>$token</b> Session Token</li>
</ul>
<h3>timeout($seconds)</h3>
<p>Returns the current timeout and optionally sets a new request timeout.</p>
<p>Parameters:</p><ul>
<li><b>$seconds</b> New timeout in seconds (optional)</li>
</ul>
<p>Returns:</p><ul>
<li>Previous timeout in seconds</li>
</ul>
<h3>createProxy($rid, $basetype)</h3>
<p>Creates a new proxy object for the given resource id.</p>
<p>This method will query the type information for the specified resource ID and create a proxy object which provides all methods defined in the IDL definition.</p>
<p>When connecting to very old firmware versions (PX2 2.2 and earlier, EMX 2.0 and earlier) the type information of a resource ID cannot be queried. In this case the <b>$basetype</b> argument is required.</p>
<p>Parameters:</p><ul>
<li><b>$rid</b> The resource ID, e.g. "/auth/user/admin"</li>
<li><b>$basetype</b> The base type, e.g. "usermgmt.User" (optional)</li>
</ul>
<p>Returns:</p><ul>
<li>A new proxy object for the specified resource ID</li>
</ul>
<h3>set_verbose($verbose)</h3>
<p>Enables request tracing. When verbose mode is enabled all JSON-RPC requests and responses will be echoed to the console.</p>
<p>Parameters:</p><ul>
<li><b>$verbose</b> <code>true</code> to enable verbose mode </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Aug 21 2020 10:20:37 for Raritan PX2/PX3 JSON-RPC API by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.14
</small></address>
</body>
</html>
|
