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
|
<!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: C# / .NET 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">C# / .NET JSON-RPC Client Binding </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Examples</h2>
<h3>Getting device information:</h3>
<div class="fragment"><div class="line"><span class="keyword">using</span> System;</div><div class="line"><span class="keyword">using</span> Com.Raritan.JsonRpc;</div><div class="line"><span class="keyword">using</span> Com.Raritan.Idl;</div><div class="line"><span class="keyword">using</span> Com.Raritan.Idl.pdumodel;</div><div class="line"></div><div class="line"><span class="keyword">namespace </span>Examples {</div><div class="line"> <span class="keyword">class </span>Program {</div><div class="line"> <span class="keyword">static</span> <span class="keywordtype">void</span> Main(<span class="keywordtype">string</span>[] args) {</div><div class="line"> <span class="comment">// create a JSON RPC agent, using a PX2 device URL</span></div><div class="line"> <span class="keyword">using</span> (Agent agent = <span class="keyword">new</span> Agent(<span class="stringliteral">"https://my-px.raritan.com"</span>)) {</div><div class="line"> <span class="comment">// set username and password</span></div><div class="line"> agent.Username = <span class="stringliteral">"agent"</span>;</div><div class="line"> agent.Password = <span class="stringliteral">"password"</span>;</div><div class="line"> <span class="comment">// disable TLS certificate check if default certificate is used</span></div><div class="line"> <span class="comment">// agent.ServerCertificateValidationCallback = Agent.UnsecureTrustAllCertificatesCallback;</span></div><div class="line"></div><div class="line"> <span class="comment">// query the firmware revision using JSON RPC</span></div><div class="line"> Pdu_4_0_0 pdu = <span class="keyword">new</span> Pdu_4_0_0(agent, <span class="stringliteral">"/model/pdu/0"</span>);</div><div class="line"> Pdu_4_0_0.MetaData metadata = pdu.getMetaData()._ret_;</div><div class="line"> Console.WriteLine(<span class="stringliteral">"Firmware version: "</span> + metadata.fwRevision);</div><div class="line"> }</div><div class="line"> }</div><div class="line"> }</div><div class="line">}</div></div><!-- fragment --><h3>Power-cycling an outlet:</h3>
<div class="fragment"><div class="line"><span class="keyword">using</span> System.Collections.Generic;</div><div class="line"><span class="keyword">using</span> System.Linq;</div><div class="line"><span class="keyword">using</span> Com.Raritan.Idl;</div><div class="line"><span class="keyword">using</span> Com.Raritan.Idl.pdumodel;</div><div class="line"><span class="keyword">using</span> Com.Raritan.JsonRpc;</div><div class="line"></div><div class="line">[...]</div><div class="line"></div><div class="line"><span class="keyword">using</span> (Agent agent = <span class="keyword">new</span> Agent(<span class="stringliteral">"https://my-px.raritan.com"</span>)) {</div><div class="line"> agent.Username = <span class="stringliteral">"agent"</span>;</div><div class="line"> agent.Password = <span class="stringliteral">"password"</span>;</div><div class="line"></div><div class="line"> Pdu_4_0_0 pdu = <span class="keyword">new</span> Pdu_4_0_0(agent, <span class="stringliteral">"/model/pdu/0"</span>);</div><div class="line"> IEnumerable<Outlet_2_0_0> outlets = pdu.getOutlets()._ret_;</div><div class="line"> outlets.FirstOrDefault().cyclePowerState();</div><div class="line">}</div></div><!-- fragment --><h2>IDL-to-.NET Mapping</h2>
<h3>Modules and .NET Namespaces</h3>
<p>The classes implementing Raritan JSON-RPC communication are contained in two separate .NET namespaces: The namespace <code>Com.Raritan.Idl</code> contains .NET classes for all IDL interfaces, and .NET equivalents for named IDL data types like structures or enumerations. The <code>Com.Raritan.JsonRpc</code> namespace contains utility classes for performing the JSON-RPC.</p>
<h3>Interfaces and Methods</h3>
<p>IDL interfaces are mapped to .NET classes. Each method defined in IDL maps to three overloaded methods in the corresponding .NET class:</p>
<div class="fragment"><div class="line"><span class="keyword">public</span> <span class="keyword">class </span>CreateAccountResult {</div><div class="line"> <span class="keyword">public</span> <span class="keywordtype">int</span> _ret_;</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// Version 1: synchronous method call</span></div><div class="line"><span class="keyword">public</span> CreateAccountResult createAccount(<span class="keywordtype">string</span> username, <span class="keywordtype">string</span> password) {</div><div class="line"> [...]</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// Version 2: asynchronous method call</span></div><div class="line"><span class="keyword">public</span> AsyncRequest createAccount(<span class="keywordtype">string</span> username, <span class="keywordtype">string</span> password,</div><div class="line"> AsyncRpcResponse<CreateAccountResult>.SuccessHandler rsp,</div><div class="line"> AsyncRpcResponse.FailureHandler fail) {</div><div class="line"> [...]</div><div class="line">}</div><div class="line"></div><div class="line"><span class="comment">// Version 3: asynchronous method call with custom options</span></div><div class="line"><span class="keyword">public</span> AsyncRequest createAccount(<span class="keywordtype">string</span> username, <span class="keywordtype">string</span> password,</div><div class="line"> AsyncRpcResponse<CreateAccountResult>.SuccessHandler rsp,</div><div class="line"> AsyncRpcResponse.FailureHandler fail,</div><div class="line"> RpcCtrl rpcCtrl) {</div><div class="line"> [...]</div><div class="line">}</div></div><!-- fragment --><ol type="1">
<li>A synchronous variant which takes the same arguments as the IDL method declaration. This method will block the calling thread until the JSON-RPC communication is finished and the result is available. If the method has a return value or out-parameters those will be included in the result object returned by the method. This version of the method is the only one that may throw a .NET exception in case of communication problems or an error response from the server.</li>
<li>An asynchronous variant. This version of the method returns immediately without performing any network communication. Instead, the request is processed by a background thread. When the JSON-RPC call is finished successfully, the passed <code>rsp</code> method callback is called. If there was an error, the <code>fail</code> method callback is called.</li>
<li>An asynchronous variant with custom options. By default, the background thread can combine multiple method calls into a single HTTP request. If that's not desired it can be suppressed by setting an option in the passed <code>rpcCtrl</code> object.</li>
</ol>
<h3>Structures</h3>
<p>IDL structures are mapped to .NET classes with public members for each structure element. Those classes feature a default constructor and implement the <code>ICloneable</code> interface.</p>
<h3>Enumerations, Vectors and Maps</h3>
<p>IDL enumerations are mapped to plain .NET enums. Vectors are mapped to System.Collections.Generic.IEnumerable, and maps are mapped to System.Collections.Generic.IDictionary.</p>
<h3>Exceptions</h3>
<p>Exceptional error conditions may occur because of communication problems or because of system errors that occur on the server while processing a request. Those "unexpected" error conditions are not a part of the regular IDL signature, so they are handled by using one of the following exceptions:</p>
<ul>
<li><p class="startli"><code>Com.Raritan.JsonRpc.RpcRequestException</code></p>
<p class="startli">This exception is raised in case of a communication failure. Typical examples for this include an unreachable server, an authentication problem or a wrong resource ID</p>
</li>
<li><p class="startli"><code>Com.Raritan.JsonRpc.RpcErrorException</code></p>
<p class="startli">This exception is raised in case the server responded with a JSON-RPC error object instead of the expected method result. This can indicate either an internal problem in the server or a malformed request from the client.</p>
</li>
<li><p class="startli"><code>Com.Raritan.JsonRpc.RpcFormatException</code></p>
<p class="startli">This exception is raised in case the JSON-RPC response from the server cannot be decoded. This may indicate an interface version mismatch between client and server.</p>
</li>
</ul>
<p>For synchronous method invocations the exceptions are thrown and can be intercepted with a try/catch block. For asynchronous method invocations the exception object is passed to the <code>fail</code> method callback.</p>
<h2>Interface Versions</h2>
<p>The .NET bindings contain classes for all IDL interface versions that have been released up to the firmware release the bindings were generated for. Using those classes client programs can be written to be compatible with any firmware version up until the most recent release.</p>
<p>IDL interface names like <code>pdumodel.Pdu_3_1_0</code> contain three separate version numbers:</p>
<ol type="1">
<li>A <em>major</em> version. This number is incremented when the interface has changed in an incompatible way. A client program that is written to support Pdu_2_* may or may not work with a device that implements the Pdu_3_* interface.</li>
<li>The middle number is the <em>sub-major</em> version. This number is incremented in case a referenced interface is changed in an incompatible way. A client can safely ignore the middle version number as long as it uses only methods of the interface itself. However, it should verify the type and version of any objects returned from an interface with a different sub-major number before using them.</li>
<li>The last number, the <em>minor</em> version, is incremented on backward- compatible interface changes, e.g. when a new method was introduced. A client that was written to support the <code>Pdu_3_1_0</code> interface is guaranteed to work with <code>Pdu_3_1_1</code> or later without modification. Object references returned from an interface with compatible changes can be safely used without additional compatibility checks.</li>
</ol>
<p>See the DumpPdu.cs program distributed with this documentation for an example how to write a client program that supports multiple interface versions.</p>
<h2>Bulk Requests</h2>
<p>The Bulk RPC interface allows combining multiple JSON-RPC method calls into a single bulk request that can be sent to the server and processed in a single HTTP request. When using the asynchronous API the .NET client library automatically adds all submitted requests into a bulk request queue. A background thread combines pending requests into a bulk request and sends it to the device. As a result, submitted requests can be delayed by up to 250 Milliseconds while the bulk RPC thread waits for more requests to be queued.</p>
<p>To bypass the bulk request queue, add an <code>rpcCtrl</code> parameter to the asynchronous method call. The following call will be immediately sent to the device as a dedicated JSON-RPC request:</p>
<div class="fragment"><div class="line">Net_4_0_0 <a class="code" href="namespacenet.html">net</a> = <span class="keyword">new</span> Net_4_0_0(agent, <span class="stringliteral">"/net"</span>);</div><div class="line"></div><div class="line"><a class="code" href="namespacenet.html">net</a>.getSettings(result => {</div><div class="line"> [...]</div><div class="line"> },</div><div class="line"> ex => {</div><div class="line"> [...]</div><div class="line"> },</div><div class="line"> <span class="keyword">new</span> RpcCtrl(RpcCtrl.BulkType.FORBID));</div></div><!-- fragment --><h2>Com.Raritan.JsonRpc.Agent Method and Property Reference</h2>
<h3>Constructor: Agent(url)</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>
</ul>
<p>It is necessary to set the Username/Password or the Token propertybefore the first request.</p>
<h3>Username</h3>
<p>This property sets or returns the username for HTTP basic authentication.</p>
<h3>Username</h3>
<p>This property sets or returns the password for HTTP basic authentication.</p>
<h3>Token</h3>
<p>When this property is set, it enables and disables HTTP authentication using a session token. A session token can be obtained by calling the newSession method of the session.SessionManager class.</p>
<p>Setting Token with a string variable which contains the token will enable token-based authentication.</p>
<p>When setting Token to null, token-based authentication is disabled. </p>
</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>
|
