Migration Guide (TOI2→TOI3)

Some effort is required to migrate an existing portal from TOI2 to TOI3. This guide helps you through the major points. While migrating your portal, please keep an eye on the STB log for warnings related to deprecated functionality.

Initialization

TOI3 does not use an NPAPI plugin as in TOI2/JS. Instead, TOI3 uses web technologies for communication with the KreaTV platform. The protocol details are hidden from the application by a JavaScript wrapper API, which is very similar to the TOI2/JS "toi" object. See the bootstrapping page for more details.

Fundamentals

Using web technologies means that each individual function call to TOI3 involves an XmlHttpRequest to the KreaTV platform, so has more overhead than before, but that data structures returned from the platform are now JSON objects. These objects are processed much faster by the browser's JavaScript engine. To optimize on this fact, the APIs in TOI3 make it easier to request more data in one single call, and also provides needed data in notifications from the platform.

For example, the Information Service getObject() and setObject() functions have been replaced by set() and get(). These functions take and return arrays of objects. It is recommended that you batch your calls to Information Service with these functions when possible.

When subscribing to changes on Information Service configuration objects, the ToiInformationObjectsChangedEvent value contains the object you subscribed to. There is no longer a need to call getObject() as a second step to get the value.

In a similar way, when subscribed to changes in media player parameters, the ToiMediaPlayerParameterChangedEvent contains the name and value of the parameter that changed, eliminating a call to getParameter().

Net Service

ToiNetService has been redesigned in TOI3. The biggest change is the introduction of networks, you can read more about it here. While configuration in TOI2 was performed directly on a particular network device/interface, now configuration is performed indirectly by ToiNetService based on the network's settings.

The term interface is used in TOI3 to represent the network interface, not an IP address as it was in TOI2.

When getting the STB's IP address, the var.ip.eth0.addr configuration object is now deprecated. Instead, the IP address used for the boot network (the method the STB used to boot, ie Wi-Fi or ethernet) should be obtained with:

// Get the STBs IP address(es)
function updateSTBInfoNetworkIPAddress() {
  var network = toi.netService.getNetwork(
    toi.consts.ToiNetService.BOOT_NETWORK);
  var networkInfo = network.getNetworkInfo();
  var interfaceInfo = networkInfo.interfaceInfo;

  var addressString = "";
  for (var i = 0; i < interfaceInfo.ipAddresses.length; i++) {
    addressString += interfaceInfo.ipAddresses[i].ipAddress;
  }

  framework.emit("NewNetworkIPAddress", addressString);
}

The MAC address is handled in a similar way. ToiNetService allows you to get the IP address, MAC address and other details of the non-active interfaces too.

ToiNetService also reduces and simplifies the number of events, and now also includes Wi-Fi related events.

Wi-Fi Connection

In TOI3 connecting to a Wi-Fi access point requires providing the required information to the service as follows:

var network = NetService.getNetwork(toi.consts.ToiNetService.BOOT_NETWORK);
  network.applySettings({}, {
   wifiSettings: { APINFO.. }
});

Please refer to the ToiNetService

API documentation for more information.

Media Player

The media player works much as before, but for efficiency purposes the close(), open() and play() functions are combined together into a single quickPlay(URL) function. There is also a quickPlayFromPosition().

The state machine for the Media Player has been simplified, please see the Media Service documentation.

Asynchronous operations

Asynchronous operations are handled in a way that is more familiar to JavaScript programmers than before. The new AsyncCallback mechanism allows you to pass an object containing callback functions which will be executed once the asynchronous operation completes. As an example:

function configureVideoOutput(config) {
  var session = toi.videoOutputService.createSession();
  session.configure(hdmiOutputId, config);
  session.apply({
    onCompleted: function() {
      ...
      session.releaseInstance();
    },
    onError: function() {
      ...
      session.releaseInstance();
    },
    onProgress: function() {
      ...
    },
    onResult: function() {
      ...
      session.releaseInstance();
    }});
}

This is used when scanning for Wi-Fi networks and when applying video configuration changes (shown above).

Video Output Service

The VideoOutput service has had a major overhaul. The new interface shares the philosophy of the old one (session based with incremental configuration steps), but tries to approach output configuration in a modern and more consistent way. Focus has been to improve the ergonomics of the JavaScript interface. The most noticeable change is that you do all output configuration using one method called configure(). Instead of doing

session.setDefaultVideoMode(outputId, VIDEO_MODE_720P50);
session.setColorSpace(outputId, COLOR_SPACE_SRGB);

you do

session.configure(outputId, { mode: VIDEO_MODE_720P50,
                              colorSpace: COLOR_SPACE_SRGB });

or equivalently

session.configure(outputId, { mode: VIDEO_MODE_720P50 });
session.configure(outputId, { colorSpace: COLOR_SPACE_SRGB });

in sequence.

Valid settings

