Class: uci

Methods

add(conf, type, name){string}

uci.js, line 289

Adds a new section of the given type to the given configuration, optionally named according to the given name.

Name	Type	Description
conf	string	The name of the configuration to add the section to.
type	string	The type of the section to add.
name	string	optional The name of the section to add. If the name is omitted, an anonymous section will be added instead.

Returns:

Type	Description
string	Returns the section ID of the newly added section which is equivalent to the given name for non-anonymous sections.

apply(timeout){Promise.<number>}

uci.js, line 974

Instructs the remote ubus UCI api to commit all saved changes with rollback protection and attempts to confirm the pending commit operation to cancel the rollback timer.

Name	Type	Default	Description
timeout	number	10	optional Override the confirmation timeout after which a rollback is triggered.

Returns:

Type	Description
Promise.<number>	Returns a promise resolving/rejecting with the ubus RPC status code.

changes(){Promise.<Object.<string, Array.<LuCI.uci.ChangeRecord>>>}

uci.js, line 1054

Fetches uncommitted UCI changes from the remote ubus RPC api.

Returns:

Type	Description
Promise.<Object.<string, Array.<LuCI.uci.ChangeRecord>>>	Returns a promise resolving to an object containing the configuration names as keys and arrays of related change records as values.

clone(conf, type, srcsid, put_next, name){string}

uci.js, line 329

Clones an existing section of the given type to the given configuration, optionally named according to the given name.

Name	Type	Description
conf	string	The name of the configuration into which to clone the section.
type	string	The type of the section to clone.
srcsid	string	The source section id to clone.
put_next	boolean	optional Whether to put the cloned item next (true) or last (false: default).
name	string	optional The name of the new cloned section. If the name is omitted, an anonymous section will be created instead.

Returns:

Type	Description
string	Returns the section ID of the newly cloned section which is equivalent to the given name for non-anonymous sections.

createSID(conf){string}

uci.js, line 103

Generates a new, unique section ID for the given configuration.

Note that the generated ID is temporary, it will get replaced by an identifier in the form cfgXXXXXX once the configuration is saved by the remote ubus UCI api.

Name	Type	Description
conf	string	The configuration to generate the new section ID for.

Returns:

Type	Description
string	A newly generated, unique section ID in the form newXXXXXX where X denotes a hexadecimal digit.

get(conf, sid, opt){null|string|Array.<string>|LuCI.uci.SectionObject}

uci.js, line 506

Gets the value of the given option within the specified section of the given configuration or the entire section object if the option name is omitted.

Name	Type	Description
conf	string	The name of the configuration to read the value from.
sid	string	The name or ID of the section to read.
opt	string	optional The option name to read the value from. If the option name is omitted or null, the entire section is returned instead.

Returns:

Type	Description
null | string | Array.<string> | LuCI.uci.SectionObject	Returns a string containing the option value in case of a plain UCI option. Returns an array of strings containing the option values in case of option pointing to an UCI list. Returns a section object if the option argument has been omitted or is null. Returns null if the config, section or option has not been found or if the corresponding configuration is not loaded.

get_bool(conf, sid, opt){boolean}

uci.js, line 734

A special case of get that always returns either true or false.

Many configuration files contain boolean settings, such as enabled or advanced_mode, where there is no consistent definition for the values. This function allows users to enter any of the values "yes", "on", "true" or 1 in their config files and we return the expected boolean result.

Character case is not significant, so for example, any of "YES", "Yes" or "yes" will be interpreted as a true value.

Name	Type	Description
conf	string	The name of the configuration to read.
sid	string	The name or ID of the section to read.
opt	string	optional The option name from which to read the value. If the option name is omitted or null, the value false is returned.

Returns:

Type	Description
boolean	Returns boolean true if the configuration value is defined and looks like a true value, otherwise returns false.

get_first(conf, type, opt){null|string|Array.<string>|LuCI.uci.SectionObject}

uci.js, line 697

Gets the value of the given option or the entire section object of the first found section of the specified type or the first found section of the entire configuration if no type is specified.

