Skip to content

Latest commit

 

History

History
867 lines (671 loc) · 23.4 KB

ControllerPlugin.md

File metadata and controls

867 lines (671 loc) · 23.4 KB
Raw

Controller Plugin

Version: 1.0

Status: ⚫⚫⚫

Controller plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the Controller plugin. It includes detailed specification of its configuration, methods and properties provided, as well as notifications sent.

Case Sensitivity

All identifiers on the interface 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
FQDN Fully Qualified Domain Name
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON
SSDP Simple Service Discovery Protocol
URL Uniform Resource Locator

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

The Controller plugin controls (activates and deactivates) the configured plugins. The plugin is part of the framework and cannot be activated or deactivated itself, thus as well cannot not be unloaded.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string (optional) Instance name of the plugin (default: Controller)
autostart boolean (optional) Determines if the plugin is to be started along with the framework (always true as Controller is a part of the framework)
configuration object (optional) Custom plugin configuration:
configuration?.downloadstore string (optional) Path within persistent storage to hold file downloads
configuration?.ttl number (optional) TTL to be set on the broadcast package for framework discovery in the network (default: 1)
configuration?.resumes array (optional) List of callsigns that have an IStateControl interface and need a resume at startup
configuration?.resumes[#] string (optional) Plugin callsign
configuration?.subsystems array (optional) List of subsystems configured for the system
configuration?.subsystems[#] string (optional) Subsystem name

Methods

The following methods are provided by the Controller plugin:

Controller interface methods:

Method Description
activate Activates a plugin
deactivate Deactivates a plugin
startdiscovery Starts the network discovery
storeconfig Stores the configuration
delete Removes contents of a directory from the persistent storage
harakiri Reboots the device

activate method

Activates a plugin

Description

Use this method to activate a plugin, i.e. move from Deactivated, via Activating to Activated state. If a plugin is in the Activated state, it can handle JSON-RPC requests that are coming in. The plugin is loaded into memory only if it gets activated.

Also see: statechange

Parameters

Name Type Description
params object
params.callsign string Plugin callsign

Result

Name Type Description
result null Always null

Errors

Code Message Description
31 ERROR_PENDING_CONDITIONS The plugin will be activated once its activation preconditions are met
12 ERROR_INPROGRESS The plugin is currently being activated
22 ERROR_UNKNOWN_KEY The plugin does not exist
6 ERROR_OPENING_FAILED Failed to activate the plugin
5 ERROR_ILLEGAL_STATE Current state of the plugin does not allow activation
24 ERROR_PRIVILEGED_REQUEST Activation of the plugin is not allowed (e.g. Controller)

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.activate", 
    "params": {
        "callsign": "DeviceInfo"
    }
}

Response

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

deactivate method

Deactivates a plugin

Description

Use this method to deactivate a plugin, i.e. move from Activated, via Deactivating to Deactivated state. If a plugin is Deactivated, the actual plugin (.so) is no longer loaded into the memory of the process. In a deactivated state, the plugin will not respond to any JSON-RPC requests.

Also see: statechange

Parameters

Name Type Description
params object
params.callsign string Callsign of the plugin

Result

Name Type Description
result null Always null

Errors

Code Message Description
12 ERROR_INPROGRESS The plugin is currently being deactivated
22 ERROR_UNKNOWN_KEY The plugin does not exist
5 ERROR_ILLEGAL_STATE Current state of the plugin does not allow deactivation
19 ERROR_CLOSING_FAILED Failed to activate the plugin
24 ERROR_PRIVILEGED_REQUEST Deactivation of the plugin is not allowed (e.g. Controller)

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.deactivate", 
    "params": {
        "callsign": "DeviceInfo"
    }
}

Response

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

startdiscovery method

Starts the network discovery

Description

Use this method to initiate SSDP network discovery process.

Parameters

Name Type Description
params object
params.ttl number TTL (time to live) parameter for SSDP discovery

Result

