Spark Plugin
Version: 1.0
Status: 
Spark plugin for Thunder framework.
Table of Contents
Introduction
Scope
This document describes purpose and functionality of the Spark plugin. It includes detailed specification about its configuration, 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
The Spark plugin provides web browsing functionality based on the Spark engine.
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 | M/O | Description |
|---|---|---|---|
| callsign | string | mandatory | Plugin instance name (default: Spark) |
| classname | string | mandatory | Class name: Spark |
| locator | string | mandatory | Library name: libThunderSpark.so |
| startmode | string | mandatory | Determines in which state the plugin should be moved to at startup of the framework |
| configuration | object | optional | ... |
| configuration?.url | string | optional | The URL that is loaded upon starting the browser |
Interfaces
This plugin implements the following interfaces:
- Browser.json (version 1.0.0) (uncompliant-extended format)
Methods
The following methods are provided by the Spark plugin:
Browser interface methods:
| Method | Description |
|---|---|
| delete | Removes contents of a directory from the persistent storage |
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 | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.path | string | mandatory | Path to directory (within the persistent storage) to delete contents of |
Result
| Name | Type | M/O | Description |
|---|---|---|---|
| result | null | mandatory | Always null (default: None) |
Errors
| Message | Description |
|---|---|
ERROR_UNKNOWN_KEY |
The given path was incorrect |
Example
Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.delete",
"params": {
"path": ".cache/wpe/disk-cache"
}
}
Response
{
"jsonrpc": "2.0",
"id": 42,
"result": null
}
Properties
The following properties are provided by the Spark plugin:
Browser interface properties:
| Property | R/W | Description |
|---|---|---|
| url | read/write | URL loaded in the browser |
| visibility | read/write | Current browser visibility |
| fps | read-only | Current number of frames per second the browser is rendering |
url property
Provides access to the URL loaded in the browser.
Also see: urlchange
Value
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | string | mandatory | URL loaded in the browser |
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | string | mandatory | URL loaded in the browser |
Errors
| Message | Description |
|---|---|
ERROR_INCORRECT_URL |
Incorrect URL given |
Example
Get Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.url"
}
Get Response
{
"jsonrpc": "2.0",
"id": 42,
"result": "https://www.google.com"
}
Set Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.url",
"params": "https://www.google.com"
}
Set Response
{
"jsonrpc": "2.0",
"id": 42,
"result": "null"
}
visibility property
Provides access to the current browser visibility.
Also see: visibilitychange
Value
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | string | mandatory | Current browser visibility (must be one of the following: hidden, visible) |
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | string | mandatory | Current browser visibility (must be one of the following: hidden, visible) |
Errors
| Message | Description |
|---|---|
ERROR_UNAVAILABLE |
Returned when the operation is unavailable |
Example
Get Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.visibility"
}
Get Response
{
"jsonrpc": "2.0",
"id": 42,
"result": "hidden"
}
Set Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.visibility",
"params": "hidden"
}
Set Response
{
"jsonrpc": "2.0",
"id": 42,
"result": "null"
}
fps property
Provides access to the current number of frames per second the browser is rendering.
This property is read-only.
Value
| Name | Type | M/O | Description |
|---|---|---|---|
| (property) | integer | mandatory | Current number of frames per second the browser is rendering |
Example
Get Request
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.fps"
}
Get Response
{
"jsonrpc": "2.0",
"id": 42,
"result": 30
}
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 Spark plugin:
Browser interface events:
| Notification | Description |
|---|---|
| urlchange | Signals a URL change in the browser |
| visibilitychange | Signals a visibility change of the browser |
| pageclosure | Notifies that the web page requests to close its window |
urlchange notification
Signals a URL change in the browser.
Notification Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.url | string | mandatory | The URL that has been loaded or requested |
| params.loaded | boolean | mandatory | Determines if the URL has just been loaded (true) or if URL change has been requested (false) (default: True) |
Example
Registration
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.register",
"params": {
"event": "urlchange",
"id": "myid"
}
}
Notification
{
"jsonrpc": "2.0",
"method": "myid.urlchange",
"params": {
"url": "https://www.google.com",
"loaded": false
}
}
The client ID parameter is passed within the notification designator, i.e.
<client-id>.urlchange.
visibilitychange notification
Signals a visibility change of the browser.
Notification Parameters
| Name | Type | M/O | Description |
|---|---|---|---|
| params | object | mandatory | ... |
| params.hidden | boolean | mandatory | Determines if the browser has been hidden (true) or made visible (false) |
Example
Registration
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.register",
"params": {
"event": "visibilitychange",
"id": "myid"
}
}
Notification
{
"jsonrpc": "2.0",
"method": "myid.visibilitychange",
"params": {
"hidden": false
}
}
The client ID parameter is passed within the notification designator, i.e.
<client-id>.visibilitychange.
pageclosure notification
Notifies that the web page requests to close its window.
Notification Parameters
This notification carries no parameters.
Example
Registration
{
"jsonrpc": "2.0",
"id": 42,
"method": "Spark.1.register",
"params": {
"event": "pageclosure",
"id": "myid"
}
}
Notification
{
"jsonrpc": "2.0",
"method": "myid.pageclosure"
}
The client ID parameter is passed within the notification designator, i.e.
<client-id>.pageclosure.