The information about valid settings in the old ToiVideoOutputConfigurationVideoOutputInfo and ToiVideoOutputConfigurationVideoOutputCapabilityInfo (like ToiVideoOutputConfigurationVideoOutputInfo::allowedVideoModes and ToiVideoOutputConfigurationVideoOutputCapabilityInfo::videoModes) are merged and made available in the different ToiVideoOutputInfo members. Here a "supported" prefix indicates that the member contains a lists of all settings supported by the hardware, "configurable" a lists of all settings available using the current configuration and "allowed" all settings available using the current configuration plus the restrictions imposed by the display (where applicable).

Display overrides

The feature of adding exceptions or overrides for HDMI displays with a broken EDID (using setDisplayInfo()) has been removed. Instead you can instruct the interface to ignore all restrictions imposed by the display. This is done using the ignoreDisplayCapabilities attribute.

// Scenario: The connected display signals (using the EDID) that it
// doesn't support 'VIDEO_MODE_720P50' (i.e. the mode is not in
// 'allowedModes'), but we know it does and we want to ignore it.
session.configure(outputId, { mode: VIDEO_MODE_720P50,
                              ignoreDisplayCapabilities: true });

More information about the service and the interface can be found in here: Video Output Service

Platform Service

Functions related to components have been removed.

Statics

The TOI2/JS concept of statics has been removed, and instead you can now write JSON objects directly. For example, when connecting to a Wi-Fi network and calling ToiNetwork::applySettings() a ToiSettings object is required:

this.network.applySettings({}, {
  wifiSettings: {
    ssid: apInfo.ssid,
    presharedKey: password
  },
  deviceSelection: toi.consts.ToiNetwork.DEVICE_SELECTION_WIFI
});

Exceptions

Exception handling is now more aligned with standard JavaScript paradigms. See here for more details on exceptions.

Detailed comparison

The following table lists the changes between TOI2/JS and TOI3 where possible. An exhaustive changelog is also provided.

TOI2/JS	TOI3
ToiApplicationService
activate(), activateWithUri(), activateWithCommand(), deactivate(), kill(), getOwnApplicationId(), getApplicationIds(), getBoolProperty(), getIntProperty(), getStringProperty(), getStringSequenceProperty(), getInfo(), loadUri()	Removed.
ToiAudioOutputConfigurationSession
	Application must call releaseInstance() explicitly.
ToiHdmiService
getHdmiSinkInfo()	getSinkInfo()
HDMI_CONNECTION_STATUS_UNKNOWN, HDMI_CONNECTION_STATUS_CONNECTED, HDMI_CONNECTION_STATUS_CONNECTED_CAPABILITIES_UNKNOWN, HDMI_CONNECTION_STATUS_DISCONNECTED	CONNECTION_STATUS_UNKNOWN, CONNECTION_STATUS_CONNECTED, CONNECTION_STATUS_CONNECTED_CAPABILITIES_UNKNOWN, CONNECTION_STATUS_DISCONNECTED
ON_HDMI_CONNECTION_STATUS_CHANGED	ON_CONNECTION_STATUS_CHANGED
	ON_HDCP_STATUS_CHANGED
ToiInformationService
getObject(), getObjects()	get(names)
setObject(), setObjects()	set(objects, type)
unsetObject(), unsetObjects()	unset(names, type)
ToiMediaService
createPipPlayerInstance(), createRecoderInstance, createProducerInstance(), createConsumerInstance(), enumerateProducers(), enumerateRecorders(), cancelTask()	Not yet supported.
ON_RECORDER_STATUS_CHANGED, ON_PRODUCER_STATUS_CHANGED	Not yet supported.
ToiMediaPlayer
	quickPlay(), quickPlayFromPosition(position)
setParameter(), unsetParameter()	setParameters(parameters), unsetParameters(names)
startTimeshiftBuffering(), stopTimeshiftBuffering(), redirectTimeshiftBuffering(), discardTimeshiftBuffer()	Not yet supported.
ToiNetService
ToiNetService has been mostly rewritten. We recommend you consult the Net Service page and the ToiNetService API documentation.
ToiPlatformService
rebootNow(), rebootAtNextStandby()	reboot(rebootType)
setStandby()	Removed.
	Use Power Management Service
getComponentsInfo(), getComponentInfo(), registerComponentUsage(), releaseComponentUsage()	Removed.
ToiVideoOutputService
ToiVideoOutputService has received extensive changes. We recommend you consult the Video Output Service page and the actual ToiVideoOutputService API documentation for more details. The example portal also shows some basic usage of this redesigned interface.

Unavailable services

The following services are not yet available:

Service name	Status
Asset Manager Service	Not yet available.
Channel Service	Not yet available.
Diagnostics Service	Not yet available.
Dlna Content Directory Service	Not yet available.
Dlna Service	Not yet available.
Drm Service	Not yet available.
Dvb Eit Service	Not yet available.
Frontend Service	Not yet available.
Front Panel Service	Removed. Functionality moved to a config file instead.
Operation Manager	Removed. See AsyncCallback for new replacement.
Resource Service	Not yet available.
Storage Service	Not yet available.