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	M/O	Description
callsign	string	mandatory	Plugin instance name (default: DIALServer)
classname	string	mandatory	Class name: DIALServer
locator	string	mandatory	Library name: libThunderDIALServer.so
startmode	string	mandatory	Determines in which state the plugin should be moved to at startup of the framework
configuration	object	mandatory	Server configuration
configuration.name	string	mandatory	User-friendly name of the device
configuration.model	string	mandatory	Name of the device model
configuration.description	string	mandatory	Short description of the device
configuration?.modelnumber	string	optional	Device model number
configuration?.modelurl	string	optional	URL to device model website
configuration.manufacturer	string	mandatory	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	mandatory	List of supported applications
configuration.apps[#]	object	mandatory	(an application definition)
configuration.apps[#].name	string	mandatory	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	R/W	Description
state	read/write	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.

The application name parameter shall be passed as the index to the property, i.e. state@<application-name>.

Index

Name	Type	M/O	Description
application-name	string	mandatory	...

Value

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

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

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	Specified application does not exist
`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": "Started"
}

Set Request

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

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:

Notification	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
show ^deprecated	Signals that application show was requested over DIAL
change ^deprecated	Signals that application URL change was requested over DIAL

start ^notification

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).

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.application	string	mandatory	Application name
params?.parameters	string	optional	Additional application-specific parameters
params?.payload	string	optional	Additional application-specific payload

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.register",
  "params": {
    "event": "start",
    "id": "myid"
  }
}

Notification

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

The client ID parameter is passed within the notification designator, i.e. <client-id>.start.

stop ^notification

Signals that application stop was requested over DIAL.

Description

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

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.application	string	mandatory	Application name
params?.parameters	string	optional	Additional application-specific parameters

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.register",
  "params": {
    "event": "stop",
    "id": "myid"
  }
}

Notification

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

The client ID parameter is passed within the notification designator, i.e. <client-id>.stop.

hide ^notification

Signals that application hide was requested over DIAL.

Description

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

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.application	string	mandatory	Application name

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.register",
  "params": {
    "event": "hide",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.hide",
  "params": {
    "application": "YouTube"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.hide.

show ^notification

Signals that application show was requested over DIAL.

show is an alternative name for this notification. This name is deprecated and may be removed in the future. It is not recommended for use in new implementations.

Description

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

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.application	string	mandatory	Application name

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.register",
  "params": {
    "event": "show",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.show",
  "params": {
    "application": "YouTube"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.show.

change ^notification

Signals that application URL change was requested over DIAL.

change is an alternative name for this notification. This name is deprecated and may be removed in the future. It is not recommended for use in new implementations.

Description

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

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.application	string	mandatory	Application name

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "DIALServer.1.register",
  "params": {
    "event": "change",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.change",
  "params": {
    "application": "YouTube"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.change.

DIAL Server Plugin

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Configuration

Interfaces

Properties

state property

Description

Index

Value

Errors

Example

Get Request

Get Response

Set Request

Set Response

Notifications

start notification

Description

Notification Parameters

Example

Registration

Notification

stop notification

Description

Notification Parameters

Example

Registration

Notification

hide notification

Description

Notification Parameters

Example

Registration

Notification

show notification

Description

Notification Parameters

Example

Registration

Notification

change notification

Description

Notification Parameters

Example

Registration

Notification

state ^property

start ^notification

stop ^notification

hide ^notification

show ^notification

change ^notification