Application Concepts

Overview

The OpenTV OS runs on a network-deployed set-top box (STB) connected to a television. Input typically comes from a remote control, although other input devices can be used.

The OpenTV OS Software Development Kit (SDK) runs this hardware environment using a Windows-based PC, outputting content to a set-top box connected to a television.

OpenTV OS SDK allows developers to efficiently design, iterate, debug, and deploy applications using HTML5 and JavaScript.

Application Installation

This section describes how to install OpenTV OS applications.

Overview

OpenTV OS uses W3C widget packages for application installation; the package must be correctly structured and include a certificate/signature in order to be valid.

Installation Format

Installation Package

Applications must be installed as a valid W3C widget package, conforming to the following specifications: Packaged Web Apps (Widgets).

A valid OpenTV package consists of a valid W3C widget package containing:

  • The configuration document, called OTVAppMetadata.xml.
  • The application source files and assets, located at the root of the widget package or subfolders.
  • A start file, as referenced by OTVAppMetadata.xml
  • Zero or more digital signatures located at the root of the widget package.

Certificates

A certificate uses a digital signature to bind together a public key with an identity. All application installations require certificates.

The OpenTV package uses an XML digital signature, as specified at: XML Digital Signatures for Widgets.

The signature syntax and processing specification is available at: XML Signature Syntax and Processing.

A digital signature consists of:

  • One Author signature file (author-signature.xml)
  • One or more distributor signature files (signature1.xml)

To generate a digital signature, refer to Generating a digital signature.

To validate the digital signature, refer to the Algorithm to validate digital signatures.

To generate the digital signature use following algorithms:

Signature Format

Note: A signed package contains digital signature files; an unsigned package does not. All developers must provide signed packages, otherwise installation fails.

