NetworkTools API
Version: 1.0.0
Status: 
NetworkTools interface for Thunder framework.
(Defined with INetworkTools in INetworkTools.h)
Table of Contents
Introduction
Scope
This document describes purpose and functionality of the NetworkTools interface (version 1.0.0). It includes detailed specification about its methods provided and notifications sent.
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
NetworkTools JSON-RPC interface.
Methods
The following methods are provided by the NetworkTools interface:
Built-in methods:
| Method | Description |
|---|---|
| exists | Checks if a JSON-RPC method or property exists |
| register | Registers for an asynchronous JSON-RPC notification |
| unregister | Unregisters from an asynchronous JSON-RPC notification |
NetworkTools interface methods:
| Method | Description |
|---|---|
| ping | Ping the given destination with ICMP packages |
| traceRoute | TraceRoute to the given destination with ICMP packages |
exists method
Checks if a JSON-RPC method or property exists.
Description
This method will return True for the following methods/properties: exists, register, unregister, ping, traceRoute.
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.method | string | mandatory | Name of the method or property to look up |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | boolean | mandatory | Denotes if the method exists or not |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.exists",
"params": {
"method": "methodName"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": false
}
register method
Registers for an asynchronous JSON-RPC notification.
Description
This method supports the following event names: report.
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.event | string | mandatory | Name of the notification to register for |
| params.id | string | mandatory | Client identifier |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null |
Errors
| Message | Description |
|---|---|
ERROR_FAILED_REGISTERED |
Failed to register for the notification (e.g. already registered) |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.register",
"params": {
"event": "eventName",
"id": "myapp"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
unregister method
Unregisters from an asynchronous JSON-RPC notification.
Description
This method supports the following event names: report.
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.event | string | mandatory | Name of the notification to register for |
| params.id | string | mandatory | Client identifier |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null |
Errors
| Message | Description |
|---|---|
ERROR_FAILED_UNREGISTERED |
Failed to unregister from the notification (e.g. not yet registered) |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.unregister",
"params": {
"event": "eventName",
"id": "myapp"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
ping method
Ping the given destination with ICMP packages.
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.destination | string | mandatory | The node id of the host we would like to ping (ipv4/ipv6) |
| params.timeOutInSeconds | integer | mandatory | Time out, continue to ping for the given duration |
| params.count | integer | mandatory | Maximum number of pings to send |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null |
Errors
| Message | Description |
|---|---|
ERROR_NONE, |
ERROR_INPROGRES means an icmp check is already in progress . |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.ping",
"params": {
"destination": "...",
"timeOutInSeconds": 0,
"count": 0
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
traceRoute method
TraceRoute to the given destination with ICMP packages.
Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.destination | string | mandatory | The node id of the host we would like to ping (ipv4/ipv6) |
| params.timeOutInSeconds | integer | mandatory | Time out, continue to ping for the given duration |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null |
Errors
| Message | Description |
|---|---|
ERROR_NONE, |
ERROR_INPROGRES means an icmp check is already in progress |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.traceRoute",
"params": {
"destination": "...",
"timeOutInSeconds": 0
}
}
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 NetworkTools interface:
NetworkTools interface events:
| Notification | Description |
|---|---|
| report | Signals an message from a given host |
report notification
Signals an message from a given host.
Notification Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.source | string | mandatory | The NodeId of the system that send the metadta presented in the next field |
| params.metadata | string | mandatory | Depending on the tool started, this JSON string will contain additional information on this notification |
Example
Registration
{
"jsonrpc": "2.0",
"id": 42,
"method": "<callsign>.1.register",
"params": {
"event": "report",
"id": "myid"
}
}
Notification
{
"jsonrpc": "2.0",
"method": "myid.report",
"params": {
"source": "...",
"metadata": "..."
}
}
The client ID parameter is passed within the notification designator, i.e.
<client-id>.report.