Class: CSMan

CSMan

Module for using the Companion Screen Manager API of HbbTV 2.0

CSMan may fire the following events:

Source:
Example

Launch a webpage with the remote app2app service endpoint added to the URL.

var CSMan = require("hbbtv-lib/cs/cs_manager");

CSMan.once(CSMan.CS_DISCOVERED, on_discovery_finished);
CSMan.discover_launchers(10000);

function on_discovery_finished (devices) {
	   for (x in devices) {
	       CSMan.launch_html(devices[x].enum_id, "http://example.com/");
	   }
}

Extends

Members

APP_ALREADY_INSTALLED

The CS Launcher application received an Install operation (without a Launch operation) but it detected that the requested application is already installed
Source:

ERR_CSMAN_NOTFOUND

HbbTV CS Manager could not be initialized.
Source:

ERR_CSMAN_TIMEOUT

The discovery for launcher apps timed out. HbbTV requires that the discovery is finished within a second.
Source:
See:
  • CSMan.discover_launchers()

ERR_INVALID_ENUM_ID

Error signalled if the enum_id in a launch or install request does not match a connected CS launcher.
Source:

ERR_UNDEFINED

Unspecified error.
Source:

EVT_CS_DISCOVERED

Event name constant for the EVT_CS_DISCOVERED event.
Source:

EVT_CS_ERROR

Event name constant for the EVT_CS_ERROR event.
Source:

EVT_CS_LAUNCH_RESPONSE

Event name constant for the EVT_CS_LAUNCH_RESPONSE event.
Source:

GENERAL_ERROR

A general error has occurred that meant that the operation could not be completed for a reason other than those described for the other error codes in this table.
Source:

INVALID_ID

The CS Launcher application that is identified by enum_id is no longer available. (i.e. it has become unavailable since discovery occurred), or has never been available.
Source:

OP_DENIED

The CS Launcher application has blocked the operation, but it was blocked by the explicit interaction of the user of the Companion Screen.
Source:

OP_FAILED

The CS Launcher application attempted a Launch or Install operation but it is known to have failed. For a Native application, it means that the application could not be launched or installed. For an HTML application it means that an HTML application environment could not be launched.
Source:

OP_NOT_GUARANTEED

The CS Launcher application has initiated the instruction (launch or install) without a problem. It is assumed (to the best knowledge of the Launcher application) that the launch or installation operation has completed successfully.
Source:

OP_REJECTED

The CS Launcher application has automatically rejected the operation with no interaction with the user of the Companion Screen. This error code is intended for use when the CS Launcher has automatically blocked the operation due to a blacklist feature.
Source:

Methods

discover_launchers(timeoutopt)

Discovers available CS launchers.
Parameters:
Name Type Attributes Default Description
timeout number <optional>
 1500 Specifies when discovery shall terminate.
Source:
Fires:

getA2A_local() → {string}

Get the current base URL of the local endpoint of the application to application communication service.

The endpoint is defined in clause 14.5.2 of the HbbTV 2 specification. The usage of this endpoint to communicate between the HbbTV® application and the remote client is described in clause 14.5.1. The URL retrieved by this method shall end with a slash ('/') character.

Source:
Returns:
the local app2app service endpoint.
Type
string

getA2A_remote() → {string}

Get the current base URL of the remote endpoint of the application to application service.

The URL retrieved by this method shall be the same as the URL carried in the element as described in clause 14.7.2 of the HbbTV 2 specification and shall end with a slash ('/') character.

Source:
Returns:
the remote app2app service endpoint, i.e. the one used by the companion application
Type
string

getCII() → {string}

Get the URL that points to the CSS-CII service endpoint of the terminal that the calling HbbTV application is running on.

The URL retrieved by this method shall be the same as the URL carried in the element as described in clause 14.7.2. of the HbbTV 2 specification

Source:
Returns:
the DVB CSS CII service endpoint.
Type
string

install(enum_id, app_url, market_id) → {boolean}

Issues an install request on the selected device.
Parameters:
Name Type Description
enum_id number Identifier (enum_id) of a DiscoveredCSLauncher
app_url string market specific identifier of an application
market_id string id of a supported market on the companion device, e.g. Play Store, etc.
Source:
Fires:
Returns:
TRUE if request was executed, else FALSE.
Type
boolean

launch_html(enum_id, url) → {boolean}

Launches an HTML page on the selected device.
Parameters:
Name Type Description
enum_id number Identifier (enum_id) of a DiscoveredCSLauncher
url string a URL to a web site that shall be launched.
Source:
Fires:
Returns:
TRUE if request was executed, else FALSE.
Type
boolean

launch_native(enum_id, url) → {boolean}

Launches a native application on the selected device.
Parameters:
Name Type Description
enum_id number Identifier (enum_id) of a DiscoveredCSLauncher
url string a URL that is connected with a native application, that is installed on the companion device.
Source:
Fires:
Returns:
TRUE if request was executed, else FALSE.
Type
boolean

launch_native_html(enum_id, url_native, url_html) → {boolean}

Launches a native application with an HTML page as fallback on the selected device.
Parameters:
Name Type Description
enum_id number Identifier (enum_id) of a DiscoveredCSLauncher
url_native string a URL that is connected with a native application, that is installed on the companion device.
url_html string a URL to a web site that shall be launched if the native application can't be launched.
Source:
Fires:
Returns:
TRUE if request was executed, else FALSE.
Type
boolean

send_request(enum_id, payload) → {boolean}

Send launch and install requests.
Parameters:
Name Type Description
enum_id number Identifier (enum_id) of a DiscoveredCSLauncher
payload string Information on the app to be launched.
Source:
See:
Fires:
Returns:
TRUE if request was executed, else FALSE.
Type
boolean

Events

EVT_CS_DISCOVERED

A companion screen has been discovered or the discovery timed out.

Use the CSMan.EVT_CS_DISCOVERED event name constant to listen for this event.

Parameters:
Name Type Description
csLaunchers Array.<DiscoveredCSLauncher> Array of discovered CS launchers.
Source:

EVT_CS_ERROR

An error occured.

Use the CSMan.EVT_CS_ERROR event name constant to listen for this event.

Parameters:
Name Type Description
errorCode string Error code. Following values possible:
message string A textual description of what happened
Source:

EVT_CS_LAUNCH_RESPONSE

Response of a launch or install request is available.
Parameters:
Name Type Description
responseCode number Can have the following values:
Source: