Browser API

Version: 1.0.0

Status:

Browser interface for Thunder framework.

(Defined by Browser.json)

Table of Contents

• Introduction
• Description
• Methods
• Properties
• Notifications

Introduction

Scope

This document describes purpose and functionality of the Browser 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

Browser JSON-RPC interface.

Methods

The following methods are provided by the Browser interface:

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": "<callsign>.1.delete",
  "params": {
    "path": ".cache/wpe/disk-cache"
  }
}

Response

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

Properties

The following properties are provided by the Browser interface:

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": "<callsign>.1.url"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "https://www.google.com"
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.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": "<callsign>.1.visibility"
}

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.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": "<callsign>.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 Browser interface:

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": "<callsign>.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": "<callsign>.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": "<callsign>.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.