# Class: Protocol

## LuCI.Network. Protocol

The `Network.Protocol` class serves as base for protocol specific subclasses which describe logical UCI networks defined by `config interface` sections in `/etc/config/network`.

#### new LuCI.Network.Protocol()

network.js, line 1850

### Methods

#### addDevice(device){boolean}

network.js, line 2439

  Add the given network device to the logical interface.

  Name | Type | Description
  --- | --- | ---
  `device` | LuCI.Network.Protocol | LuCI.Network.Device | LuCI.Network.WifiDevice | LuCI.Network.WifiNetwork | string | The object or device name to add to the logical interface. In case the given argument is not a string, it is resolved though the `Network.getIfnameOf()` function.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the device name has been added or `false` if any argument was invalid, if the device was already part of the logical interface or if the logical interface is virtual.

#### containsDevice(device){boolean}

network.js, line 2608

  Checks whether this logical interface contains the given device object.

  Name | Type | Description
  --- | --- | ---
  `device` | LuCI.Network.Protocol | LuCI.Network.Device | LuCI.Network.WifiDevice | LuCI.Network.WifiNetwork | string | The object or device name to check. In case the given argument is not a string, it is resolved though the `Network.getIfnameOf()` function.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` when this logical interface contains the given network device or `false` if not.

#### deleteDevice(device){boolean}

network.js, line 2466

  Remove the given network device from the logical interface.

  Name | Type | Description
  --- | --- | ---
  `device` | LuCI.Network.Protocol | LuCI.Network.Device | LuCI.Network.WifiDevice | LuCI.Network.WifiNetwork | string | The object or device name to remove from the logical interface. In case the given argument is not a string, it is resolved though the `Network.getIfnameOf()` function.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the device name has been added or `false` if any argument was invalid, if the device was already part of the logical interface or if the logical interface is virtual.

#### get(opt){null|string|Array.<string>}

network.js, line 1883

  Read the given UCI option value of this network.

  Name | Type | Description
  --- | --- | ---
  `opt` | string | The UCI option name to read.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Array.<string> | Returns the UCI option value or `null` if the requested option is not found.

#### getDevice(){LuCI.Network.Device}

network.js, line 2493

  Returns the Linux network device associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  LuCI.Network.Device | Returns a `Network.Device` class instance representing the expected Linux network device according to the configuration.

#### getDevices(){null|Array.<LuCI.Network.Device>}

network.js, line 2554

  Returns a list of network sub-devices associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  null | Array.<LuCI.Network.Device> | Returns an array of of `Network.Device` class instances representing the sub-devices attached to this logical interface or `null` if the logical interface does not support sub-devices, e.g. because it is virtual and not a bridge.

#### getDNS6Addrs(){Array.<string>}

network.js, line 2208

  Query the IPv6 DNS servers associated with the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<string> | Returns an array of IPv6 DNS servers registered by the remote protocol backend.

#### getDNSAddrs(){Array.<string>}

network.js, line 2120

  Query the IPv4 DNS servers associated with the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<string> | Returns an array of IPv4 DNS servers registered by the remote protocol backend.

#### getErrors(){Array.<string>}

network.js, line 2252

  Query interface error messages published in `ubus` runtime state.

  Interface errors are emitted by remote protocol handlers if the setup of the underlying logical interface failed, e.g. due to bad configuration or network connectivity issues.

  This function will translate the found error codes to human readable messages using the descriptions registered by `Network.registerErrorCode()` and fall back to `"Unknown error (%s)"` where `%s` is replaced by the error code in case no translation can be found.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<string> | Returns an array of translated interface error messages.

#### getExpiry(){number}

network.js, line 2003

  Get the logical interface expiry time in seconds.

  For protocols that have a concept of a lease, such as DHCP or DHCPv6, this function returns the remaining time in seconds until the lease expires.

  ##### Returns:

  Type | Description
  --- | ---
  number | Returns the amount of seconds until the lease expires or `-1` if it isn't applicable to the associated protocol.

#### getGateway6Addr(){string}

network.js, line 2188

  Query the gateway (nexthop) of the IPv6 default route associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns a string containing the IPv6 nexthop address of the associated default route or `null` if no default route was found.

#### getGatewayAddr(){string}

network.js, line 2100

  Query the gateway (nexthop) of the default route associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns a string containing the IPv4 nexthop address of the associated default route or `null` if no default route was found.

#### abstractgetI18n(){string}

network.js, line 1948

  Return a human readable description for the protcol, such as `Static address` or `DHCP client`.

  This function should be overwritten by subclasses.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the description string.

#### getIfname(){null|string}

network.js, line 1908

  Get the associared Linux network device of this network.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the name of the associated network device or `null` if it could not be determined.

#### getIP6Addr(){null|string}

network.js, line 2139

  Query the first (primary) IPv6 address of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the primary IPv6 address registered by the protocol handler in CIDR notation or `null` if no IPv6 addresses were set.

#### getIP6Addrs(){Array.<string>}

network.js, line 2161

  Query all IPv6 addresses of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<string> | Returns an array of IPv6 addresses in CIDR notation which have been registered by the protocol handler. The order of the resulting array follows the order of the addresses in `ubus` runtime information.

#### getIP6Prefix(){null|string}

network.js, line 2227

  Query the routed IPv6 prefix associated with the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the routed IPv6 prefix registered by the remote protocol handler or `null` if no prefix is present.

#### getIPAddr(){null|string}

network.js, line 2055

  Query the first (primary) IPv4 address of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the primary IPv4 address registered by the protocol handler or `null` if no IPv4 addresses were set.

#### getIPAddrs(){Array.<string>}

network.js, line 2068

  Query all IPv4 addresses of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  Array.<string> | Returns an array of IPv4 addresses in CIDR notation which have been registered by the protocol handler. The order of the resulting array follows the order of the addresses in `ubus` runtime information.

#### getL2Device(){LuCI.Network.Device}

network.js, line 2526

  Returns the layer 2 linux network device currently associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  LuCI.Network.Device | Returns a `Network.Device` class instance representing the Linux network device currently associated with the logical interface.

#### getL3Device(){LuCI.Network.Device}

network.js, line 2539

  Returns the layer 3 linux network device currently associated with this logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  LuCI.Network.Device | Returns a `Network.Device` class instance representing the Linux network device currently associated with the logical interface.

#### getMetric(){number}

network.js, line 2023

  Get the metric value of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  number | Returns the current metric value used for device and network routes spawned by the associated logical interface.

#### getName(){string}

network.js, line 1978

  Get the name of the associated logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the logical interface name, such as `lan` or `wan`.

#### getNetmask(){null|string}

network.js, line 2086

  Query the first (primary) IPv4 netmask of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the netmask of the primary IPv4 address registered by the protocol handler or `null` if no IPv4 addresses were set.

#### abstractgetOpkgPackage(){string}

network.js, line 2292

  Get the name of the opkg package providing the protocol functionality.

  This function should be overwritten by protocol specific subclasses.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the name of the opkg package required for the protocol to function, e.g. `odhcp6c` for the `dhcpv6` prototocol.

#### abstractgetProtocol(){string}

network.js, line 1934

  Get the name of this network protocol class.

  This function will be overwritten by subclasses created by `Network.registerProtocol()`.

  ##### Returns:

  Type | Description
  --- | ---
  string | Returns the name of the network protocol implementation, e.g. `static` or `dhcp`.

#### getType(){null|string}

network.js, line 1968

  Get the type of the underlying interface.

  This function actually is a convenience wrapper around `proto.get("type")` and is mainly used by other `LuCI.Network` code to check whether the interface is declared as bridge in UCI.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the value of the `type` option of the associated logical interface or `null` if no `type` option is set.

#### getUptime(){number}

network.js, line 1988

  Get the uptime of the logical interface.

  ##### Returns:

  Type | Description
  --- | ---
  number | Returns the uptime of the associated interface in seconds.

#### getZoneName(){null|string}

network.js, line 2039

  Get the requested firewall zone name of the logical interface.

  Some protocol implementations request a specific firewall zone to trigger inclusion of their resulting network devices into the firewall rule set.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the requested firewall zone name as published in the `ubus` runtime information or `null` if the remote protocol handler didn't request a zone.

#### isAlias(){null|string}

network.js, line 2380

  Checks whether this interface is an alias interface.

  Alias interfaces are interfaces layering on top of another interface and are denoted by a special `@interfacename` notation in the underlying `ifname` option.

  ##### Returns:

  Type | Description
  --- | ---
  null | string | Returns the name of the parent interface if this logical interface is an alias or `null` if it is not an alias interface.

#### isBridge(){boolean}

network.js, line 2277

  Checks whether the underlying logical interface is declared as bridge.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` when the interface is declared with `option type bridge` and when the associated protocol implementation is not marked virtual or `false` when the logical interface is no bridge.

