Class: uci

Source: uci.js, line 19

Methods

add(conf, type, nameopt) → {string}

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

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 295

Returns:

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

Type:: string

apply(timeoutopt) → {Promise.<number>}

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.

Parameters:

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

Source: uci.js, line 991

Returns:

Returns a promise resolving/rejecting with the ubus RPC status code.

Type:: Promise.<number>

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

Fetches uncommitted UCI changes from the remote ubus RPC api.

Source: uci.js, line 1071

Returns:

Returns a promise resolving to an object containing the configuration names as keys and arrays of related change records as values.

Type:: Promise.<Object.<string, Array.<LuCI.uci.ChangeRecord>>>

clone(conf, type, srcsid, put_nextopt, nameopt) → {string}

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

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 335

Returns:

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

Type:: string

createSID(conf) → {string}

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.

Parameters:

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

Source: uci.js, line 109

Returns:

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

Type:: string

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

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.

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 514

Returns:

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.

Type:: null | string | Array.<string> | LuCI.uci.SectionObject

get_bool(conf, type, optopt) → {boolean}

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", "enabled" 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.

Parameters:

Name	Type	Attributes	Description
`conf`	string		The name of the configuration to read.
`type`	string		The section type 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.

Source: uci.js, line 748

Returns:

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

See the Developers Guide for more.

Type:: boolean

get_first(conf, typeopt, optopt) → {null|string|Array.<string>|LuCI.uci.SectionObject}

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.

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 706

Returns:

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.

Type:: null | string | Array.<string> | LuCI.uci.SectionObject

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

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.

Parameters:

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

Source: uci.js, line 231

Returns:

Returns a promise resolving to the names of the configurations that have been successfully loaded.

Type:: Promise.<Array.<string>>

move(conf, sid1, sid2opt, afteropt) → {boolean}

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

Parameters:

Name	Type	Attributes	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	<optional>	false	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.

Source: uci.js, line 846

Returns:

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

Type:: boolean

remove(conf, sid)

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

Parameters:

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

Source: uci.js, line 367

resolveSID(conf, sid) → {string|null}

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

Parameters:

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.

Source: uci.js, line 140

Returns:

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.

Type:: string | null

save() → {Array.<string>}

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.

Source: uci.js, line 902

Returns:

Returns a promise resolving to an array of configuration names which have been reloaded by the save operation.

Type:: Array.<string>

sections(conf, typeopt, cbopt) → {Array.<LuCI.uci.SectionObject>}

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

Parameters:

Name	Type	Attributes	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.sections	<optional>	An optional callback to invoke for each enumerated section.

Source: uci.js, line 455

Returns:

Returns a sorted array of the section objects within the given configuration, filtered by type, if a type has been specified.

Type:: Array.<LuCI.uci.SectionObject>

set(conf, sid, opt, val)

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.

Parameters:

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.

Source: uci.js, line 599

set_first(conf, typeopt, opt, val) → {null}

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.

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 780

Returns:

Type:: null

unload(packages)

Unloads the given UCI configurations from the local cache.

Parameters:

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

Source: uci.js, line 263

unset(conf, sid, opt) → {null}

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).

Parameters:

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.

Source: uci.js, line 675

Returns:

Type:: null

unset_first(conf, typeopt, opt) → {null}

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).

Parameters:

Name	Type	Attributes	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.

Source: uci.js, line 811

Returns:

Type:: null

Type Definitions

ChangeRecord

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.

Type:

Array.<string>

Properties

Name	Type	Attributes	Description
`operation`	string		The operation name - may be one of `add`, `set`, `remove`, `order`, `list-add`, `list-del` or `rename`.
`section_id`	string		The section ID targeted by the operation.
`parameter`	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.
`value`	string	<optional>	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.

Source: uci.js, line 1020

SectionObject

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.

Type:

Object.<string, (boolean|number|string|Array.<string>)>

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.

Source: uci.js, line 386

sections(section, sid)

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

Parameters:

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

Source: uci.js, line 423