The signature file (for the author or distributor) must use the following:

  • Canonicalization Method Algorithm for SignedInfo
    Used for normalization (to remove spaces, new lines) of the content.
  • Signature Method Algorithm for SignedInfo
    Used for calculating the signature value which is kept in the “SignatureValue” element.
  • The list of nonsignature file name (URI) associated with the digest method algorithm and digest value, also called hash value, calculated over the file. The digest method algorithm calculates the digest value.
  • The property reference is the same as the nonsignature file reference above, but the digest value is calculated over the property element in the XML file (<Object Id="prop”> … </Object>).
  • A SignatureValue generated by the algorithm associated with the SignatureMethod Algorithm.
  • A list of one or more certificates in <X509Certificate>. One of the certificates is an end entity certificate and the others are CA certificates. The CA certificates are used for verification of the end entity certificate. The end entity certificate contains a valid public key.
  • A Property object element.
    This specifies the signature document properties and the user-defined properties.

Note: In a real deployment, networks or network authorized entities will sign the application package. For development purposes, Nagra provides a tool to package and sign the application.

Downloading and Installing the Package

After a valid installation package has been created for an application, it must be installed onto the set-top box. This is accomplished using Application Information Manager object (AIM) methods and events.

  • Install using installApp()
    Requires a downloadURL string, which is either a download server link, or a local zip file. This method checks the client's credentials, downloads/copies the application package, adds the application metadata to the application database, and sets the home directory and permissions. If successful, it returns the new and unique application UUID (identifying the application on the network) to the caller via the installAppOK event.
  • Installation Failed
    If the installation fails, an installAppFailed event is generated. Failure to install is generally due to an invalid installation package.
  • Uninstall
    If an application is uninstalled after being successfully installed via uninstallApp(), the system automatically cleans up the application's remnants, removing directories and data used and accessed by the application. The system also removes any configuration settings defined by the application using the Configuration Manager object methods.
  • Configuration Manager
    Create entries for this application using the Configuration Manager. Refer to the Configuration Manager Permissions documentation. See the section Configuration Manager Permissions for details.

Sample Installation Package

A (valid) sample installation zip file can be found in the SDK tutorials folder, one for each of the sample applications. In addition, NAGRA provides a tool, the Application Controller, that can be used to automatically create and sign a new installation package from a valid collection of files.

Permissions and the Application Metadata File

When an application is installed, its application metadata file is immediately read and processed, and its permissions automatically validated by the Application Information Manager (AIM). Later, when a running application attempts to use a component’s methods, its permissions are checked by the component.

Application Permissions

This section describes the OpenTV OS application permission system.

Overview

Starting with OpenTV OS 5.1.3, a permissions-based application security mechanism has been put into place, guaranteeing that applications can access only authorized system operations, features, or resources.

Permissions are defined as authorizations (rights or privileges) granted to an application, allowing access to specific system resources in specific ways.

Two general categories of permissions are defined: those authorizing the use of CCOM-based services (service permissions), and those authorizing the use of system resources (resource permissions).

Service permissions allow access to various CCOM services, such as methods or inter-object communication; while resource permissions allow access to non-CCOM resources such as storage space, memory resources, or devices (camera, keyboard, sensor).

An application accesses a CCOM service by connecting to the component providing the service and invoking methods provided by the component; service permissions are automatically enforced by the component providing the service.

An application accesses non-CCOM resources (such as a networking facility, dynamic memory, local file storage, external media, etc.) via system capabilities depending on the resource; resource permissions are configured when the application is launched.

In neither case is a developer required to provide additional coding in order to “enforce” permissions (after the permissions are initially defined).

The application’s metadata file contains all the service and resource permissions authorized for the application, which are explained in detail in the following.

Permissions and the Application Metadata File

When an application is installed, its application metadata file is immediately read and processed, and its permissions automatically validated by the Application Information Manager (AIM). Later, when a running application attempts to use a component’s methods, its permissions are checked by the component.

Service Permissions

Service permissions are separated into two major categories:

  • Permission based on a CCOM API:
    Each permission authorizes the use of a specific API of the component.
  • Permission based on groups of related CCOM APIs:
    Each permission authorizes the use of a specific group of APIs; or, they may be based on the features that the component implements via its APIs, where each permission enables or constrains the use of the component's APIs in a specific manner.

Each CCOM service is identified by a globally unique service name, and each service permission is identified by a unique service permission string within the component providing the service.

These service names and service permission strings, in combination, identify the services and operations authorized for the application in the application metadata file.

Service permissions are explicitly defined in the application's metadata file, as in this example:

<otv:AUTHORIZATIONS>
    <otv:SERVICES>
        <otv:AppinfoManager>
            <otv:PERMISSIONS>MANAGE</otv:PERMISSIONS>
            </otv:AppinfoManager>
            <otv:ApplicationManager>
                <otv:PERMISSIONS>QUERY</otv:PERMISSIONS>
            </otv:ApplicationManager>
                [... other CCOM Objects...]
    </otv:SERVICES>
</otv:AUTHORIZATIONS>

The general format of service permissions is:

<otv:AUTHORIZATIONS>
<otv:SERVICES>
    <otv:CCOM_Object_Name>
        <otv:PERMISSIONS> {one or more Permission_Strings}
        </otv:PERMISSIONS>
    </otv:CCOM_Object_Name>
</otv:SERVICES>
</otv:AUTHORIZATIONS>

Where CCOM_Object_Name is the name of the CCOM object having permissions defined, and is one of the following:

  • AppinfoManager
  • Application
  • ApplicationManager
  • ConditionalAccess
  • ConfigManager
  • ControlCenter
  • DRM
  • EPG
  • HomeNetworking
  • HomeNetworkingScheduler
  • IpNetwork
  • MediaLibrary
  • PlayerManager
  • Scheduler
  • SINetwork
  • SoftwareUpgradeManager
  • System
  • UserAuth
  • WindowManager

Refer to the following section for valid permission strings.

CCOM Permission strings

CCOM service permissions are specified for each object. An application can have full, partial, or multiple CCOM object service permissions.

These permissions are listed in the API documentation for each method.

Note: If an object method is not listed as needing a specific permission, it does not require a permission in order to be accessed. For example, getConnectionInfo() (part of the SINetwork CCOM object), requires no permission to use.

Deprecated methods are the only exception; all deprecated methods require ADMIN permission, even if not explicitly stated elsewhere.

Additional note: The global methods addEventListener() and removeEventListener(), available to all CCOM objects, do not require permissions in order to be used.

The following table lists the valid permission strings. Note that not all permission strings are valid or useful for all CCOM Objects.

Permission String Type Definition
QUERY Generic Allows read-only access to existing data, with no side effects. Reading sensitive data may require higher rights (such as MANAGE).
CONTROL Generic Allows for operating on existing objects, e.g. in order to play or connect to a data source. CONTROL implies QUERY. CONTROL allows also inter-application messaging.
MANAGE Generic Allows deleting, updating, creating, saving data or objects, changing their state, etc. MANAGE implies CONTROL.
ADMIN Generic The same as MANAGE but also includes global effects on the set-top box state which could be harmful, e.g. set time, install applications, perform a factory reset, etc. ADMIN implies MANAGE\ NOTE: All deprecated methods require the ADMIN permission.
Profile_1 to Profile_8 Specific Defines configuration tree access. Used only with ConfigManager.
ENCRYPT Specific Allows access to encrypted configuration tree settings. Used only with ConfigManager.

An outline of the various configuration setting locations and theirinteractions follows:

Path or File Description Notes
\[application installation folder\]/OTVAppMetadata.xml The path and name of the application configuration file for the application having permissions defined. This file contains all the permissions defined for the application, and references one or more network access profiles used by the configuration manager, and might further restrict the permission paths defined by them.
/system/opentv/configman/profiles Location of access profiles on the network, used to define configuration manager permissions. Defines the default paths accessible by PROFILE_1 to PROFILE_8\ Paths defined in these files should include paths required by applications referencing them; applications cannot define paths not already contained within one or more of these files.
/system/opentv/otvsec/memory-resource-mapping Defines the maximum memory values. String values are either SMALL, MEDIUM, or LARGE, and are referenced by the application configuration file. The actual memory size values are defined by integer at the network configuration location.
/applications/AUTHOR_Name/App_ID Defines the network location for the application’s specific folder. Heavy restrictions exist for the characters allowed in these path components; refer to the Application-specific Directory Structure for details. Must match values defined in the application configuration file.

Configuration Manager permissions

The Configuration Manager object does not operate like other objects.

Instead of defining permissions for how the Configuration Manager interacts with other objects, this set of permissions defines how the Configuration Manager interacts with and reads and modifies the configuration tree.

Permissions are not defined on a method-by-method basis. Permissions apply to all methods in the Configuration Manager object equally and uniformly.

Nine permission strings are used with this object:

  • ENCRYPT
    Allows an application access to selected encrypted parts of the configuration tree.
  • PROFILE_1, PROFILE_2, PROFILE_3, PROFILE_4, PROFILE_5, PROFILE_6, PROFILE_7, PROFILE_8
    Eight profiles that control the amount of access the application has to the configuration tree. These profiles are defined on a network-by-network basis.

Application-specific directory structure

Application-specific configuration settings are stored in specific directories within the /applications subtree, subject to the following restrictions:

  • An application producer has a producer-specific configuration directory under /applications, the name of which matches the value of the AUTHOR element in the application metadata file. For example, a producer with the AUTHOR value of jimmy-X must have a producer-specific directory at /applications/jimmy-X.
  • Each application from the same producer has an application-specific configuration directory under the producer-specific configuration directory of its producer, the name of which matches the value of the APP_ID element in the application metadata file. For example, an application with APP_ID values of application-Y and application-Z, both from producer jimmy-X, each must have an application-specific configuration directory at /applications/jimmy-X/application-Y and /applications/jimmy-X/application-Z, respectively.
  • Naming restrictions:
    The AUTHOR and APP_ID values must not contain any of the following characters: /, \\, \t, \r, \n, , $, &, < >, ,, +, =, #, !, ( ), , |, [ ], ?, ~, ', ;, *. Due to these naming restrictions, the Configuration Manager replaces any non-conforming characters from the AUTHOR or APP_ID values from the application metadata with an underscore ('_') when forming the producer- or application-specific directory name.
  • In a sandboxed runtime environment, an application accesses a configuration setting within its application-specific directory by using a relative path from the root of its application-specific directory. For example, if application-Y from producer-X needs to access a setting named my-key-Y in the subdirectory my-subdir-Y within its application-specific directory, it would use the relative keypath of my-subdir-Y/my-key-Y (or, optionally, ./my-subdir-Y/my-key-Y), which would access the setting found at the absolute path /applications/producer-X/application-Y/my-subdir-Y/my-key-Y.
  • In a non-sandboxed runtime environment, an application accesses a configuration setting within its application-specific directory by using an absolute path from the root of the configuration tree, e.g.: /applications/producer-X/application-Y/my-key-Y.
  • In a sandboxed runtime environment, an application accesses a configuration setting within its producer-specific directory by using a relative path of .. (two consecutive dots) that refers to its producer-specific directory. For example, if application-Y from producer-X needs to access a setting named my-producer-key-Y in its producer-specific directory, it would use the relative path of ../my-producer-key-Y, which would access the setting found at the absolute path /applications/producer-X/my-producer-key-Y.
  • In a non-sandboxed runtime environment, an application accesses a configuration setting within its producer-specific directory by using an absolute path from the root of the configuration tree, e.g.: /applications/producer-X/my-producer-key-Y.

To ensure an application runs properly in either a sandboxed or nonsandboxed runtime environment, applications should be written to access configuration settings using only absolute path names.

New applications should be designed to use application-specific and producer-specific directories for settings.

Be aware that an application-specification configuration directory of an application is removed when the application is uninstalled.

Note: For more details about how the configuration tree is structured, refer to the Configuration Guide.

Access profiles

Application access to configuration settings is limited by default as follows:

  • read-write access to settings in its own application-specific configuration directory, and
  • read-only access to settings in its producer-specific configuration directory.

To access a configuration setting elsewhere in the configuration tree, even the application-specific directory of another application from the same producer, the application must have explicit permission to access the directory containing the setting.

This permission is specified by an access profile in the application’s metadata file, as well as the allowable paths defined in /system/opentv/configman/profiles.

Eight possible access profiles, PROFILE_1 to PROFILE_8, control this access. An access profile consists of a list of one or more access permissions, including an access mode (read-only, read-write, or no-access), and a configuration pathname for the configuration subtree covered by the profile.

An application with a particular access profile is allowed to access configuration settings via the absolute pathname in the profile and the specified access mode in the profile, in addition to the configuration settings in its application-specific directory and producer-specific directory. The access profile definitions are stored as string lists named profile-1 to profile-8 in the /system/opentv/configman/profiles configuration subtree.

At present, placeholders exist (empty lists) for profile-1 to profile-7 under /system/opentv/configman/profiles. A defined profile-8 exists in the Configuration Manager default XML file as well; this profile, defined to permit read-write access to the entire configuration tree, is currently required by various built-in EPG applications (Gravity, e.g.), which need to access configuration settings throughout the configuration tree. The metadata for these applications has been modified to include PROFILE_8 permission. Without this profile, these applications fail at launch.

A system default profile can be found at /system/opentv/configman/profiles/system. This profile defines read-only access to the /system/opentv/rtes and /system/opentv/services subtrees, which is needed to run any application.

An additional network default profile is defined at /system/opentv/configman/profiles/network, although as currently defined it is an empty list, and it may be used to define a network-specific profile that is needed to run any application.

Changing the profile definitions

Default profile paths are defined in /system/opentv/configman/profiles.

Three definitions are allowed when defining profiles:

  • readwrite
    Allows for read-write access to the associated directory and any directory below it.
  • readonly
    Allows read-only access to the associated directory and any directory below it.
  • noaccess
    Neither read nor write access is granted to the associated directory nor any directory below it.

For example, suppose PROFILE_1 is needed to allow an application to access the settings in the following subtrees: * read-write access to /users/preferences * read-only access to /applications/common * read-only access to /users/default

The access profile is defined as a string list in the metadata file with the access permissions: * readwrite:/users/preferences * readonly:/applications/common * readonly:/users/default

If an application has PROFILE_1 specified in its metadata file, the application is allowed to read or write settings in or below /users/preferences and read settings in or below /applications/common and /users/default.

If PROFILE_2 is required to allow an application from producer-X to read or write the settings of application-Y, also from the same producer, i.e., to read or write settings in or below /applications/<producer-X>/<application-Y>, the access profile is defined as a string list at /system/opentv/configman/profiles/profile-2 containing the access permission:

readwrite:../<application-Y>

Then, if an application from producer-X, say application-Z, has the profile_2 permission specified in its metadata file, the application is allowed to read or write settings in or below /applications/<producer-X>/<application-Y>.

Any application from producer-X with the PROFILE_3 permission specified in its metadata is allowed to read the settings of any other application from producer-X. Since an application is always allowed to read or write its own settings and to read the settings of its producer, the access permissions readwrite:. and readonly:.. are implied and don’t need to be explicitly specified.

To prevent access to part of a subtree even though other parts of the subtree are accessible, noaccess is used. For example, suppose that PROFILE_4 should allow read-only access to the /users/preferences subtree but not allow access (neither read-only nor read-write) to the /users/preferences/parental-rating setting. In this case, the access profile /system/opentv/configman/profiles/profile-4 is defined as a string list containing the access permissions: * readonly:/users/preferences * noaccess:/users/preferences/parental-rating

An application can specify more than one access profile in its metadata. In general, the order of the profiles specified in the application's metadata is not significant, nor is the order of access permissions within an access profile. However, if the same configuration pathname is specified more than once for the same application (because the pathname appears in more than one profile specified by the application or because the pathname appears more than once in the same profile), then the last sequential appearance of the pathname and the associated access mode replaces any previous appearance of the pathname and associated access mode.

Sample profile definition

Partial file example, located in /system/opentv/configman/profiles.

<dir name="configman">
    <dir name="profiles">
    <!-- profiles that are specified in app metadata -->
    ...
    <entry name="profile-3" type="list" ltype="string">
    </entry>
    <entry name="profile-4" type="list" ltype="string">
    </entry>
    <entry name="profile-5" type="list" ltype="string">
    </entry>
    <entry name="profile-6" type="list" ltype="string">
    </entry>
    <entry name="profile-7" type="list" ltype="string">
    </entry>
    <entry name="profile-8" type="list" ltype="string">

<!-- profile for builtin EPG apps -->
  <li type="string">
  <stringvalue>readwrite:/</stringvalue>
  </li>
    </entry>
    </dir>
</dir>

Encrypt

Application access to encrypted configuration settings is allowed only if the application’s metadata file specifies the ENCRYPT permission. In the absence of an access profile in the application’s metadata, an application with ENCRYPT permission is allowed read-write access to encrypted settings in its application-specific directory and read-only access to encrypted settings in its producer-specific directory.

If an application with ENCRYPT permission also has one or more access profile permissions, the application is allowed to access encrypted settings in the subtrees specified by the corresponding access profiles as constrained by the corresponding access mode.

Resource permissions

Resource permissions are defined in the application metadata file, with some definitions for memory maximums also found at /system/opentv/otvsec/memory-resource-mapping.

The following system resources are currently supported:

  • Network access:
    The <otv:NETWORK> resource permission element allows the application to use network interfaces.
  • RAM usage:
    The <otv:MEMORY> resource permission element specifies how much RAM the application is allowed to use. The text content of the element is either SMALL, MEDIUM, or LARGE. The corresponding memory size values are defined by integer configuration settings under /system/opentv/otvsec/memory-resource-mapping in the default configuration tree.
  • Local storage:
    The <otv:STORAGE> resource permission element allows the application to use local persistent storage. Currently, only the presence of this permission is required to allow local storage usage, without constraint on how much is used. Presence of string values SMALL, MEDIUM, or LARGE has no effect.
  • Key stealing:
    The <otv:KEYS> resource permission element defined the list of keys that the application is allowed to steal when it is not in focus. The text content of the element is a list of logical key names that may include any of the following:

    • DOM_VK_ENTER
    • DOM_VK_DELETE
    • DOM_VK_LEFT
    • DOM_VK_RIGHT
    • DOM_VK_UP
    • DOM_VK_DOWN
    • DOM_VK_PAGE_UP
    • DOM_VK_PAGE_DOWN
    • OTV_RED
    • OTV_BLUE
    • OTV_YELLOW
    • OTV_GREEN
    • OTV_0
    • OTV_1
    • OTV_2
    • OTV_3
    • OTV_4
    • OTV_5
    • OTV_6
    • OTV_7
    • OTV_8
    • OTV_9
    • OTV_F6
    • OTV_F7

An example from an application configuration file follows, in which network access is permitted, local storage is permitted, four keys are active, and the memory permission is MEDIUM:

...
<otv:RESOURCES>
    <otv:NETWORK>
    <otv:STORAGE>SMALL</otv:STORAGE>
    <otv:KEYS>OTV_YELLOW OTV_BLUE OTV_F6 OTV_F7</otv:KEYS>
    <otv:MEMORY>MEDIUM</otv:MEMORY>
</otv:RESOURCES>
...

Sample permission-enabled application metadata file

A sample file follows, defining an application with five CCOM object permissions, as well as the following resource permissions: network, memory, local storage, and four keys.

<?xml version="1.0" encoding="UTF-8"?>
<AIM>
<NAME>app_portal_test</NAME>
<AUTHOR>OPENTV</AUTHOR>
<AUTHOR_HREF>http://www.nagra.com/dtv/</AUTHOR_HREF>
<AUTHOR_EMAIL>gqyu@opentv.com</AUTHOR_EMAIL>
<APP_ID>app_portal_test_id</APP_ID>
<APP_TYPE>svg</APP_TYPE>
<APP_VER>3.4</APP_VER>
<START_ARG>portal.svg</START_ARG>
<otv:AUTHORIZATIONS>otv:SERVICES>
    <otv:AppinfoManager>
        <otv:PERMISSIONS>MANAGE</otv:PERMISSIONS>
    </otv:AppinfoManager>
    <otv:ApplicationManager>
        <otv:PERMISSIONS></otv:PERMISSIONS>
    </otv:ApplicationManager>
    <otv:Application>
        <otv:PERMISSIONS>ADMIN</otv:PERMISSIONS>
    </otv:Application>
    <otv:System>
        <otv:PERMISSIONS>ADMIN</otv:PERMISSIONS>
    </otv:System>
    <otv:IpNetwork>
        <otv:PERMISSIONS>ADMIN</otv:PERMISSIONS>
    </otv:IpNetwork>
    <otv:ConfigManager>
        <otv:PERMISSIONS>PROFILE_8 ENCRYPT</otv:PERMISSIONS>
    </otv:ConfigManager>
</otv:SERVICES>
<otv:RESOURCES>
    <otv:NETWORK/>
    <otv:STORAGE>SMALL</otv:STORAGE>
    <otv:KEYS>OTV_YELLOW OTV_BLUE OTV_F6 OTV_F7</otv:KEYS>
    <otv:MEMORY>MEDIUM</otv:MEMORY>
/otv:RESOURCES>
</otv:AUTHORIZATIONS>
</AIM>

Multiple Application Support

Overview

As of OpenTV OS 5.1.3, more than one application can be run concurrently, limited only by resource availability (memory, CPU, etc.).

Application installation and control primarily use two CCOM objects: the Application Information Manager (AIM), and the Application Manager (AppMan).

Application Information Manager

The Application Information Manager (AIM) object is responsible for storing information about applications available on the system, as well as applications capable of being downloaded in the future. This information consists of the application name, metadata, and other details.

Using AIM object methods, developers are able to download and install applications, uninstall them, update them, and enforce credentials. Applications are packaged as W3C widgets and installed using installApp(), which checks certificates and permissions, and does other necessary bookkeeping before installing the application.

Application Manager

Once an application has been installed, the Application Manager (AppMan) object methods can be used by developers to control applications by:

  • Starting, stopping, and querying applications about their status, in addition to launching an application, giving it focus (making it display on top of any other application).
  • Transmitting messages between applications.
  • Creating notifications about application changes, such as application launched, application destroyed, etc.

Key stealing is accomplished using the Windows Manager.

Manipulating applications

In general, Application Manager object methods are responsible for controlling applications. These methods allow an application to:

  • Launch an application.
  • Destroy a running application.
  • Query an application’s status, or list the currently running applications.
  • Send messages to another applications.

The Windows Manager object methods allows an application to “steal” keys (receiving input from the keyboard via events), however there are limitations to this:

  • Key stealing is allowed only for keys defined in the <resource> section of the application metadata file. In this example, the OTV_YELLOW OTV_BLUE keys are defined, and therefore may be captured:

    <otv:RESOURCES>
        <otv:NETWORK/>
        <otv:STORAGE>SMALL</otv:STORAGE>
        <otv:KEYS>OTV_YELLOW OTV_BLUE</otv:KEYS>
        <otv:MEMORY>MEDIUM</otv:MEMORY>
    </otv:RESOURCES>
    
  • Keys are not automatically captured when the application starts; use the Windows Manager registerInputEvents() method and set the winmanInputEventTypes to define the capture keys.

The following MultiApp issues should also be kept in mind:

  • Applications are, in general, “persistent” meaning that applications relaunch automatically should they stop unexpectedly (due to a reboot, for example).
  • The only way to transmit information between applications is via CCOM.ApplicationManager.sendMessage().
  • Application resource usage and application permissions are defined by the application metadata file and checked/implemented during installation. Care should be taken not to overload the system by running too many applications, whose additive demands upon CPU and other resources might cause slowdowns.

Manipulate multiple applications step-by-step

What follows is a rough outline of how to manipulate multiple applications using Application Manager and Windows Manager methods.

  1. Let’s assume three applications, App1, App2, and Switcher have been successfully installed on the network via the Application Information Manager’s installApp() method. Switcher is a master application, already launched, which sits in the background and controls the other two applications.
  2. The two applications (App1 and App2) have been assigned global UUID numbers by appInstall(), which uniquely distinguishes them.
  3. The Switcher application, already running, launches these two applications using launchApplication(), which requires the UUID values of the two applications. Listen for the launchApplicationOK event, and if two events are generated (one for each application), both applications should be running.
  4. To double-check they are running, call isApplicationRunning() and listen for the isApplicationRunningOK event. If two events are returned, it serves as confirmation that App1 and App2 are both running.
  5. When an application has focus, it captures all keys except those stolen by other applications. In order to set an application to capture keys, use the Windows Manager object and the registerInputEvents() method, which allows any application to “steal” keys from input events. As always, the only keys an application is allowed to capture are those defined in its application metadata file. Switcher has been configured to steal keys from both App1 and App2 when they are running.
  6. When Switcher steals a remote control key press, indicating that the user wants App1 to close, Switcher uses CCOM.ApplicationManager.destroyApplication() to close App1. Switcher again has focus since it is the only currently-running application.
  7. Should the user wish to run App2, he presses the appropriate button. Switcher receives the input and uses launchApplication() to launch App2, which when it starts will have focus over Switcher.

In general, when multiple applications are run concurrently, one application serves as the main “switcher,” determining which applications will be shut down or started, and therefore which application currently has focus.

Video Resource Management

In a MultiApp environment more than one application can be running at the same time, each app may be playing video at the same time. Because the number of video decoders is limited in any chipset, they may need to be re-allocated dynamically to different players, within the same application or among different applications.

Priority

Priority among Multiple Applications

The video resource priority among various applications will be in the following order:

  • The focused application has the highest priority
  • All blurred applications according to their z-order stacking
  • All hidden applications according to their z-order stacking
  • All suspended applications according to their z-order stacking

Priority within the Same Application

The video resource priority within the same application will be in the following order:

  • The priority of the player(s) assigned using

    CCOM.PlayerManager.setPlayerInstancePriorities() This should be used by the applications using PIP to give higher priority to the MAIN window, even if the MAIN window has a lower zIndex value than others.

  • The video window with highest <video> attribute zIndex value.

    Within children of the same parent, the <video> element with a higher zIndex value is shown above others.

Example

<div id="videoMain" style="position: absolute; left: 0px; top: 0px;">
    <video id="videoMain" width="1280" height="720" src="" otv-video-destination="display://app-id-1-MAIN" />
</div>

<div id="videoSub" style="position: absolute; left: 600px; top: 25px;">
    <video id="videoSub" width="480" height="270" src="" otv-video-destination="display://app-id-1-PIP" />
</div>

function updateZindex(vidElemId, value)
{
    var vidElem = document.getElementById(vidElemId);
    vidElem.style.zIndex = value;
}

// set Zindex of videoMain to be below videoSub.
// Incase of resource conflict, the videoSub will have higher priority as it has higher zIndex
updateZindex('videoMain', 1)
updateZindex('videoSub', 2)

// Set videoMain to have higher resource priority than videoSub

var playerInstanceHandleMain = 0;
var playerInstanceHandleSub = 0;

// Register for InstanceCreated event.
playerMan = CCOM.PlayerManager;
playerMan.addEventListener("onPlayerInstanceCreated",onPlayerInstanceCreated);

// associate player handler with destUri
onPlayerInstanceCreated = function(e) {
    console.log("onPlayerInstanceCreated event received");
    console.log("destUri:" + e.playerInfo.destUri);

    if (e.playerInfo.destUri == "display://app-id-1-MAIN")
        playerInstanceHandleMain = e.playerInfo.instanceHandle;

    if (e.playerInfo.destUri == "display://app-id-1-PIP")
        playerInstanceHandleSub = e.playerInfo.instanceHandle;
}

// Set videoMain to have higher resource priority than videoSub
var Players = new Array;

Players[0].instanceHandle = playerInstanceHandleMain;
Players[0].priority = playerMan.INSTANCE_PRIORITY_HIGH

Players[1].instanceHandle = playerInstanceHandleSub;
Players[1].priority = playerMan.INSTANCE_PRIORITY_LOW

// Incase of resource conflict, the videoMain will have higher priority as it has higher player priority

res = playerMan.setPlayerInstancePriorities(Players);
if(res.error) {
    console.log("Failed to setPlayerInstancePriorities: "+res.error.domain + res.error.name + res.error.message);
}
else {
    console.log("Success setPlayerInstancePriorities LOW for handle " + playerInst.instanceHandle);
}


Conflicts

All players from applications that are not in focus are considered as non-critical as far as user experience is concerned. It is only when a player of the application in focus is going to be impacted, a conflict is generated in order to let the user decide. All other players will not generate conflicts. An application like GUIDE/Control App should resolve the conflict.

Application Metadata File

Overview

The application metadata file (OTVAppMetadata.xml) is required in order to install, configure, and define applications. It is part of an application installation package, and when installed is located in the base application folder.

A typical example follows:

<?xml version='1.0' encoding='UTF-8'?>
<AIM>
    <AUTHOR>NAGRA</AUTHOR>
    <NAME>CCOMTutorial</NAME>
    <AUTHOR_HREF>http://www.nagra.com/dtv/</AUTHOR_HREF>
    <AUTHOR_EMAIL>contact@opentv.com</AUTHOR_EMAIL>
    <RUNTIME_PRIORITY>0</RUNTIME_PRIORITY>
    <APP_ID>CCOMTutorial1</APP_ID>
    <APP_TYPE>svg</APP_TYPE>
    <APP_VER>1_0</APP_VER>
    <START_ARG>launch-html.svg</START_ARG>
    <otv:AUTHORIZATIONS>
        <otv:SERVICES>
            <otv:AppinfoManager>
                <otv:PERMISSIONS>MANAGE</otv:PERMISSIONS>
                </otv:AppinfoManager>
                <otv:ApplicationManager>
                    <otv:PERMISSIONS>QUERY</otv:PERMISSIONS>
            </otv:ApplicationManager>
        </otv:SERVICES>
    </otv:AUTHORIZATIONS>
</AIM>

A complete list of fields and options for this file are defined in the following section.

Application metadata file structure

In general, the application metadata file should have only one entry for each field; given duplicate entries, the first is ignored.

Queryable fields are those that can be accessed via: CCOM.AppinfoManager.getAppinfoByQuery().

Name Type Description Required? Queryable?
APP_ID STRING The application ID. It must be unique for the AUTHOR. It should remain constant in order to update the application in the future. Yes Yes
APP_SIZE NUMBER The size of application, in bytes, in persistent storage like FLASH. No Yes
APP_TYPE STRING The application type. The supported application types are: html An HTML/JavaScript application, run via otvwebkit. svg An SVG application, run via Ekioh. native A native application, run using the native environment. Yes Yes
APP_VER STRING The version of the application. AUTHOR can decide the format of the version string. Yes Yes
APPLICATION_CLASS STRING The application class must be SYSTEM. Optional (if absent indicates a non-system application). Applications in the SYSTEM class are the applications necessary for the set-top box to function, such as the main UI. No Yes
AUTHOR STRING The AUTHOR represents person or organization creating the application. Yes Yes
AUTHOR_EMAIL STRING The AUTHOR’s email address. Yes Yes
CCOM_MINOR_VERSION NUMBER The minor version of CCOM that this application is compatible with. Optional. No Yes
CCOM_MAJOR_VERSION NUMBER The version of CCOM that this application is compatible with. Mandatory. Yes Yes
AUTHOR_HREF STRING The AUTHOR's URL, pointing to its web site or profile on a social network. Yes Yes
DIAL_ENABLED BOOLEAN This field is required for the applications that support DIAL. It is, by default, disabled. No Yes
ICON STRING The application icons are used by the applications, such as portal or GUIDE, to display the list of installed applications in the system. The application can specify one or more application icons. If there are multiple icons specified by the application, the portal or Guide may choose to display the icon that is best suited for the platform. If the application does not specify any ICON, then a default icon may be applied based on the network configuration. An icon can be of any file format supported by WebKit. If an icon file is provided, it is recommended that the resolution be at least 64x64. The naming convention should follow this form: <app_name>_<res>_<height>_<width>.<format>. This icon name is used by the portal or Guide to choose the best-suited icon to be displayed based on the platform—e.g. Gravity_720p_64_64.png. Coding example: <ICON><ICON_PATH>Gravitiy_720p_64_64.png</ICON_PATH></ICON><ICON> <ICON_PATH>Gravity_1440p_64_64.png</ICON_PATH></ICON> No Yes
INSTALLED_DATE_SECONDS NUMBER The date application was installed; the value is the number of seconds since 1970-01-01. No Yes
LAUNCH_MODE STRING The launch mode of the application, either FOCUSED or SUSPEND. Default is FOCUSED. No Yes
LICENSE STRING Describes the software license of the application. It can be a usage agreement, redistribution statement, or copyright license under which the application is provided. No Yes
NAME STRING Name of the application. An optional <SHORT_NAME> subelement is also supported, defining a truncated name for the application. For example: <NAME>Poker Millions Online Tournament <SHORT_NAME>Poker</SHORT_NAME> </NAME> Yes Yes
NOTIFY_ON_LOW_POWER STRING This field indicates whether the application supports handling the requestActionSignal for the REQUEST_LOW_POWER action type. If the value is TRUE, then the requestActionSignal notification with a REQUEST_LOW_POWER action type is sent to the application. The Application RunTime performs default actions on behalf of the application if the value is FALSE. The default value is FALSE. Note that this setting will be deprecated in 5.1.5, and should be used only for testing in 5.1.4. No Yes
START_ARG STRING The start file in the application package to be loaded at application launch. Yes Yes
SUPPORT_SHOW BOOLEAN This field indicates if the application supports handling the requestActionSignal for the REQUEST_SHOW action type. If the value is TRUE then the requestActionSignal notification with a REQUEST_SHOW action type is sent to the application. The Application RunTime performs default actions on behalf of the application if the value is FALSE. The default value is FALSE. Note that this setting will be deprecated in 5.1.5, and should only be used for testing in 5.1.4. No Yes
SUPPORT_SUSPEND_MODE STRING This field indicates if the application supports handling the requestActionSignal for the REQUEST_SUSPEND action type. If the value is TRUE then the requestActionSignal notification with a REQUEST_SUSPEND action type is sent to the application. The Application RunTime performs default actions on behalf of the application if the value is FALSE. The default value is FALSE. Note that this setting will be deprecated in 5.1.5, and should only be used for testing in 5.1.4. No Yes
USAGE STRING Defines the application’s usage. This value can be used to filter certain kinds of applications, for example “Game”, “Guide”, etc. No Yes
Permission-based
<otv:AUTHORIZATIONS> STRING Top-level permission element. Yes No
<otv:RESOURCES> Element containing application resource permissions, using sub-elements <otv:NETWORK>. <otv:STORAGE>, <otv:KEYS>, and <otv:MEMORY>. Yes No
<otv:SERVICES> Element containing application access permissions for individual CCOM objects, using sub-elements <otv:PERMISSIONS>, and <otv:[CCOM_Object_Name]>. The subelement <otv:ALL> is also supported, and indicates the application has administrative permission for all CCOM objects; must be used in conjunction with <otv:PERMISSIONS>ADMIN</otv:PERMISSIONS> or <otv:PERMISSIONS>*</otv:PERMISSIONS>, which both indicate full access. For example: <otv:SERVICES> <otv:ALL> <otv:PERMISSIONS>*</otv:PERMISSIONS> </otv:ALL> </otv:SERVICES> Yes No