The application/oipfRemoteControlFunction embedded object
Support in HbbTV
Available since: Not implemented in HbbTV
OITFs that have indicated <remoteControlFunction> with value “true” SHALL support the DLNA RUI RCF APIs through the use of the following non-visual embedded object:
<object type=”application/oipfRemoteControlFunction”/>
Constants
The following constants are defined as properties of the application/oipfRemoteControlFunction embedded object:
| Constant name | Numeric Value | Use |
| REQUEST_CUI | 0 | A Remote Control Device (a Control UI or an XML UI Listing) requests a control UI by using the pre-defined URI “/rcf/request_cui”. |
| REQUEST_MSG | 1 | A Control UI in the Remote Control Device sends a message by using the pre-defined URI “/rcf/request_msg”. |
| CREATE_APP | 2 | A Control UI in the Remote Control Device sends a message by using a URI defined by an OITF. This message has triggered the application receiving this event to be launched by the OITF. |
Properties
| readonly Integer currentRemoteDeviceHandle |
| The handle of the Remote Control Device which is associated with the DAE application in the mapping information table (see section 8.5.6) and is waiting for the response from the DAE application. The value of this handle is assigned by the OITF, and is unique within the OITF for the duration of a session (the duration of the connection between the OITF and that Remote Control Device). Applications SHALL NOT rely on the value of this handle being preserved across sessions. This property is retrieved from the mapping information table (see section 8.5.6) in the OITF which contains the pairing information between the Remote Control Device and the DAE application. Only one Remote Control Device is allowed to connect to a given DAE application at a time. If there is no mapping information between a Remote Control Device and the DAE application, this property returns undefined. |
| readonly String currentRemoteDeviceUA |
| The Remote Control Device User-Agent string that has been provided in the Remote Control Device’s HTTP request. The application/oipfRemoteControlFunction object stores the value of the User-Agent header included in the most recent HTTP request of the Remote Control Device currently being connected to this DAE application. Note: The User-Agent string of the Remote Control Device is expected to conform to the format of the User-Agent string defined in [Req. 5.3.a] of [CEA-2014-A]. If there is no mapping information between a Remote Control Device and the DAE application, this property returns undefined. |
| function onReceiveRemoteMessage( Integer requestType, Integer remoteDeviceHandle, Integer reqHandle, String requestLine, String headers, String body ) |
| The function that is called when the Remote Control Device sends an HTTP request with one of the pre-defined URIs (“/rcf/request_cui” or “/rcf/request_msg”), or sends an HTTP request to the OITF to launch a DAE application. The DAE application can distinguish between these two cases by the type parameter as follows: · When the Remote Control Device requests a control UI by using the pre-defined URI “/rcf/request_cui”, the function is called with the type parameter REQUEST_CUI. · When the Remote Control Device sends a message by using the pre-defined URI “/rcf/request_msg”, the function is called with the type parameter REQUEST_MSG. When the DAE application is launched by the OITF in response to a request from the control UI in the Remote Control Device, the function is called with the type parameter CREATE_APP. The function will be called after the DAE application has loaded (i.e. after the onLoad event has been dispatched to the DAE application). The DAE application being launched is expected to contain an instance of the application/oipfRemoteControlFunction object. The OITF SHALL dispatch the event to the application/oipfRemoteControlFunction object in the DAE application matched with the Remote Control Device handle which are paired in the mapping information table (see section 8.5.6). When the ReceiveRemoteMessage event is dispatched to the target application, the DAE application receives the Remote Control Device’s User-Agent header value containing the Remote Control Device’s capability (in the headers parameter) which the OITF was given with the HTTP request from the Remote Control Device. The DAE application SHALL include the User-Agent value from the Remote Control Device in the XMLHttpRequest object it uses to retrieve the appropriate Control UI from the IPTV Applications server (see section 8.1.2). When this event is invoked, the DAE application SHALL respond by calling the sendRemoteMessage() method. This method need not be called from the event handling function, and may be called after a request to the IPTV Applications Server for an appropriate Control UI has completed. Only one Remote Control Device is allowed to connect to a DAE application (see section 8.5.6) at any time. If an HTTP request from another Remote Control Device directed at the DAE application is received by the OITF while a Remote Control Device is connected, the OITF SHALL NOT make and dispatch ReceiveRemoteMessage events to the target DAE application but SHALL send an HTTP response (HTTP 500 – Internal Server Error) to the Remote Control Device. Every HTTP request from a Remote Control Device to the DAE application with which it is paired SHALL generate an onReceiveRemoteMessage event, even if there are previous HTTP requests which the DAE application has not yet responded to. Each HTTP request SHALL be given a unique reqHandle by the OITF to allow the DAE application to distinguish between outstanding requests. The specified function is called with six arguments: type, remoteDeviceHandle, reqHandle, requestLine, headers and body which are defined as follows: · Integer requestType – the type of the HTTP request from the Remote Control Device. This SHALL take one of the following values: o REQUEST_CUI o REQUEST_MSG o CREATE_APP · Integer remoteDeviceHandle – the handle of the Remote Control Device which is sending the HTTP request to the DAE application. This handle has a unique value which is assigned by the OITF. · Integer reqHandle – the handle of the request from the Remote Control Device. The value of this handle is assigned by the OITF, and is unique within the OITF for the duration of a session (the duration of the connection between the OITF and that Remote Control Device). Applications SHALL NOT rely on the value of this handle being preserved across sessions. · String requestLine – the HTTP requestLine string that comes from the Remote Control Device. · String headers – the HTTP request header string that comes from the Remote Control Device. · String body – the HTTP request body that comes from the Remote Control Device. The values of the requestLine, headers and body parameters are derived from the received HTTP request as follows: Where: HTTP Request = Request-Line CRLF Header-Lines CRLF Message Header-Lines = *((general-header | request-header | entity-header) CRLF) Message = [ message-body ] Then: requestLine = “Request-Line”. headers = ”Header-Lines”. body = “Message “. |
| function onResultMuticastNotif( Integer remoteDeviceHandle, Integer reqHandle, Boolean dynamic ) |
| The function that is called when the Remote Control Device sends an HTTP request with an URL which is a value of a <ruiEventURL> element in the Multicast Notification Message. This function is called with the following arguments: · Integer remoteDeviceHandle – the handle of the Remote Control Device which is sending the HTTP request to the DAE application. · Integer reqHandle – the handle of the request from the Remote Control Device. · Boolean dynamic – if true, the DAE application SHALL respond by calling the sendRemoteMessage method. This method need not be called from the event handling function, and may be called after a request to the IPTV Applications Server for an appropriate notification CE-HTML document has completed. |
Methods
Boolean useServerSideXMLUIListing( String xmlUIListing, | ||
Description | Generate an XML UI Listing by merging the XML UI Listing currently being exposed by the DLNA RUIS in the OITF with the XML UI Listing provided by the xmlUIListing parameter of this method. If the OITF successfully generates the new XML UI Listing, this method SHALL return true. Otherwise, it SHALL return false. | |
Arguments | xmlUIListing | The Server Side XML UI Listing. |
advertiseImmediately | After generating the new XML UI Listing, if this parameter is true, the DLNA RUIS in the OITF SHALL send a UPnP Discovery (SSDP:byebye) message followed by a UPnP Discovery (SSDP:alive) message. This notifies the DLNA RUIC in any Remote Control Device that it should retrieve the new XML UI Listing. | |
Boolean sendRemoteMessage( Integer remoteDeviceHandle, Integer reqHandle, | ||
Description | Send the HTTP response with the headers and the message to the Remote Control Device related to remoteDeviceHandle. This method is called by a DAE application in response to a HTTP request from the Remote Control Device. This method can be called at any time for any pending HTTP request (i.e. a request with handle reqHandle from the Remote Control Device with handle remoteDeviceHandle that has not had a response from the OITF via a sendRemoteMessage() or sendInternalServerError() call). This method SHALL return true if the operation succeeded, or false if failed. If there is no HTTP connection, it also returns false. | |
Arguments | remoteDeviceHandle | The handle of the Remote Control Device. |
reqHandle | The handle of the request as provided by onReceiveRemoteMessage. | |
headers | The HTTP response header string. This string is added to the default HTTP header string generated by the OITF to form the HTTP header string used for the HTTP response. Any parameters that are specified in both strings SHALL be set to the value in the headers argument. If the headers supplied by the application do not include a Content-Type header, the OITF SHALL use the default content type of application/ce-html+xml. | |
message | The HTTP response body string whose type is text (e.g. XML, JSON, CE-HTML or Plain Text). | |
Boolean sendMulticastNotif( Integer remoteDeviceHandle, Integer eventLevel, | |||||||||||||
Description | Send the 3rd party multicast notification to any Remote Control Devices (as defined in section 5.6.1 of [CEA-2014-A]) based on target Remote Device information. The OITF SHALL store the text (essentially a CE-HTML document) provided in the notifCEHTML parameter inside the DLNA RUIS and SHALL create a URL to it which can be used by Remote Control Devices to retrieve the original text. This URL SHALL be inserted in the <ruiEventURL> element in the Multicast Notification Message. If the notifCEHTML parameter is set to null, the HTTP request from the Remote Device to retrieve the text SHALL be being pended and dispatch the onResultMuticastNotif event to the DAE application which will retrieve a CE-HTML document dynamically. The DAE application SHALL use the sendRemoteMessage method with a CE-HTML document related parameters to send the text (notification message). If the remoteDeviceHandle parameter in this method has a value other than -1, the notification CE-HTML document will be retrieved by the only Remote Device matched with the remoteDeviceHandle parameter, whereas if the parameter has -1, all of the Remote Devices could retrieve the notification CE-HTML document from the OITF (see section 8.5.5). This method SHALL return true if the operation succeeded, or false if it failed. | ||||||||||||
Arguments | remoteDeviceHandle | The handle of the Remote Device. | |||||||||||
eventLevel | The value of the HTTP LVL. This allows the Remote Control Devices to filter the multicast notification messages. The following are the defined event levels and the expected meaning of those values (see section 5.6.1 of [CEA-2014-A] for more information):
| ||||||||||||
notifCEHTML | The text that makes up the notification CE-HTML document, the link to which is sent to the Remote Control Device. | ||||||||||||
profileList | All the profiles that the Remote UI Server in the OITF requires the Remote UI Client in the Remote Control Device to support to properly render the notification CE-HTML document. The value of the <profilelist> element SHALL conform to the definition of the <profilelist> element in the XML schema in Annex B of [CEA-2014-A]. | ||||||||||||
Boolean sendInternalServerError( Integer remoteDeviceHandle, | ||
Description | Send the HTTP status code (500: Internal Server Error) in response to a pending HTTP request from the Remote Control Device. This method SHALL return true if the operation succeeded, or false if it failed. | |
Arguments | remoteDeviceHandle | The handle of the Remote Control Device. |
reqHandle | The handle of the request as provided by onReceiveRemoteMessage. | |
Boolean dropConnection( Integer remoteDeviceHandle ) | ||
Description | Remove the mapping information in the table between the DAE application and the Remote Control Device currently bound to the DAE application. This method SHALL return true if the operation succeeded, or false if it failed. | |
Arguments | remoteDeviceHandle | The handle of the Remote Control Device. |
Events
For the intrinsic events listed in the table below, a corresponding DOM event SHALL be generated in the following manner:
| Intrinsic event | Corresponding DOM event | DOM Event properties |
| onReceiveRemoteMessage | ReceiveRemoteMessage | Bubbles: No Cancellable: No Context Info: requestType, remoteDeviceHandle, reqHandle, requestLine, headers, body |
| onResultMuticastNotif | ResultMuticastNotif | Bubbles: No Cancellable: No Context Info: remoteDeviceHandle, reqHandle, dynamic |
NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications SHOULD NOT rely on receiving ReceiveRemoteMessage or a ResultMuticastNotif event during the bubbling or the capturing phase. Applications that use DOM event handlers SHALL call the addEventListener() method on the application/oipfRemoteControlFunction object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.