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)
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.
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 )
· 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:
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.
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.
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.
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 22.214.171.124).
A DiscoveredTerminal object shall have the following properties:
readonly Number enum_id
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
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 .
readonly String X_HbbTV_App2AppURL
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
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
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.