Name	Type	Description
conf	string	The name of the configuration to read the value from.
type	string	optional The type of the first section to find. If it is null, the first section of the entire config is read, otherwise the first section matching the given type.
opt	string	optional The option name to read the value from. If the option name is omitted or null, the entire section is returned instead.

Returns:

Type	Description
null | string | Array.<string> | LuCI.uci.SectionObject	Returns a string containing the option value in case of a plain UCI option. Returns an array of strings containing the option values in case of option pointing to an UCI list. Returns a section object if the option argument has been omitted or is null. Returns null if the config, section or option has not been found or if the corresponding configuration is not loaded.

load(packages){Promise.<Array.<string>>}

uci.js, line 225

Loads the given UCI configurations from the remote ubus api.

Loaded configurations are cached and only loaded once. Subsequent load operations of the same configurations will return the cached data.

To force reloading a configuration, it has to be unloaded with uci.unload() first.

Name	Type	Description
packages	string | Array.<string>	The name of the configuration or an array of configuration names to load.

Returns:

Type	Description
Promise.<Array.<string>>	Returns a promise resolving to the names of the configurations that have been successfully loaded.

move(conf, sid1, sid2, after){boolean}

uci.js, line 829

Move the first specified section within the given configuration before or after the second specified section.

Name	Type	Default	Description
conf	string		The configuration to move the section within.
sid1	string		The ID of the section to move within the configuration.
sid2	string		optional The ID of the target section for the move operation. If the after argument is false or not specified, the section named by sid1 will be moved before this target section, if the after argument is true, the sid1 section will be moved after this section. When the sid2 argument is null, the section specified by sid1 is moved to the end of the configuration.
after	boolean	false	optional When true, the section sid1 is moved after the section sid2, when false, the section sid1 is moved before sid2. If sid2 is null, then this parameter has no effect and the section sid1 is moved to the end of the configuration instead.

Returns:

Type	Description
boolean	Returns true when the section was successfully moved, or false when either the section specified by sid1 or by sid2 is not found.

remove(conf, sid)

uci.js, line 361

Removes the section with the given ID from the given configuration.

Name	Type	Description
conf	string	The name of the configuration to remove the section from.
sid	string	The ID of the section to remove.

resolveSID(conf, sid){string|null}

uci.js, line 134

Resolves a given section ID in extended notation to the internal section ID value.