Name Type Description
result null Always null

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.startdiscovery", 
    "params": {
        "ttl": 1
    }
}

Response

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

storeconfig method

Stores the configuration

Description

Use this method to save the current configuration to persistent memory.

Parameters

This method takes no parameters.

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed to store the configuration

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.storeconfig"
}

Response

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

delete method

Removes contents of a directory from the persistent storage

Description

Use this method to recursively delete contents of a directory

Parameters

Name Type Description
params object
params.path string Path to directory (within the persistent storage) to delete contents of

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The given path was incorrect
24 ERROR_PRIVILEGED_REQUEST The path points outside of persistent directory or some files/directories couldn't have been deleted

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.delete", 
    "params": {
        "path": "test/test.txt"
    }
}

Response

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

harakiri method

Reboots the device

Description

Use this method to reboot the device. Depending on the device, this call may not generate a response.

Parameters

This method takes no parameters.

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Rebooting procedure is not available on the device
24 ERROR_PRIVILEGED_REQUEST Insufficient privileges to reboot the device
1 ERROR_GENERAL Failed to reboot the device

Example

Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.harakiri"
}

Response

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

Properties

The following properties are provided by the Controller plugin:

Controller interface properties:

Property Description
status RO Information about plugins, including their configurations
links RO Information about active connections
processinfo RO Information about the framework process
subsystems RO Status of the subsystems
discoveryresults RO SSDP network discovery results
environment RO Value of an environment variable
configuration Configuration object of a service

status property

Provides access to the information about plugins, including their configurations.

This property is read-only.

Value

