NetworkControl API

Version: 1.0.0

Status:

NetworkControl interface for Thunder framework.

(Defined with INetworkControl in INetworkControl.h)

Table of Contents

• Introduction
• Description
• Methods
• Properties
• Notifications

Introduction

Scope

This document describes purpose and functionality of the NetworkControl interface (version 1.0.0). It includes detailed specification about its methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym	Description
API	Application Programming Interface
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term	Description
callsign	The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID	Description
HTTP	HTTP specification
JSON-RPC	JSON-RPC 2.0 specification
JSON	JSON specification
Thunder	Thunder API Reference

Description

NetworkControl JSON-RPC interface.

This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

Methods

The following methods are provided by the NetworkControl interface:

NetworkControl interface methods:

Method	Description
flush	Flush and reload requested interface

flush ^method

Flush and reload requested interface.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.interface	string	mandatory	Name of the interface to be flushed

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.flush",
  "params": {
    "interface": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

Properties

The following properties are provided by the NetworkControl interface:

NetworkControl interface properties:

Property	R/W	Description
interfaces	read-only	Currently available interfaces
status	read-only	Status of requested interface
network	read/write	Network info of requested interface
dns	read/write	DNS list
up	read/write	Provides given requested interface is up or not

interfaces ^property

Provides access to the currently available interfaces.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	array	mandatory	Currently available interfaces
(property)[#]	string	mandatory	...

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.interfaces"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "..."
  ]
}

status ^property

Provides access to the status of requested interface.

This property is read-only.

The interface parameter shall be passed as the index to the property, i.e. status@<interface>.

Index

Name	Type	M/O	Description
interface	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	string	mandatory	Status of requested interface (must be one of the following: Available, Unavailable)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.status@xyz"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "Available"
}

network ^property

Provides access to the network info of requested interface.

The interface parameter shall be passed as the index to the property, i.e. network@<interface>.

Index

Name	Type	M/O	Description
interface	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	object	mandatory	Network info of requested interface
(property).value	array	mandatory	...
(property).value[#]	object	mandatory	...
(property).value[#].address	string	mandatory	IP Address
(property).value[#].defaultgateway	string	mandatory	Default Gateway
(property).value[#].mask	integer	mandatory	Network mask
(property).value[#].mode	string	mandatory	Mode of interface activation Dynamic or Static (must be one of the following: Dynamic, Static)

Name	Type	M/O	Description
(property)	array	mandatory	Info about requested interface
(property)[#]	object	mandatory	...
(property)[#].address	string	mandatory	IP Address
(property)[#].defaultgateway	string	mandatory	Default Gateway
(property)[#].mask	integer	mandatory	Network mask
(property)[#].mode	string	mandatory	Mode of interface activation Dynamic or Static (must be one of the following: Dynamic, Static)

Errors

Message	Description
ERROR_UNAVAILABLE	Failed to set/retrieve network

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.network@xyz"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "address": "...",
      "defaultgateway": "...",
      "mask": 0,
      "mode": "Dynamic"
    }
  ]
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.network@xyz",
  "params": {
    "value": [
      {
        "address": "...",
        "defaultgateway": "...",
        "mask": 0,
        "mode": "Dynamic"
      }
    ]
  }
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

dns ^property

Provides access to the DNS list.

Value

Name	Type	M/O	Description
(property)	object	mandatory	DNS list
(property).value	array	mandatory	...
(property).value[#]	string	mandatory	...

Name	Type	M/O	Description
(property)	array	mandatory	List of DNS
(property)[#]	string	mandatory	...

Errors

Message	Description
ERROR_UNAVAILABLE	Failed to set/retrieve DNS

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.dns"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "..."
  ]
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.dns",
  "params": {
    "value": [
      "..."
    ]
  }
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

up ^property

Provides access to the provides given requested interface is up or not.

The interface parameter shall be passed as the index to the property, i.e. up@<interface>.

Index

Name	Type	M/O	Description
interface	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	object	mandatory	Provides given requested interface is up or not
(property).value	boolean	mandatory	...

Name	Type	M/O	Description
(property)	boolean	mandatory	Up/Down requested interface

Errors

Message	Description
ERROR_UNAVAILABLE	Failed to set/retrieve UP

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.up@xyz"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": false
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.up@xyz",
  "params": {
    "value": false
  }
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the NetworkControl interface:

NetworkControl interface events:

Notification	Description
update	Signal interface update

update ^notification

Signal interface update.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.interfacename	string	mandatory	Name of the interface where an update occured

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "update",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.update",
  "params": {
    "interfacename": "..."
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.update.