#### isDynamic(){boolean}

network.js, line 2365

  Checks whether this logical interface is dynamic.

  A dynamic interface is an interface which has been created at runtime, e.g. as sub-interface of another interface, but which is not backed by any user configuration. Such dynamic interfaces cannot be edited but only brought down or restarted.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns a boolean indicating whether this interface is dynamic (`true`) or not (`false`).

#### isEmpty(){boolean}

network.js, line 2400

  Checks whether this logical interface is "empty", meaning that ut has no network devices attached.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if this logical interface is empty, else `false`.

#### isFloating(){boolean}

network.js, line 2349

  Checks whether this protocol is "floating".

  A "floating" protocol is a protocol which spawns its own interfaces on demand, like a virtual one but which relies on an existinf lower level interface to initiate the connection.

  An example for such a protocol is "pppoe".

  This function exists for backwards compatibility with older code but should not be used anymore.

  Deprecated
    - Yes

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns a boolean indicating whether this protocol is floating (`true`) or not (`false`).

#### abstractisInstalled(){boolean}

network.js, line 2308

  Checks whether the protocol functionality is installed.

  This function exists for compatibility with old code, it always returns `true`.

  Deprecated
    - Yes

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` if the protocol support is installed, else `false`.

#### isUp(){boolean}

network.js, line 2422

  Checks whether this logical interface is configured and running.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns `true` when the interface is active or `false` when it is not.

#### isVirtual(){boolean}

network.js, line 2328

  Checks whether this protocol is "virtual".

  A "virtual" protocol is a protocol which spawns its own interfaces on demand instead of using existing physical interfaces.

  Examples for virtual protocols are `6in4` which `gre` spawn tunnel network device on startup, examples for non-virtual protcols are `dhcp` or `static` which apply IP configuration to existing interfaces.

  This function should be overwritten by subclasses.

  ##### Returns:

  Type | Description
  --- | ---
  boolean | Returns a boolean indicating whether the underlying protocol spawns dynamic interfaces (`true`) or not (`false`).

#### set(opt, val)

network.js, line 1897

  Set the given UCI option of this network to the given value.

  Name | Type | Description
  --- | --- | ---
  `opt` | string | The name of the UCI option to set.
  `val` | null | string | Array.<string> | The value to set or `null` to remove the given option from the configuration.