Name	Type	Description
conf	string	The configuration to resolve the section ID for.
sid	string	The section ID to resolve. If the ID is in the form @typename[#], it will get resolved to an internal anonymous ID in the forms cfgXXXXXX/newXXXXXX or to the name of a section in case it points to a named section. When the given ID is not in extended notation, it will be returned as-is.

Returns:

Type	Description
string | null	Returns the resolved section ID or the original given ID if it was not in extended notation. Returns null when an extended ID could not be resolved to existing section ID.

save(){Array.<string>}

uci.js, line 884

Submits all local configuration changes to the remove ubus api, adds, removes and reorders remote sections as needed and reloads all loaded configurations to resynchronize the local state with the remote configuration values.

Returns:

Type	Description
Array.<string>	Returns a promise resolving to an array of configuration names which have been reloaded by the save operation.

sections(conf, type, cb){Array.<LuCI.uci.SectionObject>}

uci.js, line 447

Enumerates the sections of the given configuration, optionally filtered by type.

Name	Type	Description
conf	string	The name of the configuration to enumerate the sections for.
type	string	optional Enumerate only sections of the given type. If omitted, enumerate all sections.
cb	LuCI.uci~sectionsFn	optional An optional callback to invoke for each enumerated section.

Returns:

Type	Description
Array.<LuCI.uci.SectionObject>	Returns a sorted array of the section objects within the given configuration, filtered by type, if a type has been specified.

set(conf, sid, opt, val)

uci.js, line 591

Sets the value of the given option within the specified section of the given configuration.

If either config, section or option is null, or if option begins with a dot, the function will do nothing.

Name	Type	Description
conf	string	The name of the configuration to set the option value in.
sid	string	The name or ID of the section to set the option value in.
opt	string	The option name to set the value for.
val	null | string | Array.<string>	The option value to set. If the value is null or an empty string, the option will be removed, otherwise it will be set or overwritten with the given value.

set_first(conf, type, opt, val)

uci.js, line 765

Sets the value of the given option within the first found section of the given configuration matching the specified type or within the first section of the entire config when no type has is specified.

If either config, type or option is null, or if option begins with a dot, the function will do nothing.

Name	Type	Description
conf	string	The name of the configuration to set the option value in.
type	string	optional The type of the first section to find. If it is null, the first section of the entire config is written to, otherwise the first section matching the given type is used.
opt	string	The option name to set the value for.
val	null | string | Array.<string>	The option value to set. If the value is null or an empty string, the option will be removed, otherwise it will be set or overwritten with the given value.

unload(packages)

uci.js, line 257

Unloads the given UCI configurations from the local cache.

Name	Type	Description
packages	string | Array.<string>	The name of the configuration or an array of configuration names to unload.

unset(conf, sid, opt)

uci.js, line 666

Remove the given option within the specified section of the given configuration.

This function is a convenience wrapper around uci.set(config, section, option, null).

Name	Type	Description
conf	string	The name of the configuration to remove the option from.
sid	string	The name or ID of the section to remove the option from.
opt	string	The name of the option to remove.

unset_first(conf, type, opt)

uci.js, line 794

Removes the given option within the first found section of the given configuration matching the specified type or within the first section of the entire config when no type has is specified.

This function is a convenience wrapper around uci.set_first(config, type, option, null).

Name	Type	Description
conf	string	The name of the configuration to set the option value in.
type	string	optional The type of the first section to find. If it is null, the first section of the entire config is written to, otherwise the first section matching the given type is used.
opt	string	The option name to set the value for.

Type Definitions

LuCI.uci.ChangeRecordArray.<string>

An UCI change record is a plain array containing the change operation name as first element, the affected section ID as second argument and an optional third and fourth argument whose meanings depend on the operation.

Properties:

Name	Type	Description
0	string	The operation name - may be one of add, set, remove, order, list-add, list-del or rename.
1	string	The section ID targeted by the operation.
2	string	The meaning of the third element depends on the operation. For add it is type of the section that has been added For set it either is the option name if a fourth element exists, or the type of a named section which has been added when the change entry only contains three elements. For remove it contains the name of the option that has been removed. For order it specifies the new sort index of the section. For list-add it contains the name of the list option a new value has been added to. For list-del it contains the name of the list option a value has been removed from. For rename it contains the name of the option that has been renamed if a fourth element exists, else it contains the new name a section has been renamed to if the change entry only contains three elements.
4	string	The meaning of the fourth element depends on the operation. For set it is the value an option has been set to. For list-add it is the new value that has been added to a list option. For rename it is the new name of an option that has been renamed.

LuCI.uci.SectionObjectObject.<string, (boolean|number|string|Array.<string>)>

A section object represents the options and their corresponding values enclosed within a configuration section, as well as some additional meta data such as sort indexes and internal ID.

Any internal metadata fields are prefixed with a dot which isn't an allowed character for normal option names.

Properties:

Name	Type	Description
.anonymous	boolean	The .anonymous property specifies whether the configuration is anonymous (true) or named (false).
.index	number	The .index property specifies the sort order of the section.
.name	string	The .name property holds the name of the section object. It may be either an anonymous ID in the form cfgXXXXXX or newXXXXXX with X being a hexadecimal digit or a string holding the name of the section.
.type	string	The .type property contains the type of the corresponding uci section.
*	string | Array.<string>	A section object may contain an arbitrary number of further properties representing the uci option enclosed in the section. All option property names will be in the form [A-Za-z0-9_]+ and either contain a string value or an array of strings, in case the underlying option is an UCI list.

sectionsFn(section, sid)

uci.js, line 415

The sections callback is invoked for each section found within the given configuration and receives the section object and its associated name as arguments.

Name	Type	Description
section	LuCI.uci.SectionObject	The section object.
sid	string	The name or ID of the section.