Companion Screen discovery APIs

Support in HbbTV

Available since: HbbTV 2.0.1 (ETSI TS 102 796 V1.4.1)

HbbTVCSManager embedded object

This embedded object shall have the MIME type “application/hbbtvCSManager”. It enables applications to:

  • discover other HbbTV® terminals on the home network;
  • discover the base URLs of the local and remote endpoint for application to application communication;

Boolean discoverTerminals(function onTerminalDiscovery)

Description

Triggers a callback reporting other HbbTV® terminals on the home network, along with an enumeration ID, a friendly name, and service endpoint URLs.

This returns with either the value true to indicate that the function has completed with no errors (and that a callback is expected), or false otherwise. On HbbTV® terminals that do not support discovering other HbbTV® terminals, false shall be returned.

When true is returned, the onTerminalDiscovery() callback shall be scheduled to fire within 1 second. There shall be no callback scheduled if false is returned.

Arguments

onTerminalDiscovery

A callback function. See below for the details.

The onTerminalDiscovery callback shall be supported and called once for each call to discoverTerminals() that returns true:


function onTerminalDiscovery( Array terminals )

Arguments

terminals

A JavaScript Array object containing zero or more DiscoveredTerminal objects (see clause 8.2.6.2) where each object in the array represents an HbbTV® terminal that was either:

· available for connecting to the HbbTV® terminal (at the time of the call to discoverTerminals());

· or subsequently became available for connecting to the HbbTV® terminal (i.e. after the call to discoverTerminals().

Terminals shall use the protocol defined in clause 14.7 to discover other terminals for inclusion in this array.

NOTE: There is no mechanism for an HbbTV® application to determine if another HbbTV® terminal is no longer available. The application should make further calls to discoverTerminals() as required to keep up to date.

For an HbbTV® application to use the local service endpoint for application to application communications, it first needs to obtain the URL of the local service endpoint by calling the getApp2AppLocalBaseURL method defined here:

String getApp2AppLocalBaseURL()

Description

Returns the base URL of the application to application communication service local endpoint, as defined in clause 14.5.2. The use 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.

String getInterDevSyncURL()

Description

Returns the URL of the CSS-CII service endpoint for 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 <X_HbbTV_InterDevSyncURL> element as described in clause 14.7.2.

String getApp2AppRemoteBaseURL()

Description

Returns the base URL of the application to application communication service remote endpoint.

The URL retrieved by this method shall be the same as the URL carried in the <X_HbbTV_App2AppURL> element as described in clause 14.7.2 and shall end with a slash (‘/’) character.

DiscoveredTerminal class

Instances of this class provide details of endpoints of a Terminal that has been discovered using the discoverTerminals() method of the HbbTVCSManager object (see clause 8.2.6.1).

A DiscoveredTerminal object shall have the following properties:

readonly Number enum_id

Description

A unique ID for a discovered HbbTV® terminal.

 

The enum_id is expected to be quasi-static, and that repeated calls to discoverTerminals() will respond with the same enum_id unless either this terminal or the other terminal have been restarted or the other terminal has been re-connected.

 

Newly started and connected terminals shall generate new enum_ids.

 

readonly String friendly_name

Description

A discovered terminal may provide a friendly name, e.g. “Muttleys TV”, for an HbbTV® application to make use of.

 

It is optional that this parameter is returned. If it is not returned, it shall be set to the empty string “”.

 

If set the value shall be carried in the friendlyName field of the UPnP device description as required by clause 14.7, and as per the implementation note in clause 5.4 of DIAL [50].

 

readonly String X_HbbTV_App2AppURL

Description

The remote service endpoint on the discovered HbbTV® terminal for application to application communication, equal to the value of the element with the same name as defined in clause 14.7.2.

 

readonly String X_HbbTV_InterDevSyncURL

Description

The remote service endpoint on the discovered HbbTV® terminal for inter-device synchronization, equal to the value of the element with the same name as defined in clause 14.7.2.

 

readonly String X_HbbTV_UserAgent

Description

The User Agent string of the discovered HbbTV® terminal, equal to the value of the element with the same name as defined in clause 14.7.2.