5 <title>JSDoc: Source: uci.js
</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">Source: uci.js
</h1>
29 <pre class=
"prettyprint source linenums"><code>'use strict';
38 * The `LuCI.uci` class utilizes {@link LuCI.rpc} to declare low level
39 * remote UCI `ubus` procedures and implements a local caching and data
40 * manipulation layer on top to allow for synchroneous operations on
41 * UCI configuration data.
43 return L.Class.extend(/** @lends LuCI.uci.prototype */ {
44 __init__: function() {
57 callLoad: rpc.declare({
61 expect: { values: { } }
65 callOrder: rpc.declare({
68 params: [ 'config', 'sections' ]
71 callAdd: rpc.declare({
74 params: [ 'config', 'type', 'name', 'values' ],
75 expect: { section: '' }
78 callSet: rpc.declare({
81 params: [ 'config', 'section', 'values' ]
84 callDelete: rpc.declare({
87 params: [ 'config', 'section', 'options' ]
90 callApply: rpc.declare({
93 params: [ 'timeout', 'rollback' ]
96 callConfirm: rpc.declare({
103 * Generates a new, unique section ID for the given configuration.
105 * Note that the generated ID is temporary, it will get replaced by an
106 * identifier in the form `cfgXXXXXX` once the configuration is saved
107 * by the remote `ubus` UCI api.
109 * @param {string} config
110 * The configuration to generate the new section ID for.
113 * A newly generated, unique section ID in the form `newXXXXXX`
114 * where `X` denotes a hexadecimal digit.
116 createSID: function(conf) {
117 var v = this.state.values,
118 n = this.state.creates,
122 sid =
"new%06x".format(Math.random() *
0xFFFFFF);
123 } while ((n[conf]
&& n[conf][sid]) || (v[conf]
&& v[conf][sid]));
129 * Resolves a given section ID in extended notation to the internal
132 * @param {string} config
133 * The configuration to resolve the section ID for.
135 * @param {string} sid
136 * The section ID to resolve. If the ID is in the form `@typename[#]`,
137 * it will get resolved to an internal anonymous ID in the forms
138 * `cfgXXXXXX`/`newXXXXXX` or to the name of a section in case it points
139 * to a named section. When the given ID is not in extended notation,
140 * it will be returned as-is.
142 * @returns {string|null}
143 * Returns the resolved section ID or the original given ID if it was
144 * not in extended notation. Returns `null` when an extended ID could
145 * not be resolved to existing section ID.
147 resolveSID: function(conf, sid) {
148 if (typeof(sid) != 'string')
151 var m = /^@([a-zA-Z0-
9_-]+)\[(-?[
0-
9]+)\]$/.exec(sid);
156 sections = this.sections(conf, type),
157 section = sections[pos
>=
0 ? pos : sections.length + pos];
159 return section ? section['.name'] : null;
166 reorderSections: function() {
167 var v = this.state.values,
168 n = this.state.creates,
169 r = this.state.reorder,
172 if (Object.keys(r).length ===
0)
173 return Promise.resolve();
176 gather all created and existing sections, sort them according
177 to their index value and issue an uci order call
190 o.sort(function(a, b) {
191 return (a['.index'] - b['.index']);
196 for (var i =
0; i
< o.length; i++)
197 sids.push(o[i]['.name']);
199 tasks.push(this.callOrder(c, sids));
203 this.state.reorder = { };
204 return Promise.all(tasks);
208 loadPackage: function(packageName) {
209 if (this.loaded[packageName] == null)
210 return (this.loaded[packageName] = this.callLoad(packageName));
212 return Promise.resolve(this.loaded[packageName]);
216 * Loads the given UCI configurations from the remote `ubus` api.
218 * Loaded configurations are cached and only loaded once. Subsequent
219 * load operations of the same configurations will return the cached
222 * To force reloading a configuration, it has to be unloaded with
223 * {@link LuCI.uci#unload uci.unload()} first.
225 * @param {string|string[]} config
226 * The name of the configuration or an array of configuration
229 * @returns {Promise
<string[]
>}
230 * Returns a promise resolving to the names of the configurations
231 * that have been successfully loaded.
233 load: function(packages) {
238 if (!Array.isArray(packages))
239 packages = [ packages ];
241 for (var i =
0; i
< packages.length; i++)
242 if (!self.state.values[packages[i]]) {
243 pkgs.push(packages[i]);
244 tasks.push(self.loadPackage(packages[i]));
247 return Promise.all(tasks).then(function(responses) {
248 for (var i =
0; i
< responses.length; i++)
249 self.state.values[pkgs[i]] = responses[i];
251 if (responses.length)
252 document.dispatchEvent(new CustomEvent('uci-loaded'));
259 * Unloads the given UCI configurations from the local cache.
261 * @param {string|string[]} config
262 * The name of the configuration or an array of configuration
265 unload: function(packages) {
266 if (!Array.isArray(packages))
267 packages = [ packages ];
269 for (var i =
0; i
< packages.length; i++) {
270 delete this.state.values[packages[i]];
271 delete this.state.creates[packages[i]];
272 delete this.state.changes[packages[i]];
273 delete this.state.deletes[packages[i]];
275 delete this.loaded[packages[i]];
280 * Adds a new section of the given type to the given configuration,
281 * optionally named according to the given name.
283 * @param {string} config
284 * The name of the configuration to add the section to.
286 * @param {string} type
287 * The type of the section to add.
289 * @param {string} [name]
290 * The name of the section to add. If the name is omitted, an anonymous
291 * section will be added instead.
294 * Returns the section ID of the newly added section which is equivalent
295 * to the given name for non-anonymous sections.
297 add: function(conf, type, name) {
298 var n = this.state.creates,
299 sid = name || this.createSID(conf);
309 '.index':
1000 + this.state.newidx++
316 * Removes the section with the given ID from the given configuration.
318 * @param {string} config
319 * The name of the configuration to remove the section from.
321 * @param {string} sid
322 * The ID of the section to remove.
324 remove: function(conf, sid) {
325 var n = this.state.creates,
326 c = this.state.changes,
327 d = this.state.deletes;
329 /* requested deletion of a just created section */
330 if (n[conf]
&& n[conf][sid]) {
345 * A section object represents the options and their corresponding values
346 * enclosed within a configuration section, as well as some additional
347 * meta data such as sort indexes and internal ID.
349 * Any internal metadata fields are prefixed with a dot which is isn't
350 * an allowed character for normal option names.
352 * @typedef {Object
<string, boolean|number|string|string[]
>} SectionObject
355 * @property {boolean} .anonymous
356 * The `.anonymous` property specifies whether the configuration is
357 * anonymous (`true`) or named (`false`).
359 * @property {number} .index
360 * The `.index` property specifes the sort order of the section.
362 * @property {string} .name
363 * The `.name` property holds the name of the section object. It may be
364 * either an anonymous ID in the form `cfgXXXXXX` or `newXXXXXX` with `X`
365 * being a hexadecimal digit or a string holding the name of the section.
367 * @property {string} .type
368 * The `.type` property contains the type of the corresponding uci
371 * @property {string|string[]} *
372 * A section object may contain an arbitrary number of further properties
373 * representing the uci option enclosed in the section.
375 * All option property names will be in the form `[A-Za-z0-
9_]+` and
376 * either contain a string value or an array of strings, in case the
377 * underlying option is an UCI list.
381 * The sections callback is invoked for each section found within
382 * the given configuration and receives the section object and its
383 * associated name as arguments.
385 * @callback LuCI.uci~sectionsFn
387 * @param {LuCI.uci.SectionObject} section
388 * The section object.
390 * @param {string} sid
391 * The name or ID of the section.
395 * Enumerates the sections of the given configuration, optionally
398 * @param {string} config
399 * The name of the configuration to enumerate the sections for.
401 * @param {string} [type]
402 * Enumerate only sections of the given type. If omitted, enumerate
405 * @param {LuCI.uci~sectionsFn} [cb]
406 * An optional callback to invoke for each enumerated section.
408 * @returns {Array
<LuCI.uci.SectionObject
>}
409 * Returns a sorted array of the section objects within the given
410 * configuration, filtered by type of a type has been specified.
412 sections: function(conf, type, cb) {
414 v = this.state.values[conf],
415 n = this.state.creates[conf],
416 c = this.state.changes[conf],
417 d = this.state.deletes[conf];
423 if (!d || d[s] !== true)
424 if (!type || v[s]['.type'] == type)
425 sa.push(Object.assign({ }, v[s], c ? c[s] : undefined));
429 if (!type || n[s]['.type'] == type)
430 sa.push(Object.assign({ }, n[s]));
432 sa.sort(function(a, b) {
433 return a['.index'] - b['.index'];
436 for (var i =
0; i
< sa.length; i++)
439 if (typeof(cb) == 'function')
440 for (var i =
0; i
< sa.length; i++)
441 cb.call(this, sa[i], sa[i]['.name']);
447 * Gets the value of the given option within the specified section
448 * of the given configuration or the entire section object if the
449 * option name is omitted.
451 * @param {string} config
452 * The name of the configuration to read the value from.
454 * @param {string} sid
455 * The name or ID of the section to read.
457 * @param {string} [option]
458 * The option name to read the value from. If the option name is
459 * omitted or `null`, the entire section is returned instead.
461 * @returns {null|string|string[]|LuCI.uci.SectionObject}
462 * - Returns a string containing the option value in case of a
464 * - Returns an array of strings containing the option values in
465 * case of `option` pointing to an UCI list.
466 * - Returns a {@link LuCI.uci.SectionObject section object} if
467 * the `option` argument has been omitted or is `null`.
468 * - Returns `null` if the config, section or option has not been
469 * found or if the corresponding configuration is not loaded.
471 get: function(conf, sid, opt) {
472 var v = this.state.values,
473 n = this.state.creates,
474 c = this.state.changes,
475 d = this.state.deletes;
477 sid = this.resolveSID(conf, sid);
482 /* requested option in a just created section */
483 if (n[conf]
&& n[conf][sid]) {
490 return n[conf][sid][opt];
493 /* requested an option value */
495 /* check whether option was deleted */
496 if (d[conf]
&& d[conf][sid]) {
497 if (d[conf][sid] === true)
500 for (var i =
0; i
< d[conf][sid].length; i++)
501 if (d[conf][sid][i] == opt)
505 /* check whether option was changed */
506 if (c[conf]
&& c[conf][sid]
&& c[conf][sid][opt] != null)
507 return c[conf][sid][opt];
509 /* return base value */
510 if (v[conf]
&& v[conf][sid])
511 return v[conf][sid][opt];
516 /* requested an entire section */
524 * Sets the value of the given option within the specified section
525 * of the given configuration.
527 * If either config, section or option is null, or if `option` begins
528 * with a dot, the function will do nothing.
530 * @param {string} config
531 * The name of the configuration to set the option value in.
533 * @param {string} sid
534 * The name or ID of the section to set the option value in.
536 * @param {string} option
537 * The option name to set the value for.
539 * @param {null|string|string[]} value
540 * The option value to set. If the value is `null` or an empty string,
541 * the option will be removed, otherwise it will be set or overwritten
542 * with the given value.
544 set: function(conf, sid, opt, val) {
545 var v = this.state.values,
546 n = this.state.creates,
547 c = this.state.changes,
548 d = this.state.deletes;
550 sid = this.resolveSID(conf, sid);
552 if (sid == null || opt == null || opt.charAt(
0) == '.')
555 if (n[conf]
&& n[conf][sid]) {
557 n[conf][sid][opt] = val;
559 delete n[conf][sid][opt];
561 else if (val != null
&& val !== '') {
562 /* do not set within deleted section */
563 if (d[conf]
&& d[conf][sid] === true)
566 /* only set in existing sections */
567 if (!v[conf] || !v[conf][sid])
576 /* undelete option */
577 if (d[conf]
&& d[conf][sid])
578 d[conf][sid] = d[conf][sid].filter(function(o) { return o !== opt });
580 c[conf][sid][opt] = val;
583 /* only delete in existing sections */
584 if (!(v[conf]
&& v[conf][sid]
&& v[conf][sid].hasOwnProperty(opt))
&&
585 !(c[conf]
&& c[conf][sid]
&& c[conf][sid].hasOwnProperty(opt)))
594 if (d[conf][sid] !== true)
595 d[conf][sid].push(opt);
600 * Remove the given option within the specified section of the given
603 * This function is a convenience wrapper around
604 * `uci.set(config, section, option, null)`.
606 * @param {string} config
607 * The name of the configuration to remove the option from.
609 * @param {string} sid
610 * The name or ID of the section to remove the option from.
612 * @param {string} option
613 * The name of the option to remove.
615 unset: function(conf, sid, opt) {
616 return this.set(conf, sid, opt, null);
620 * Gets the value of the given option or the entire section object of
621 * the first found section of the specified type or the first found
622 * section of the entire configuration if no type is specfied.
624 * @param {string} config
625 * The name of the configuration to read the value from.
627 * @param {string} [type]
628 * The type of the first section to find. If it is `null`, the first
629 * section of the entire config is read, otherwise the first section
630 * matching the given type.
632 * @param {string} [option]
633 * The option name to read the value from. If the option name is
634 * omitted or `null`, the entire section is returned instead.
636 * @returns {null|string|string[]|LuCI.uci.SectionObject}
637 * - Returns a string containing the option value in case of a
639 * - Returns an array of strings containing the option values in
640 * case of `option` pointing to an UCI list.
641 * - Returns a {@link LuCI.uci.SectionObject section object} if
642 * the `option` argument has been omitted or is `null`.
643 * - Returns `null` if the config, section or option has not been
644 * found or if the corresponding configuration is not loaded.
646 get_first: function(conf, type, opt) {
649 this.sections(conf, type, function(s) {
654 return this.get(conf, sid, opt);
658 * Sets the value of the given option within the first found section
659 * of the given configuration matching the specified type or within
660 * the first section of the entire config when no type has is specified.
662 * If either config, type or option is null, or if `option` begins
663 * with a dot, the function will do nothing.
665 * @param {string} config
666 * The name of the configuration to set the option value in.
668 * @param {string} [type]
669 * The type of the first section to find. If it is `null`, the first
670 * section of the entire config is written to, otherwise the first
671 * section matching the given type is used.
673 * @param {string} option
674 * The option name to set the value for.
676 * @param {null|string|string[]} value
677 * The option value to set. If the value is `null` or an empty string,
678 * the option will be removed, otherwise it will be set or overwritten
679 * with the given value.
681 set_first: function(conf, type, opt, val) {
684 this.sections(conf, type, function(s) {
689 return this.set(conf, sid, opt, val);
693 * Removes the given option within the first found section of the given
694 * configuration matching the specified type or within the first section
695 * of the entire config when no type has is specified.
697 * This function is a convenience wrapper around
698 * `uci.set_first(config, type, option, null)`.
700 * @param {string} config
701 * The name of the configuration to set the option value in.
703 * @param {string} [type]
704 * The type of the first section to find. If it is `null`, the first
705 * section of the entire config is written to, otherwise the first
706 * section matching the given type is used.
708 * @param {string} option
709 * The option name to set the value for.
711 unset_first: function(conf, type, opt) {
712 return this.set_first(conf, type, opt, null);
716 * Move the first specified section within the given configuration
717 * before or after the second specified section.
719 * @param {string} config
720 * The configuration to move the section within.
722 * @param {string} sid1
723 * The ID of the section to move within the configuration.
725 * @param {string} [sid2]
726 * The ID of the target section for the move operation. If the
727 * `after` argument is `false` or not specified, the section named by
728 * `sid1` will be moved before this target section, if the `after`
729 * argument is `true`, the `sid1` section will be moved after this
732 * When the `sid2` argument is `null`, the section specified by `sid1`
733 * is moved to the end of the configuration.
735 * @param {boolean} [after=false]
736 * When `true`, the section `sid1` is moved after the section `sid2`,
737 * when `false`, the section `sid1` is moved before `sid2`.
739 * If `sid2` is null, then this parameter has no effect and the section
740 * `sid1` is moved to the end of the configuration instead.
743 * Returns `true` when the section was successfully moved, or `false`
744 * when either the section specified by `sid1` or by `sid2` is not found.
746 move: function(conf, sid1, sid2, after) {
747 var sa = this.sections(conf),
748 s1 = null, s2 = null;
750 sid1 = this.resolveSID(conf, sid1);
751 sid2 = this.resolveSID(conf, sid2);
753 for (var i =
0; i
< sa.length; i++) {
754 if (sa[i]['.name'] != sid1)
769 for (var i =
0; i
< sa.length; i++) {
770 if (sa[i]['.name'] != sid2)
774 sa.splice(i + !!after,
0, s1);
782 for (var i =
0; i
< sa.length; i++)
783 this.get(conf, sa[i]['.name'])['.index'] = i;
785 this.state.reorder[conf] = true;
791 * Submits all local configuration changes to the remove `ubus` api,
792 * adds, removes and reorders remote sections as needed and reloads
793 * all loaded configurations to resynchronize the local state with
794 * the remote configuration values.
796 * @returns {string[]}
797 * Returns a promise resolving to an array of configuration names which
798 * have been reloaded by the save operation.
801 var v = this.state.values,
802 n = this.state.creates,
803 c = this.state.changes,
804 d = this.state.deletes,
805 r = this.state.reorder,
812 for (var conf in n) {
813 for (var sid in n[conf]) {
819 for (var k in n[conf][sid]) {
821 r.type = n[conf][sid][k];
822 else if (k == '.create')
823 r.name = n[conf][sid][k];
824 else if (k.charAt(
0) != '.')
825 r.values[k] = n[conf][sid][k];
828 snew.push(n[conf][sid]);
829 tasks.push(self.callAdd(r.config, r.type, r.name, r.values));
836 for (var conf in c) {
837 for (var sid in c[conf])
838 tasks.push(self.callSet(conf, sid, c[conf][sid]));
844 for (var conf in d) {
845 for (var sid in d[conf]) {
846 var o = d[conf][sid];
847 tasks.push(self.callDelete(conf, sid, (o === true) ? null : o));
857 return Promise.all(tasks).then(function(responses) {
859 array
"snew" holds references to the created uci sections,
860 use it to assign the returned names of the new sections
862 for (var i =
0; i
< snew.length; i++)
863 snew[i]['.name'] = responses[i];
865 return self.reorderSections();
867 pkgs = Object.keys(pkgs);
871 return self.load(pkgs);
876 * Instructs the remote `ubus` UCI api to commit all saved changes with
877 * rollback protection and attempts to confirm the pending commit
878 * operation to cancel the rollback timer.
880 * @param {number} [timeout=
10]
881 * Override the confirmation timeout after which a rollback is triggered.
883 * @returns {Promise
<number
>}
884 * Returns a promise resolving/rejecting with the `ubus` RPC status code.
886 apply: function(timeout) {
890 if (typeof(timeout) != 'number' || timeout
< 1)
893 return self.callApply(timeout, true).then(function(rv) {
895 return Promise.reject(rv);
897 var try_deadline = date.getTime() +
1000 * timeout;
898 var try_confirm = function() {
899 return self.callConfirm().then(function(rv) {
901 if (date.getTime()
< try_deadline)
902 window.setTimeout(try_confirm,
250);
904 return Promise.reject(rv);
911 window.setTimeout(try_confirm,
1000);
916 * An UCI change record is a plain array containing the change operation
917 * name as first element, the affected section ID as second argument
918 * and an optional third and fourth argument whose meanings depend on
921 * @typedef {string[]} ChangeRecord
924 * @property {string}
0
925 * The operation name - may be one of `add`, `set`, `remove`, `order`,
926 * `list-add`, `list-del` or `rename`.
928 * @property {string}
1
929 * The section ID targeted by the operation.
931 * @property {string}
2
932 * The meaning of the third element depends on the operation.
933 * - For `add` it is type of the section that has been added
934 * - For `set` it either is the option name if a fourth element exists,
935 * or the type of a named section which has been added when the change
936 * entry only contains three elements.
937 * - For `remove` it contains the name of the option that has been
939 * - For `order` it specifies the new sort index of the section.
940 * - For `list-add` it contains the name of the list option a new value
942 * - For `list-del` it contains the name of the list option a value has
944 * - For `rename` it contains the name of the option that has been
945 * renamed if a fourth element exists, else it contains the new name
946 * a section has been renamed to if the change entry only contains
949 * @property {string}
4
950 * The meaning of the fourth element depends on the operation.
951 * - For `set` it is the value an option has been set to.
952 * - For `list-add` it is the new value that has been added to a
954 * - For `rename` it is the new name of an option that has been
959 * Fetches uncommitted UCI changes from the remote `ubus` RPC api.
962 * @returns {Promise
<Object
<string, Array
<LuCI.uci.ChangeRecord
>>>}
963 * Returns a promise resolving to an object containing the configuration
964 * names as keys and arrays of related change records as values.
966 changes: rpc.declare({
969 expect: { changes: { } }
982 <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>
988 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)
991 <script> prettyPrint();
</script>
992 <script src=
"scripts/linenumber.js"> </script>