Name Type Description
(property) array A list of loaded plugins
(property)[#] object (a plugin entry)
(property)[#].callsign string Instance name of the plugin
(property)[#].locator string Library name
(property)[#].classname string Class name
(property)[#].autostart string Determines if the plugin is to be started automatically along with the framework
(property)[#]?.precondition array (optional) List of subsystems the plugin depends on
(property)[#]?.precondition[#] string (optional) (a subsystem entry) (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption,, Graphics, WebSource, Streaming)
(property)[#]?.configuration object (optional) Custom configuration properties of the plugin
(property)[#].state string State of the plugin (must be one of the following: Deactivated, Deactivation, Activated, Activation, Suspended, Resumed, Precondition)
(property)[#].processedrequests number Number of API requests that have been processed by the plugin
(property)[#].processedobjects number Number of objects that have been processed by the plugin
(property)[#].observers number Number of observers currently watching the plugin (WebSockets)
(property)[#]?.module string (optional) Name of the plugin from a module perspective (used e.g. in tracing)
(property)[#]?.hash string (optional) SHA256 hash identifying the sources from which this plugin was build

The callsign shall be passed as the index to the property, e.g. Controller.1.status@DeviceInfo. If the callsign is omitted, then status of all plugins is returned.

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The plugin does not exist

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.status@DeviceInfo"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": [
        {
            "callsign": "DeviceInfo", 
            "locator": "libWPEFrameworkDeviceInfo", 
            "classname": "DeviceInfo", 
            "autostart": "True", 
            "precondition": [
                "Platform"
            ], 
            "configuration": {}, 
            "state": "Activated", 
            "processedrequests": 2, 
            "processedobjects": 0, 
            "observers": 0, 
            "module": "Plugin_DeviceInfo", 
            "hash": "custom"
        }
    ]
}

links property

Provides access to the information about active connections.

This property is read-only.

Value

Name Type Description
(property) array List of active connections
(property)[#] object (a connection entry)
(property)[#].remote string IP address (or FQDN) of the other side of the connection
(property)[#].state string State of the link (must be one of the following: WebServer, WebSocket, RawSocket, Closed, Suspended)
(property)[#].activity boolean Denotes if there was any activity on this connection
(property)[#].id number A unique number identifying the connection
(property)[#]?.name string (optional) Name of the connection

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.links"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": [
        {
            "remote": "localhost:52116", 
            "state": "RawSocket", 
            "activity": false, 
            "id": 1, 
            "name": "Controller"
        }
    ]
}

processinfo property

Provides access to the information about the framework process.

This property is read-only.

Value

Name Type Description
(property) object Information about the framework process
(property).threads array Thread pool
(property).threads[#] number (a thread entry)
(property).pending number Pending requests
(property).occupation number Pool occupation

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.processinfo"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": {
        "threads": [
            0
        ], 
        "pending": 0, 
        "occupation": 2
    }
}

subsystems property

Provides access to the status of the subsystems.

This property is read-only.

Value

Name Type Description
(property) array Status of the subsystems
(property)[#] object
(property)[#].subsystem string Subsystem name (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption,, Graphics, WebSource, Streaming)
(property)[#].active boolean Denotes whether the subsystem is active (true)

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.subsystems"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": [
        {
            "subsystem": "Platform", 
            "active": true
        }
    ]
}

discoveryresults property

Provides access to the SSDP network discovery results.

This property is read-only.

Value

Name Type Description
(property) array List of network discovery results
(property)[#] object (a discovery result entry)
(property)[#].locator string
(property)[#].latency number
(property)[#].model string
(property)[#].secure boolean

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.discoveryresults"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": [
        {
            "locator": "", 
            "latency": 0, 
            "model": "", 
            "secure": true
        }
    ]
}

environment property

Provides access to the value of an environment variable.

This property is read-only.

Value

Name Type Description
(property) string Value of an environment variable

The variable shall be passed as the index to the property, e.g. Controller.1.environment@SHELL.

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The variable is not defined

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.environment@SHELL"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": "/bin/sh"
}

configuration property

Provides access to the configuration object of a service.

Value

Name Type Description
(property) object The configuration JSON object

The callsign shall be passed as the index to the property, e.g. Controller.1.configuration@WebKitBrowser.

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY The service does not exist
1 ERROR_GENERAL Failed to update the configuration

Example

Get Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.configuration@WebKitBrowser"
}

Get Response

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "result": {}
}

Set Request

{
    "jsonrpc": "2.0", 
    "id": 1234567890, 
    "method": "Controller.1.configuration@WebKitBrowser", 
    "params": {}
}

Set Response

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

Notifications

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

The following events are provided by the Controller plugin:

Controller interface events:

Event Description
all Signals each and every event in the system
statechange Signals a plugin state change
subsystemchange Signals a subsystem state change

all event

Signals each and every event in the system. The Controller plugin is an aggregator of all the events triggered by a specific plugin. All notifications send by any plugin are forwarded over the Controller socket as an event.

Parameters

Name Type Description
params object
params.callsign string Callsign of the originator plugin of the event
params.data object Object that was broadcasted as an event by the originator plugin

Example

{
    "jsonrpc": "2.0", 
    "method": "client.events.1.all", 
    "params": {
        "callsign": "WebKitBrowser", 
        "data": {}
    }
}

statechange event

Signals a plugin state change

Parameters

Name Type Description
params object
params.callsign string Callsign of the plugin that changed state
params.state string State of the plugin (must be one of the following: Deactivated, Deactivation, Activated, Activation, Suspended, Resumed, Precondition)
params.reason string Cause of the state change (must be one of the following: Requested, Automatic, Failure, MemoryExceeded, Startup, Shutdown)

Example

{
    "jsonrpc": "2.0", 
    "method": "client.events.1.statechange", 
    "params": {
        "callsign": "WebKitBrowser", 
        "state": "Activated", 
        "reason": "Requested"
    }
}

subsystemchange event

Signals a subsystem state change

Parameters

Name Type Description
params array
params[#] object
params[#].subsystem string Subsystem name (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption,, Graphics, WebSource, Streaming)
params[#].active boolean Denotes whether the subsystem is active (true)

Example

{
    "jsonrpc": "2.0", 
    "method": "client.events.1.subsystemchange", 
    "params": [
        {
            "subsystem": "Platform", 
            "active": true
        }
    ]
}