DIAL Server Plugin

Version: 1.0

Status: ⚫⚫⚪

DIALServer plugin for Thunder framework.

Introduction

Scope

This document describes purpose and functionality of the DIALServer plugin. It includes detailed specification about its configuration, properties 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
DIAL	Discovery and Launch
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON
REST	Representational State Transfer
SSDP	Simple Service Discovery Protocol

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

Term	Description
Controller	An internal plugin that allows activating and deactivating of services/plugins configured for use in the framework.
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
DIAL	DIAL protocol specification
HTTP	HTTP specification
JSON-RPC	JSON-RPC 2.0 specification
JSON	JSON specification
Thunder	Thunder API Reference

Description

The DIAL Server plugin implements the server side of the DIAL protocol, allowing second-screen devices discovering and launching applications on a first-screen device, utilizing SSDP protocol and RESTful API. For more invormation about the DIAL protocol please refer to [DIAL].

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	Plugin instance name (default: DIALServer)
classname	string	Class name: DIALServer
locator	string	Library name: libThunderDIALServer.so
startmode	string	Determines if the plugin shall be started automatically along with the framework
configuration	object	Server configuration
configuration.name	string	User-friendly name of the device
configuration.model	string	Name of the device model
configuration.description	string	Short description of the device
configuration?.modelnumber	string	^(optional) Device model number
configuration?.modelurl	string	^(optional) URL to device model website
configuration.manufacturer	string	Name of the device manufacturer
configuration?.manufacturerurl	string	^(optional) URL to manufacturer website
configuration?.serialnumber	string	^(optional) Device serial number
configuration?.upc	string	^(optional) Device UPC barcode number (Universal Product Code)
configuration?.interface	string	^(optional) Server interface IP and port (default: SSDP multicast address and port)
configuration?.webserver	string	^(optional) Callsign of a service implementing the web server functionality (default: WebServer)
configuration?.switchboard	string	^(optional) Callsign of a service implementing the switchboard functionality (default: SwitchBoard). If defined and the service is available then start/stop requests will be relayed to the SwitchBoard rather than handled by the Controller directly. This is used only in non-passive mode
configuration.apps	array	List of supported applications
configuration.apps[#]	object	(an application definition)
configuration.apps[#].name	string	Name of the application
configuration.apps[#]?.handler	string	^(optional) Name of the application handler. If not defined then name will be used instead
configuration.apps[#]?.callsign	string	^(optional) Callsign of the service implementing the application. If defined and the service is available then the Controller will be used to unconditionally start/stop the application by activating/deactivating its service directly (active mode), or by the SwitchBoard if selected and available (switchboard mode). If not defined then these operations will be handed over to JavaScript, by sending a notification and using handler (or name) property to identify the application (passive mode)
configuration.apps[#]?.url	string	^(optional) A URL related to the application
configuration.apps[#]?.allowstop	boolean	^(optional) Denotes if the application can be stopped (true) or not (false, default)

Interfaces

This plugin implements the following interfaces:

DIALServer.json (version 1.0.0) (uncompliant-extended format)

Properties

The following properties are provided by the DIALServer plugin:

DIALServer interface properties:

Property	Description
state	Current application running state

state ^property

Provides access to the current application running state.

Description

This property can be used to update the running status of an un-managed application (i.e. running in passive mode). For DIALServer-managed applications this property shall be considered read-only.

Value

Name	Type	Description
(property)	string	Current application running state (must be one of the following: Stopped, Started, Hidden)

The application name argument shall be passed as the index to the property, e.g. DIALServer.1.state@YouTube.

Result

Name	Type	Description
result	string	(must be one of the following: Stopped, Started, Hidden)

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	Specified application does not exist
5	`ERROR_ILLEGAL_STATE`	Specified application is running in active mode

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.state@YouTube"
}

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.state@YouTube",
  "params": "Stopped"
}

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 DIALServer plugin:

DIALServer interface events:

Event	Description
start	Signals that application launch (or show if previously hidden) was requested over DIAL
stop	Signals that application stop was requested over DIAL
hide	Signals that application hide was requested over DIAL
^deprecated show	Signals that application show was requested over DIAL
^deprecated change	Signals that application URL change was requested over DIAL

start ^event

Signals that application launch (or show if previously hidden) was requested over DIAL.

Description

This event is sent out only for un-managed applications (i.e. in passive mode).

Parameters

Name	Type	Description
params	object
params.application	string	Application name
params?.parameters	string	^(optional) Additional application-specific parameters
params?.payload	string	^(optional) Additional application-specific payload

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.start",
  "params": {
    "application": "YouTube",
    "parameters": "watch?v=zpp045FBbQY",
    "payload": "..."
  }
}

stop ^event

Signals that application stop was requested over DIAL.

Description

This event is sent out only for un-managed applications (i.e. in passive mode).

Parameters

Name	Type	Description
params	object
params.application	string	Application name
params?.parameters	string	^(optional) Additional application-specific parameters

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.stop",
  "params": {
    "application": "YouTube",
    "parameters": "watch?v=zpp045FBbQY"
  }
}

hide ^event

Signals that application hide was requested over DIAL.

Description

This event is sent out only for un-managed applications (i.e. in passive mode).

Parameters

Name	Type	Description
params	object
params.application	string	Application name

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.hide",
  "params": {
    "application": "YouTube"
  }
}

show ^event

Signals that application show was requested over DIAL.

This API is deprecated and may be removed in the future. It is no longer recommended for use in new implementations.

Description

This event is sent out only for un-managed applications (i.e. in passive mode).

Parameters

Name	Type	Description
params	object
params.application	string	Application name

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.show",
  "params": {
    "application": "YouTube"
  }
}

change ^event

Signals that application URL change was requested over DIAL.

This API is deprecated and may be removed in the future. It is no longer recommended for use in new implementations.

Description

This event is sent out only for un-managed applications (i.e. in passive mode).

Parameters

Name	Type	Description
params	object
params.application	string	Application name

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.change",
  "params": {
    "application": "YouTube"
  }
}

Files

DIALServerPlugin.md

Latest commit

History

DIALServerPlugin.md

File metadata and controls

DIAL Server Plugin

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Configuration

Interfaces

Properties

state property

Description

Value

Result

Errors

Example

Get Request

Get Response

Set Request

Set Response

Notifications

start event

Description

Parameters

Example

stop event

Description

Parameters

Example

hide event

Description

Parameters

Example

show event

Description

Parameters

Example

change event

Description

Parameters

Example

state ^property

start ^event

stop ^event

hide ^event

show ^event

change ^event