TOI/JS

General concepts

TOI/JS separates the software platform from the applications and gives the applications access to the interfaces provided by the platform, for instance the media player (ToiMediaPlayer) for streaming media and storage and retrieval of information objects (ToiInformationService).

The main purpose of TOI/JS is to provide an abstraction for applications. This includes both abstraction of hardware differences as well as underlying APIs and protocols implemented by the software platform. Examples of hardware differences are different MPEG decoders as well as different frontends for DVB. Example of protocol differences are different protocols for media transportation, e.g. RTSP dialects, DVB-T and HTTP.

The overall architecture is shown in the figure below:

Overall architecture showing TOI/JS separating applications from the software platform.

The implementation of TOI/JS shall of course provide an efficient usage of the hardware resources available, e.g. CPU, memory, MPEG decode.

TOI/JS itself and the implementation of it is important for the performance, stability and robustness of the platform itself and the applications running on it. The interface shall provide one (and only one) way of achieving a specific functionality, e.g. accessing the flash memory for persistent storage is done through exactly one interface (ToiInformationService), selecting service components for playback(e.g. audio language) is done through exactly one interface (ToiMediaPlayer) etc.

Another important design guideline is the usage of well-defined areas of responsibilities. This is important from many aspects, the understanding among application developers, the maintainability and testability of the separate interfaces as well as for introducing functional extensions. The different areas of responsibilities are assigned to the different TOI/JS interfaces as described below:

• ToiMediaPlayer
  Functionality related to the active (playing) media service, e.g. controlling the service (open, play, fast forward etc.), receiving information (e.g. component information) and control of active stream for audio, video and subtitling.

• ToiMediaRecorder
  Functionality related to the recording of a stream.

• ToiInformationService
  Functionality for reading and writing configuration tokens and other data from/to different storage medias. This includes permanent storage (e.g. in Flash memory), volatile storage (e.g. in RAM) and access to information distributed from remote (e.g. Infocast).

• ToiAssetManagerService
  Functionality for handling recordings and other assets. When a recording is made using the ToiMediaRecorder, it can be managed with this service. E.g. handling meta data, deleting, creating links between assets.

• ToiApplicationService
  Functionality related to a multi application environment. Applications can be activated/deactivated and managed through this service.

• ToiPlatformService
  Functionality related to the KreaTV platform. This is used to reboot and put the STB in an out of standby.

This also means that other kinds of functionality is left for the application to handle. This includes:

• Graphics.

• Look and feel.

• Handling user input and taking action upon user generated events.

• Preparing data for presentation as well as presenting the data for the end user.

In order to have a common language for describing various parts of TOI, IDL is being used.

Common functions and conventions

Version

TOI/JS version can be read from HTML/JavaScript applications. It is read by "version" attribute of the HTML element which loads TOI/JS. For example:

// Load one TOI/JS object.
<embed id="toiX" type="application/x-motorola-toi" hidden="true">
<script language="Javascript"
    // Read TOI/JS version by HTML element id.
    var toiXVersion = toiX.version;

    // The other way to load TOI/JS object and read version. 
    var  toiY= document.createElement("embed");
    toiY.type = "application/x-motorola-toi-dlna";
    toiY.setAttribute("hidden", "true");
    document.body.appendChild(toiY);
    var toiYVersion = toiY.version;
</script>

toi object

The global "toi" object is the primary access point to TOI interfaces from HTML/JavaScript applications. This object is available as a property of the JavaScript window object. In case no access is granted, the toi property is undefined.

Access to platform services

Each platform service is registered as it's own property in the toi object. Example of services are the ToiMediaService which is accessed by the mediaService property and ToiInformationService which is accessed by the informationService property.

Function error notifications

Any function that is not successfully executed throws an exception. An example is shown below:

var is = toi.informationService;
var name = "config.serialnumber";
try {
    // Trying to set the value of a readonly attribute.
    is.setObject(name, "4545", is.STORAGE_PERMANENT);
}
catch( ex ) {
    // A ToiException is raised.
    alert("Failure changing value for " + name + ": " + ex);
}

As seen in the example above, exception can be accessed as one string. However it is more than one string. Exception object can provide three attributes actually:

• code: one number identifying the exception
• name: the name used in the example above
• msg: more information carried by the exception To get the exception attributes, toi.utils.convertToiException() is invoked to convert the exception to object from string. The function is also used to distinguish one exception. See one more example:

try {
    var value = toi.serviceX.operationX();
}
catch( ex ) {
    alert("Failure changing value for " + ": " + ex);
    var exObj = toi.utils.convertToiException(ex);
    if (exObj instanceof TToiInvalidArgumentException) {
        alert("TToiInvalidArgumentException catched: " + exObj.name +
exObj.code + exObj.msg);
    }
    if (exObj instanceof TToiNoDataException) {
        alert("TToiNoDataException catched: " + exObj.name + 
exObj.code + exObj.msg);
    }
}

Events

While exceptions are used to report error conditions in a synchronous manner, events are used for asynchronous reporting of errors and state changes. This means in particular that applications using TOI/JS do not have to be reentrant, since all events are queued and delivered only when the application is idle. On the other hand, data provided by the event may already be obsolete by the time the event is received by the application. Subscription and notification of events is handled in a uniform way for all interfaces being part of the TOI. The subscriber provides a listener object taking a single event object as argument to a registration method in the interface that is capable of generating the event of interest. The actual type of event object being sent may depend on the particular event type. All event objects have a common base interface, the ToiEvent interface and all event targets, i.e. interfaces that can generate events, have a common base interface, the ToiEventTarget interface. An example is shown below:

function eventhandler(event) {
    // Check the event type.
    if( event.type == event.target.ON_STATE_CHANGED ) {
        // Use additional information from the TToiStateChangedEvent
        alert("MediaPlayer state changed: " + event.state);
    }
}
var mp = mediaService.createPlayerInstance();

// Adding an event to the ToiMediaPlayer (which is also a ToiEventTarget).
mp.addEventListener(mp.ON_STATE_CHANGED, eventhandler);

Security considerations

Access to TOI is restricted based on the domain from which the HTML/JavaScript application was loaded. Two levels of security has been defined: trusted and non-trusted with the corresponding application levels: trusted and anonymous JavaScript applications. For anonymous applications the toi property will be undefined.

Key Event Handling

The KreaTV IP-STB software supports input handling through standardized JavaScript DOM level 3 event model using the KeyboardEvent interface.