5 <title>JSDoc: Class: rpc</title>
7 <script src="scripts/prettify/prettify.js"> </script>
8 <script src="scripts/prettify/lang-css.js"> </script>
10 <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
12 <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
13 <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
20 <h1 class="page-title">Class: rpc</h1>
31 <h2><span class="attribs"><span class="type-signature"></span></span>
32 <span class="ancestors"><a href="LuCI.html">LuCI</a>.</span>rpc</h2>
34 <div class="class-description"><p>The <code>LuCI.rpc</code> class provides high level ubus JSON-RPC abstractions
35 and means for listing and invoking remove RPC methods.</p></div>
41 <div class="container-overview">
86 <dt class="tag-source">Source:</dt>
87 <dd class="tag-source"><ul class="dummy"><li>
88 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line8">line 8</a>
136 <h3 class="subsection-title">Methods</h3>
144 <h4 class="name" id="addInterceptor"><span class="type-signature"></span>addInterceptor<span class="signature">(interceptorFn)</span><span class="type-signature"> → {<a href="LuCI.rpc.html#~interceptorFn">LuCI.rpc~interceptorFn</a>}</span></h4>
151 <div class="description">
152 <p>Registers a new interceptor function.</p>
166 <table class="params">
179 <th class="last">Description</th>
188 <td class="name"><code>interceptorFn</code></td>
194 <span class="param-type"><a href="LuCI.rpc.html#~interceptorFn">LuCI.rpc~interceptorFn</a></span>
204 <td class="description last"><p>The inteceptor function to register.</p></td>
243 <dt class="tag-source">Source:</dt>
244 <dd class="tag-source"><ul class="dummy"><li>
245 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line454">line 454</a>
273 <div class="param-desc">
274 <p>Returns the given function value.</p>
285 <span class="param-type"><a href="LuCI.rpc.html#~interceptorFn">LuCI.rpc~interceptorFn</a></span>
303 <h4 class="name" id="declare"><span class="type-signature"></span>declare<span class="signature">(options)</span><span class="type-signature"> → {<a href="LuCI.rpc.html#~invokeFn">LuCI.rpc~invokeFn</a>}</span></h4>
310 <div class="description">
311 <p>Describes a remote RPC call procedure and returns a function
326 <table class="params">
339 <th class="last">Description</th>
348 <td class="name"><code>options</code></td>
354 <span class="param-type"><a href="LuCI.rpc.html#.DeclareOptions">LuCI.rpc.DeclareOptions</a></span>
364 <td class="description last"><p>If any object names are given, this function will return the method
365 signatures of each given object.</p></td>
404 <dt class="tag-source">Source:</dt>
405 <dd class="tag-source"><ul class="dummy"><li>
406 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line292">line 292</a>
434 <div class="param-desc">
435 <p>Returns a new function implementing the method call described in
436 <code>options</code>.</p>
447 <span class="param-type"><a href="LuCI.rpc.html#~invokeFn">LuCI.rpc~invokeFn</a></span>
465 <h4 class="name" id="getBaseURL"><span class="type-signature"></span>getBaseURL<span class="signature">()</span><span class="type-signature"> → {string}</span></h4>
472 <div class="description">
473 <p>Returns the current RPC base URL.</p>
515 <dt class="tag-source">Source:</dt>
516 <dd class="tag-source"><ul class="dummy"><li>
517 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line367">line 367</a>
545 <div class="param-desc">
546 <p>Returns the RPC URL endpoint to issue requests against.</p>
557 <span class="param-type">string</span>
575 <h4 class="name" id="getSessionID"><span class="type-signature"></span>getSessionID<span class="signature">()</span><span class="type-signature"> → {string}</span></h4>
582 <div class="description">
583 <p>Returns the current RPC session id.</p>
625 <dt class="tag-source">Source:</dt>
626 <dd class="tag-source"><ul class="dummy"><li>
627 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line346">line 346</a>
655 <div class="param-desc">
656 <p>Returns the 32 byte session ID string used for authenticating remote
668 <span class="param-type">string</span>
686 <h4 class="name" id="getStatusText"><span class="type-signature"></span>getStatusText<span class="signature">(statusCode)</span><span class="type-signature"> → {string}</span></h4>
693 <div class="description">
694 <p>Translates a numeric <code>ubus</code> error code into a human readable
709 <table class="params">
722 <th class="last">Description</th>
731 <td class="name"><code>statusCode</code></td>
737 <span class="param-type">number</span>
747 <td class="description last"><p>The numeric status code.</p></td>
786 <dt class="tag-source">Source:</dt>
787 <dd class="tag-source"><ul class="dummy"><li>
788 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line391">line 391</a>
816 <div class="param-desc">
817 <p>Returns the textual description of the code.</p>
828 <span class="param-type">string</span>
846 <h4 class="name" id="list"><span class="type-signature"></span>list<span class="signature">(…objectNames<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)>}</span></h4>
853 <div class="description">
854 <p>Lists available remote ubus objects or the method signatures of
855 specific objects.</p>
856 <p>This function has two signatures and is sensitive to the number of
857 arguments passed to it:</p>
859 <li><code>list()</code> -
860 Returns an array containing the names of all remote <code>ubus</code> objects</li>
861 <li><code>list("objname", ...)</code>
862 Returns method signatures for each given <code>ubus</code> object name.</li>
877 <table class="params">
892 <th class="last">Description</th>
901 <td class="name"><code>objectNames</code></td>
907 <span class="param-type">string</span>
914 <td class="attributes">
929 <td class="description last"><p>If any object names are given, this function will return the method
930 signatures of each given object.</p></td>
969 <dt class="tag-source">Source:</dt>
970 <dd class="tag-source"><ul class="dummy"><li>
971 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line140">line 140</a>
999 <div class="param-desc">
1000 <p>When invoked without arguments, this function will return a promise
1001 resolving to an array of <code>ubus</code> object names. When invoked with one or
1002 more arguments, a promise resolving to an object describing the method
1003 signatures of each requested <code>ubus</code> object name will be returned.</p>
1014 <span class="param-type">Promise.<(Array.<string>|Object.<string, Object.<string, Object.<string, string>>>)></span>
1032 <h4 class="name" id="removeInterceptor"><span class="type-signature"></span>removeInterceptor<span class="signature">(interceptorFn)</span><span class="type-signature"> → {boolean}</span></h4>
1039 <div class="description">
1040 <p>Removes a registered interceptor function.</p>
1051 <h5>Parameters:</h5>
1054 <table class="params">
1067 <th class="last">Description</th>
1076 <td class="name"><code>interceptorFn</code></td>
1082 <span class="param-type"><a href="LuCI.rpc.html#~interceptorFn">LuCI.rpc~interceptorFn</a></span>
1092 <td class="description last"><p>The inteceptor function to remove.</p></td>
1104 <dl class="details">
1131 <dt class="tag-source">Source:</dt>
1132 <dd class="tag-source"><ul class="dummy"><li>
1133 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line470">line 470</a>
1161 <div class="param-desc">
1162 <p>Returns <code>true</code> if the given function has been removed or <code>false</code>
1163 if it has not been found.</p>
1174 <span class="param-type">boolean</span>
1192 <h4 class="name" id="setBaseURL"><span class="type-signature"></span>setBaseURL<span class="signature">(sid)</span><span class="type-signature"></span></h4>
1199 <div class="description">
1200 <p>Set the RPC base URL to use.</p>
1211 <h5>Parameters:</h5>
1214 <table class="params">
1227 <th class="last">Description</th>
1236 <td class="name"><code>sid</code></td>
1242 <span class="param-type">string</span>
1252 <td class="description last"><p>Sets the RPC URL endpoint to issue requests against.</p></td>
1264 <dl class="details">
1291 <dt class="tag-source">Source:</dt>
1292 <dd class="tag-source"><ul class="dummy"><li>
1293 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line377">line 377</a>
1329 <h4 class="name" id="setSessionID"><span class="type-signature"></span>setSessionID<span class="signature">(sid)</span><span class="type-signature"></span></h4>
1336 <div class="description">
1337 <p>Set the RPC session id to use.</p>
1348 <h5>Parameters:</h5>
1351 <table class="params">
1364 <th class="last">Description</th>
1373 <td class="name"><code>sid</code></td>
1379 <span class="param-type">string</span>
1389 <td class="description last"><p>Sets the 32 byte session ID string used for authenticating remote
1402 <dl class="details">
1429 <dt class="tag-source">Source:</dt>
1430 <dd class="tag-source"><ul class="dummy"><li>
1431 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line357">line 357</a>
1465 <h3 class="subsection-title">Type Definitions</h3>
1469 <h4 class="name" id=".DeclareOptions">DeclareOptions</h4>
1480 <span class="param-type">Object</span>
1490 <h5 class="subsection-title">Properties:</h5>
1494 <table class="props">
1509 <th class="last">Description</th>
1518 <td class="name"><code>object</code></td>
1524 <span class="param-type">string</span>
1531 <td class="attributes">
1540 <td class="description last"><p>The name of the remote <code>ubus</code> object to invoke.</p></td>
1547 <td class="name"><code>method</code></td>
1553 <span class="param-type">string</span>
1560 <td class="attributes">
1569 <td class="description last"><p>The name of the remote <code>ubus</code> method to invoke.</p></td>
1576 <td class="name"><code>params</code></td>
1582 <span class="param-type">Array.<string></span>
1589 <td class="attributes">
1600 <td class="description last"><p>Lists the named parameters expected by the remote <code>ubus</code> RPC method.
1601 The arguments passed to the resulting generated method call function
1602 will be mapped to named parameters in the order they appear in this
1604 <p>Extraneous parameters passed to the generated function will not be
1605 sent to the remote procedure but are passed to the
1606 <a href="LuCI.rpc.html#~filterFn"><code>filter function</code></a> if one is specified.</p>
1609 <li><code>params: [ "foo", "bar" ]</code> -
1610 When the resulting call function is invoked with <code>fn(true, false)</code>,
1611 the corresponding args object sent to the remote procedure will be
1612 <code>{ foo: true, bar: false }</code>.</li>
1613 <li><code>params: [ "test" ], filter: function(reply, args, extra) { ... }</code> -
1614 When the resultung generated function is invoked with
1615 <code>fn("foo", "bar", "baz")</code> then <code>{ "test": "foo" }</code> will be sent as
1616 argument to the remote procedure and the filter function will be
1617 invoked with <code>filterFn(reply, [ "foo" ], "bar", "baz")</code></li>
1625 <td class="name"><code>expect</code></td>
1631 <span class="param-type">Object.<string, *></span>
1638 <td class="attributes">
1649 <td class="description last"><p>Describes the expected return data structure. The given object is
1650 supposed to contain a single key selecting the value to use from
1651 the returned <code>ubus</code> reply object. The value of the sole key within
1652 the <code>expect</code> object is used to infer the expected type of the received
1653 <code>ubus</code> reply data.</p>
1654 <p>If the received data does not contain <code>expect</code>'s key, or if the
1655 type of the data differs from the type of the value in the expect
1656 object, the expect object's value is returned as default instead.</p>
1657 <p>The key in the <code>expect</code> object may be an empty string (<code>''</code>) in which
1658 case the entire reply object is selected instead of one of its subkeys.</p>
1659 <p>If the <code>expect</code> option is omitted, the received reply will be returned
1660 as-is, regardless of its format or type.</p>
1663 <li><code>expect: { '': { error: 'Invalid response' } }</code> -
1664 This requires the entire <code>ubus</code> reply to be a plain JavaScript
1665 object. If the reply isn't an object but e.g. an array or a numeric
1666 error code instead, it will get replaced with
1667 <code>{ error: 'Invalid response' }</code> instead.</li>
1668 <li><code>expect: { results: [] }</code> -
1669 This requires the received <code>ubus</code> reply to be an object containing
1670 a key <code>results</code> with an array as value. If the received reply does
1671 not contain such a key, or if <code>reply.results</code> points to a non-array
1672 value, the empty array (<code>[]</code>) will be used instead.</li>
1673 <li><code>expect: { success: false }</code> -
1674 This requires the received <code>ubus</code> reply to be an object containing
1675 a key <code>success</code> with a boolean value. If the reply does not contain
1676 <code>success</code> or if <code>reply.success</code> is not a boolean value, <code>false</code> will
1677 be returned as default instead.</li>
1685 <td class="name"><code>filter</code></td>
1691 <span class="param-type"><a href="LuCI.rpc.html#~filterFn">LuCI.rpc~filterFn</a></span>
1698 <td class="attributes">
1709 <td class="description last"><p>Specfies an optional filter function which is invoked to transform the
1710 received reply data before it is returned to the caller.</p></td>
1720 <dl class="details">
1747 <dt class="tag-source">Source:</dt>
1748 <dd class="tag-source"><ul class="dummy"><li>
1749 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line160">line 160</a>
1771 <h4 class="name" id="~filterFn"><span class="type-signature"></span>filterFn<span class="signature">(data, args, …extraArgs)</span><span class="type-signature"> → {*}</span></h4>
1778 <div class="description">
1779 <p>The filter function is invoked to transform a received <code>ubus</code> RPC call
1780 reply before returning it to the caller.</p>
1791 <h5>Parameters:</h5>
1794 <table class="params">
1809 <th class="last">Description</th>
1818 <td class="name"><code>data</code></td>
1824 <span class="param-type">*</span>
1831 <td class="attributes">
1842 <td class="description last"><p>The received <code>ubus</code> reply data or a subset of it as described in the
1843 <code>expect</code> option of the RPC call declaration. In case of remote call
1844 errors, <code>data</code> is numeric <code>ubus</code> error code instead.</p></td>
1851 <td class="name"><code>args</code></td>
1857 <span class="param-type">Array.<*></span>
1864 <td class="attributes">
1875 <td class="description last"><p>The arguments the RPC method has been invoked with.</p></td>
1882 <td class="name"><code>extraArgs</code></td>
1888 <span class="param-type">*</span>
1895 <td class="attributes">
1908 <td class="description last"><p>All extraneous arguments passed to the RPC method exceeding the number
1909 of arguments describes in the RPC call declaration.</p></td>
1921 <dl class="details">
1948 <dt class="tag-source">Source:</dt>
1949 <dd class="tag-source"><ul class="dummy"><li>
1950 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line231">line 231</a>
1978 <div class="param-desc">
1979 <p>The return value of the filter function will be returned to the caller
1980 of the RPC method as-is.</p>
1991 <span class="param-type">*</span>
2009 <h4 class="name" id="~interceptorFn"><span class="type-signature"></span>interceptorFn<span class="signature">(msg, req)</span><span class="type-signature"> → {Promise.<*>|*}</span></h4>
2016 <div class="description">
2017 <p>Registered interceptor functions are invoked before the standard reply
2018 parsing and handling logic.</p>
2019 <p>By returning rejected promises, interceptor functions can cause the
2020 invocation function to fail, regardless of the received reply.</p>
2021 <p>Interceptors may also modify their message argument in-place to
2022 rewrite received replies before they're processed by the standard
2023 response handling code.</p>
2024 <p>A common use case for such functions is to detect failing RPC replies
2025 due to expired authentication in order to trigger a new login.</p>
2036 <h5>Parameters:</h5>
2039 <table class="params">
2052 <th class="last">Description</th>
2061 <td class="name"><code>msg</code></td>
2067 <span class="param-type">*</span>
2077 <td class="description last"><p>The unprocessed, JSON decoded remote RPC method call reply.</p>
2078 <p>Since interceptors run before the standard parsing logic, the reply
2079 data is not verified for correctness or filtered according to
2080 <code>expect</code> and <code>filter</code> specifications in the declarations.</p></td>
2087 <td class="name"><code>req</code></td>
2093 <span class="param-type">Object</span>
2103 <td class="description last"><p>The related request object which is an extended variant of the
2104 declaration object, allowing access to internals of the invocation
2105 function such as <code>filter</code>, <code>expect</code> or <code>params</code> values.</p></td>
2117 <dl class="details">
2144 <dt class="tag-source">Source:</dt>
2145 <dd class="tag-source"><ul class="dummy"><li>
2146 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line408">line 408</a>
2174 <div class="param-desc">
2175 <p>Interceptor functions may return a promise to defer response
2176 processing until some delayed work completed. Any values the returned
2177 promise resolves to are ignored.</p>
2178 <p>When the returned promise rejects with an error, the invocation
2179 function will fail too, forwarding the error to the caller.</p>
2190 <span class="param-type">Promise.<*></span>
2193 <span class="param-type">*</span>
2211 <h4 class="name" id="~invokeFn"><span class="type-signature"></span>invokeFn<span class="signature">(…params)</span><span class="type-signature"> → {Promise.<*>}</span></h4>
2218 <div class="description">
2219 <p>The generated invocation function is returned by
2220 <a href="LuCI.rpc.html#declare"><code>rpc.declare()</code></a> and encapsulates a single
2221 RPC method call.</p>
2222 <p>Calling this function will execute a remote <code>ubus</code> HTTP call request
2223 using the arguments passed to it as arguments and return a promise
2224 resolving to the received reply values.</p>
2235 <h5>Parameters:</h5>
2238 <table class="params">
2253 <th class="last">Description</th>
2262 <td class="name"><code>params</code></td>
2268 <span class="param-type">*</span>
2275 <td class="attributes">
2288 <td class="description last"><p>The parameters to pass to the remote procedure call. The given
2289 positional arguments will be named to named RPC parameters according
2290 to the names specified in the <code>params</code> array of the method declaration.</p>
2291 <p>Any additional parameters exceeding the amount of arguments in the
2292 <code>params</code> declaration are passed as private extra arguments to the
2293 declared filter function.</p></td>
2305 <dl class="details">
2332 <dt class="tag-source">Source:</dt>
2333 <dd class="tag-source"><ul class="dummy"><li>
2334 <a href="rpc.js.html">rpc.js</a>, <a href="rpc.js.html#line254">line 254</a>
2362 <div class="param-desc">
2363 <p>Returns a promise resolving to the result data of the remote <code>ubus</code>
2364 RPC method invocation, optionally substituted and filtered according
2365 to the <code>expect</code> and <code>filter</code> declarations.</p>
2376 <span class="param-type">Promise.<*></span>
2402 <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="LuCI.html">LuCI</a></li><li><a href="LuCI.Class.html">Class</a></li><li><a href="LuCI.dom.html">dom</a></li><li><a href="LuCI.fs.html">fs</a></li><li><a href="LuCI.Headers.html">Headers</a></li><li><a href="LuCI.Network.html">Network</a></li><li><a href="LuCI.Network.Device.html">Device</a></li><li><a href="LuCI.Network.Hosts.html">Hosts</a></li><li><a href="LuCI.Network.Protocol.html">Protocol</a></li><li><a href="LuCI.Network.WifiDevice.html">WifiDevice</a></li><li><a href="LuCI.Network.WifiNetwork.html">WifiNetwork</a></li><li><a href="LuCI.Poll.html">Poll</a></li><li><a href="LuCI.Request.html">Request</a></li><li><a href="LuCI.Request.poll.html">poll</a></li><li><a href="LuCI.Response.html">Response</a></li><li><a href="LuCI.rpc.html">rpc</a></li><li><a href="LuCI.uci.html">uci</a></li><li><a href="LuCI.view.html">view</a></li><li><a href="LuCI.XHR.html">XHR</a></li></ul>
2408 Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Nov 05 2019 09:33:05 GMT+0100 (Central European Standard Time)
2411 <script> prettyPrint(); </script>
2412 <script src="scripts/linenumber.js"> </script>
projects / oweals / luci.git / blob