Platform

Platform is the root object of the solidAPI, which exposes sub-modules that deals with specific functionality. The specific functionality can be found in the menu on the left under Namespaces.

A number of conventions are common to the entire API and will be discussed hereafter.

Asynchronicity
The solidAPI is fully asynchronous. The various function calls never return values directly. Instead, they return a Promise. Promises can be used to retrieve return values asynchronously and they can be easily chained together.

Here is an plain old synchronous call:

var result = getResult( arg )
console.log( "Function getResult returned", result )

This is the equivalent asynchronous call:

getResult( arg ).then( function( result ) {
    console.log( "Function getResult returned", result )
} )

Here is an example of chaining Promise calls:

getResult( arg )
.then( function( result ) {
    console.log( "Function getResult returned", result )
    return processResult( result )
} )
.then( function( processed ) {
    console.log( "Function processResult returned", processed )
} )

*Sync versions of functions
Some functions have an equivalent synchronous version. For example, both getInformation() and getInformationSync() are available. Only functions that return results or modify state have synchronous versions. Please do not to use these functions unless there is no other choice. The asynchronous versions are much faster.

Errors
Promises can't throw exceptions, an error handler has to be defined:

getResult( arg )
.then( function( result ) {
    console.log( "Function getResult returned", result )
} )
.catch( function( error ) {
    console.error( "Function processResult failed" )
} )

If an error occurs, the error handler will be called with an argument of type Platform.Error.

Signals
Occasionaly the platform will want to asynchronously inform the application of something that has happened, without the application needing to prompt it first. Traditionally these are called Events. However, there is also the concept of EPG Events. To avoid confusion, the term Signals will be used to refer to events asynchronously recieved from the platform. All Signals inplement the interface presented in Signal.

Templates
Assumed a function called getItems() which returns a list of items. Each individual item has 3 properties: id, name, and length. Normally getItems() would just return a list fully populated with items. The returned list would look like this:

[
    { id: 0, name: 'tv',    length: 23 },
    { id: 1, name: 'radio', length: 12 },
    { id: 2, name: 'all',   length: 35 }
]

This is fine, except when the list is gigantic, as is often the case with channel lists. Such lists force us to transfer huge chunks of data between application and platform. One solution we considered, was to return a list containing only the unique identifier of each item. The returned list now looks like this:

[ 0, 1, 2 ]

getItemInfo( 1 ).then( function( item ) {
    console.log( item )
    // prints -> { id: 1, name: 'radio', length: 12 }
} )

This solved the one-huge-response problem, but presented us with another problem: Sometimes we only need one specific property of every item (for example, we might want to filter the items by name, so we would only need that one property). We are still forced to transfer every propertiy of every item.

In the end we did the following: Functions that return lists have a template argument. A template is an Array of properties the returned items should have. So finaly, the call looks like this:

getItems( [ 'id', 'name' ] ).then( function( items ) {
    console.log( items )
    // prints -> [
    //     { id: 0, name: 'tv' },
    //     { id: 1, name: 'radio' },
    //     { id: 2, name: 'all' }
    // ]
} )

Notice: The template argument can be ignored (or pass null or any other falsy value instead of an Array), to disable the template and get all properties. In addition, the getItemInfo() function will be included in the API, if items shall be retrieved in its entirety.

Timestamps
Always use JS timestamps for dates. Whenever a date is expected as an argument, or is returned as a result, it should be encoded as a JS timestamp. A JS timestamp is the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.

Media Resource Locators (MRLs) Various Media Resources throughout the API will be addresed by their MRL. The MRL is a string simmilar in structure to a URL. The following Media Resources have MRLs:

• DVB Channels
• IP Streams
• Files
• Recordings

MRLs allows us to refer to different Media Resources using a common interface.