Asynchronous Operations

The TOI API is used to control the set-top box hardware from a JavaScript portal, and most of the API operates asynchronously. The API is designed so that most function calls will return immediately, allowing your portal to continue to operate while the set-top box hardware carries out the operation in the background. An event mechanism is used to signal when the asynchronous operation completes.

As an example, calling the ToiMediaPlayer::quickPlay() function returns immediately, but the media player now has the task to connect to the network, locate the stream, download and buffer it, set up any necessary decryption, and eventually begin to perform the decoding and display of video. The portal does not need to freeze up wwhile these actions occur.

The Portal developer can use an addEventListener() function to register an event listener function (also known as a callback function) which will be called every time the media player changes state. When the set-top box has begin decoding and displaying the video, the KreaTV platform raises the ToiMediaService::ON_PLAYER_STATUS_CHANGED event to notify all subscribed listeners that the media player just entered STATE_PLAYING.

On a few occasions the TOI API also uses a special object for handling more complex asynchronous operation. To start such an operation, simply call the asynchronous function (as illustrated below). The function in question will return an operation handle that can be used to cancel the operation. The first argument to an asynchronous function is a callback object that provides callback functions for handling the result of the operation.

function WifiScanner(network)
{
  var pending = false;

  var callbacks = {
    onResult : function(operation, operationresult) {
      // display found access points
    },
    onError : function(operation) {
      // display error
      pending = false;
    },
    onCompleted: function(operation) {
      pending = false;
    },
    onProgress : function(operation) {}
  };

  this.scan = function() {
    try {
      var scanOperation = network.scanWifi(callbacks);
      pending = true;
    }
    catch (x) {
      printEvent("Can not start wifi scan: " + x);
    }
  };
}