net-top-box technical reference - onelan digital signage€¦ · net-top-boxtechnicalreference 15...

ONELAN Digital SignageNet-Top-Box

Technical Reference

V9.4.0 (41487)

Copyright © 2010-2013ONELAN Ltd. All rights reserved.

ONELAN Digital SignageNet-Top-Box Technical ReferenceVersion: 9.4.0

The ONELAN Net-Top-Box digital signage appliance is amultimedia, multizoned solution capable of displayingstored media and live media, for example, RSS feeds,web pages, and broadcast or locally streamed TV. With abrowser-based user interface, the system is fullymultilingual, including all main European languages.

Copyright © 2010-2013 ONELAN Ltd. All rights reserved.

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, ormechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the writtenpermission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of the respectiveowners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume noresponsibility for errors or omissions, or for damages resulting from the use of information contained in this document orfrom the use of programs and source code that may accompany it. In no event shall the publisher and the author be liablefor any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by thisdocument.

Printed: 16 October 2018

Net-Top-Box Technical Reference

3

Table of ContentsPart 1: Introduction 7

1.1 Target Audience 7

Part 2: XML API Version 2 11

2.1 Prerequisites 11

2.1 Command List 11

2.2 Response List 13

2.3 Checking Capabilities 14

2.4 Player Local Information 152.4.1 Get All Player Local Information 15

2.4.2 Get Player Local Information 17

2.4.3 Set Player Local Information 18

2.5 Advance To 19

2.6 Ad Hoc Items 202.6.1 Get Ad HocTable Information 21

2.6.2 Set Ad HocTable Information 23

2.6.3 Get Ad HocText Information 24

2.6.4 Set Ad HocText Information 26

2.6.5 Get Ad HocTV Information 27

2.6.6 Set Ad HocTV Information 29

2.6.7 Get Ad HocRadio Information 30

2.6.8 Set Ad HocRadio Information 31

Part 3: XML API Version 1 35

3.1 External XML API 353.1.1 ChannelManager 35

3.1.2 Schedule 39

3.2 HTMLPlayer Services 413.2.1 Get RS-232 Buffer 41

3.2.2 Transmit RS-232 Data 42

3.2.3 HTTPGET Request 42

3.2.4 HTTPPOST Request 43

3.3 Sample Code 44

Part IIntroduction


7

Part 1: IntroductionThis document describes the application programming interfaces (APIs) to the Net-Top-Box (NTB).

The two APIs are:

l XMLAPI version 2.

l XMLAPI version 1 (deprecated).

Within this document you will find:

l General information about the APIs.

l Detailed information about each API command.

l Code examples.

The purpose is to help you get themost out of the NTB digital signage platform:

l Improving the efficiency and accuracy of the digital media played.

l Providingmore flexible control over when and how that media is played on the digital signage network.

As versions of the NTB software are released, the XMLAPI is updated to provide a consistent and easy to useinterface.

1.1 Target AudienceThis technical reference is intended for web developers and content designers who wish tomanage the NTBprogrammatically rather than through the browser user interface.

You require a good understanding of web technologies to use the APIs.

It is assumed you are familiar with the NTB user interface and with the contents of theNet-Top-Box User Guide.

Part IIXML API Version 2


11

Part 2: XML API Version 2The XMLAPI version 2 provides commands tomanage player local information, Advance To commands, and aselection of ad hoc items.

2.1 PrerequisitesTomake use of the version 2 XMLAPI commands, the application you write must conform to the prerequisitesdescribed in this section.

Youmust use HTTP POST to send the XML commands to the URLNTBxxxxx/XML2 (where xxxxx is the serialnumber of the target NTB). The NTB supports both the HTTP and HTTPS protocols.

Your applicationmust conform to these prerequisites:

l Has its content-type header set to text/xml.

l Accesses the interface using the credentials of a user with theXML Control permission.

l Handles the HTTP 401 status code and authenticates with the request URI.

l Its message data does not exceed 240,000 bytes in size (this is the current POST data size limit).

Note: Only Digest authentication is supported.

There are two types of command:

l Read-only – Use these to obtain settings from the NTB (they always start with get_).

l Modifying – Use these to change settings on the NTB (they always start with set_).

Youmust wrap all of your XML API calls in a container called <command_list> (see Command List for details). TheNTB returns a response to your request in a container called <response_list> (see Response List for details).

For debugging purposes, refer to the HTML-media-n.log file on the NTB (where n is an automatically incrementednumber). Locate that log file on the NTB by clickingMedia > Files & Folders and navigating to the/HOME/logs/player folder. The log contains:

l HTML player messages.

l JavaScript errors.

l Messages directed to the JavaScript console.log function.

2.1 Command ListWhen composing your XML API code, be aware of these characteristics of the <command_list> container:

l It can contain multiple commands.

l It cannot contain amixture of get_ and set_ commands.

l Processing stops on the first error unless you specify <command_list continue_on_error="yes">.

Before relying on a particular command, youmay want to confirm that the target version of the NTB supports it. Usethe get_all_capabilities command to do so (see Checking Capabilities for details).

The rest of this section describes the general syntax of the <command_list> container and lists the commands itsupports. Later sections describe the <command_list> syntax specific to each command.

Part 2: XML API Version 2

12

General Syntax

Typical Get Command:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><command_list>

<command_required command_id="xx"/></command_list>

XML Node Notes

<command_list> Root element for all requests.

<command_required> Command name.

---command_id A string you enter to uniquely identify each command. The NTB tags each responsein the <response_list> with the same command_id.

Typical Set Command:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><command_list>

<command_required command_id="xx" ><further_syntax />

</command_required></command_list>

XML Node Notes


<command_required> Command name.


---<further_syntax> Any additional syntax required to specify the settings.

Supported Commands

Following is the list of supported commands:

Command Purpose and Further Details

get_all_capabilities Checking Capabilities

get_all_player_local_info Get All Player Local Information

get_player_local_info Get Player Local Information

set_player_local_info Set Player Local Information

advance_to Advance To

get_ad_hoc_item_info item_name="table_name" Get Ad Hoc Table Information


13

Command Purpose and Further Details

set_ad_hoc_item_info item_name="table_name" Set Ad Hoc Table Information

get_ad_hoc_item_info item_name="text_entry_label" Get Ad Hoc Text Information

set_ad_hoc_item_info item_name="text_entry_label" Set Ad Hoc Text Information

get_ad_hoc_item_info item_name="tv_name" Get Ad Hoc TV Information

set_ad_hoc_item_info item_name="tv_name" Set Ad Hoc TV Information

get_ad_hoc_item_info item_name="radio_name" Get Ad Hoc Radio Information

set_ad_hoc_item_info item_name="radio_name" Set Ad Hoc Radio Information

2.2 Response ListThe NTB returns a response in a container called <response_list>. The NTB tags each response in the<response_list>with the same command identifier you entered for thematching command in the request<command_list>.

The status_code in the <response_list> element reflects the overall result of all the commands in the <command_list>. If all commands execute successfully, the NTB sets the status_code to 0.

The rest of this section describes the general syntax of the <response_list> container. Later sections describe the<response_list> syntax specific to each command.

General Syntax<?xml version="1.0" encoding="UTF-8" standalone="yes"?><response_list status_code="x">

<command_requested command_id="xx" status_code="x"><status>xxxxxxxxxxxxxxxx</status>

</command_requested></response_list>

XML Node Notes

<response_list> Root element for all responses.

---status_code Indicates the overall return status for the <command_list>:

0. All commands succeeded.

1. Invalid XML.

2. Partial failure: at least one command failed.

3. The <command_list> contained both get_ and set_ commands.

4. The request was sent with incorrect HTTP headers.

For all other errors, the NTB returns a status code of 99.

<command_requested> Command for which the NTB returns this response.

---command_id The unique command identifier you specified in the <command_list>.


14

XML Node Notes

---status_code Indicates the status return for the individual command in the <command_list>:

0. The NTB executed the command successfully.

1. There was an error whilst trying to execute the command.

2. The NTB did not execute the command as a previous command in the<command_list> failed to execute.

As well as those generic codes, some command groups have specific codes startingfrom 100. Those are listed at the beginning of each command group section.

---<status> Text describing the command's success or failure.

2.3 Checking CapabilitiesThe XMLAPI provides a capability-checkingmechanism for you to determine if the target NTB supports thecommands you want to use.

This mechanism can help enhance your application's robustness. By first checking for the supported commands, youcan implement an alternative approach if the command you want is not available.

Note: Capabilities are available in version 8.1.0 and later of the NTB software. For future viability, this is anassured backward-compatible interface.

Syntax<?xml version="1.0" encoding="UTF-8" standalone="yes"?><command_list>

<get_all_capabilities command_id="get cmd caps id"/></command_list>

XML Node Notes


<get_all_capabilities> Command name.


Sample Response<?xml version="1.0" encoding="UTF-8" standalone="yes"?><response_list status_code="0">

<get_all_capabilities command_id="get cmd caps id" status_code="0"><capability name="CAP_AD_HOC_ITEM_INFO_1"/><capability name="CAP_PLAYER_LOCAL_ITEM_INFO_1"/><capability name="CAP_ADVANCE_TO_1"/>

</get_all_capabilities></response_list>


15

XML Node Notes

<response_list> Root element for all responses

---status_code See Response List

<get_all_capabilities> Command for which status is being returned.

---command_id Is the same as was specified in the request.


0 – The NTB executed the command successfully.

1 – There was an error whilst trying to execute the command.

2 – The NTB did not execute the command as a previous command in the<command_list> failed to execute.

<capability> Element for holding each capability name.

---name Capability name.

2.4 Player Local InformationThe commands in this section allow you to get and set player local information:

l Get All Player Local Information

l Get Player Local Information

l Set Player Local Information

If youmake changes to the player local information it can immediately affect the conditional play items concerned.

Following is the return status code specific to theGet commands:

Status Code Meaning

100 The player local information file is not valid.

Following are the return status codes specific to theSet command:

Status Code Meaning

100 The player local information file is not valid.

101 The NTB failed to save changes to the player local information.

102 The NTB failed to update players with the changes to the player local information.

2.4.1 Get All Player Local Information

Get all player local information.

Syntax<?xml version="1.0" encoding="UTF-8" standalone="yes"?>


16

<command_list><get_all_player_local_info command_id="all local info"/>

</command_list>

XML Node Notes


<get_all_player_local_info> Command to get all player local Information.

---command_id The string you enter to uniquely identify the command. The NTB tags each responsein the <response_list> with the same command_id.


<get_all_player_local_info status_code="0" command_id="all local info"><data_player_local_info name="Unit Location">

<value>Henley-On-Thames</value></data_player_local_info><data_player_local_info name="Display in">

<value>Food section</value></data_player_local_info>

</get_all_player_local_info></response_list>

XML Node Notes


---status_code Indicates the return status for the whole <command_list>:


1. Invalid XML.





<get_all_player_local_info> The name of the requested command.

---command_id The command identifier you specified in the request.

---status_code Indicates the return status for the specific command. The generic codes are:




See Player Local Information for the command-specific return codes.

<data_player_local_info> Container element for each player local information item.


17

XML Node Notes

---name Player local Information name.

<value> Container element for the player local Information value list:

l All child text nodes represents a value for the specified name.

l Multiple values may be associated with a single name.

2.4.2 Get Player Local Information

Get values for a named player local information.


<get_player_local_info command_id="cmd_local" name="Unit Location" /></command_list>

XML Node Notes


<get_player_local_info> Command to get the named player local Information.


---name The name of the player local Information required.


<get_player_local_info status_code="0" command_id="cmd_local"><data_player_local_info name="Unit Location">

<value>Henley-On-Thames</value></data_player_local_info>

</get_player_local_info></response_list>


18

XML Node Notes




1. Invalid XML.





<get_player_local_info> The name of the requested command.







<data_player_local_info> Container element for the player local information item.

---name Player local Information name.

<value> Container element for the player local Information value list:

l Empty if there is no player local information for this name.

l All child text nodes represents a value for the specified name.

l Multiple values may be associated with a single name.

2.4.3 Set Player Local Information

Create or replace player local information.


<set_player_local_info command_id="cmd_local" name="local info1"><data_player_local_info>

<value>value 1</value><value>value 2</value><value>value 3</value>

</data_player_local_info></set_player_local_info>

</command_list>


19

XML Node Notes


<set_player_local_info> Command to set the player local Information.


---name The name of the player local Information to set.

<data_player_local_info> Container element for the player local Information value list.

<value> Optional. Container element for each player local Information value you want to set.


<set_player_local_info command_id="cmd_local" status_code="0"/></response_list>

XML Node Notes

<response_list> Root element for all responses



1. Invalid XML.





<set_player_local_info> The name of the requested command.







2.5 Advance ToSend anAdvance To command to all zones or to a named zone.

Syntax<?xml version="1.0" encoding="UTF-8" standalone="yes"?>


20

<command_list><advance_to rendezvous_name="rendezvous name" zone_name="zone name" command_id="1"/>

</command_list>

XML Node Notes


<advance_to> Command to send an Advance To command.


---rendezvous_name The name of the rendezvous point to which all zones or a named zone will advance.This is case-sensitive: enter the rendezvous point name exactly as written.

---zone_name Optional. Specify if you want only the named zone to advance to the rendezvouspoint. Otherwise, the NTB sends the Advance To command to all zones in thecurrently playing layout.


<advance_to command_id="1" status_code="0"/></response_list>

XML Node Notes




1. Invalid XML.





<set_ad_hoc_item_info> The name of the requested command.






2.6 Ad Hoc ItemsThe commands in this section allow you to get and set information for ad hoc items:


21

l Get Ad Hoc Table Information

l Set Ad Hoc Table Information

l Get Ad Hoc Text Information

l Set Ad Hoc Text Information

l Get Ad Hoc TV Information

l Set Ad Hoc TV Information

l Get Ad Hoc Radio Information

l Set Ad Hoc Radio Information

Following are the return status codes specific to theGet commands:

Status Code Meaning

100 The NTB could not find the ad hoc item.

101 The ad hoc table data file is invalid or corrupt.

102 The command is not supported for the named ad hoc item.

Following are the return status codes specific to theSet commands:

Status Code Meaning

100 The NTB could not find the ad hoc item.

101 The ad hoc table data file is invalid or corrupt.

102 The command is not supported for the named ad hoc item.

103 The input data is not valid for the specified ad hoc item

104 The input data does not match the specified ad hoc item.

2.6.1 Get Ad Hoc Table Information

Returns the data from all of the cells in an ad hoc table.


<get_ad_hoc_item_info item_name="adhoc table" command_id="user specified id"/></command_list>

XML Node Notes


<get_ad_hoc_item_info> Command to get the content of an ad hoc item.


22

XML Node Notes


---item_name The name of the ad hoc table.


<get_ad_hoc_item_info command_id="user specified id" status_code="0"><data_table item_name="adhoc table">

<row id="1"><cell id="A" ad_hoc="yes">Top-Left</cell><cell id="B" ad_hoc="no">Top-Middle</cell><cell id="C" ad_hoc="no">Top-Right</cell>

</row><row id="2">

<cell id="A" ad_hoc="no">Middle-Left</cell><cell id="B" ad_hoc="no">Middle-Middle</cell><cell id="C" ad_hoc="no">Middle-Right</cell>

</row><row id="3">

<cell id="A" ad_hoc="no">Bottom-Left</cell><cell id="B" ad_hoc="yes">Bottom-Middle</cell><cell id="C" ad_hoc="yes">Bottom-Right</cell>

</row></data_table>

</get_ad_hoc_item_info></response_list>

XML Node Notes




1. Invalid XML.





<get_ad_hoc_item_info> The name of the requested command.



23

XML Node Notes





See Ad Hoc Items for the command-specific return codes.

<data_table> Container element for the ad hoc table data.

---item_name The ad hoc table name.

<row> Container element for the row in the ad hoc table.

---id Unique identifier for the specific row.

<cell> Container element for the cell in the row. The text nodes represent the content youwant to update the cell with.

---id Identifier for the cell in the row.

---ad_hoc If yes an ad hoc user can update the contents of the cell.

If no an ad hoc user cannot update the contents of the cell.

2.6.2 Set Ad Hoc Table Information

Update the content of cells in an ad hoc table.


<set_ad_hoc_item_info item_name="adhoc table" command_id="user specified id"><data_table>

<row row_id="1"><cell col_id="A" >Override</cell>

</row><row row_id="3">

<cell col_id="B">2:1 Unicode - €ßß«</cell><cell col_id="C">2:2 Bottom-Right Red</cell>

</row></data_table>

</set_ad_hoc_item_info></command_list>

XML Node Notes


<set_ad_hoc_item_info> Command to set the content of an ad hoc item.


24

XML Node Notes


---item_name The name of the ad hoc table.

<data_table> Container element for the ad hoc table data.

<row> Container element for the row in the ad hoc table.

---id Unique identifier for the specific row.

<cell> Container element for the cell in the row. The text nodes represent the content youwant to update the cell with.

---id Identifier for the cell in the row.


<set_ad_hoc_item_info command_id="user specified id" status_code="0"/></response_list

XML Node Notes




1. Invalid XML.












2.6.3 Get Ad Hoc Text Information

Get the contents of an ad hoc text item.


25


<get_ad_hoc_item_info command_id="user specified id" item_name="adhoc text"/></command_list>

XML Node Notes




---item_name The entry label of the ad hoc text item.

Sample Responses

Plain Text Item:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><response_list status_code="0">

<get_ad_hoc_item_info command_id="user specified id" status_code="0"><data_text_plain item_name="adhoc text">Ad Hoc control test data</data_text_plain>


Rich Text Item:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><response_list status_code="0">

<get_ad_hoc_item_info command_id="user specified id" status_code="0"><data_text_rich item_name="adhoc text">Ad Hoc control test data</data_text_rich>


XML Node Notes




1. Invalid XML.








26

XML Node Notes






<data_text_plain>

<data_text_rich>

Container element for the ad hoc text item:

l <data_text_plain> if the text type is plain.

l <data_text_rich> if the text type is rich.

---item_name The ad hoc text name.

2.6.4 Set Ad Hoc Text Information

Update the contents of an ad hoc text item.

Syntax

Rich Text Item:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><command_list>

<set_ad_hoc_item_info command_id="user specified id" item_name="ad hoc Control"><data_text_rich>Ad Hoc control test data: modified</data_text_rich>


Plain Text Item:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><command_list>

<set_ad_hoc_item_info command_id="user specified id" item_name="ad hoc Control"><data_text_plain>Ad Hoc control test data: modified</data_text_plain>


XML Node Notes





27

XML Node Notes

---item_name The entry label of the ad hoc text item.

<data_text_plain>

<data_text_rich>

Container element for the ad hoc text item:

l <data_text_plain> if the text type is plain.

l <data_text_rich> if the text type is rich.

The text represents the updated content.


<set_ad_hoc_item_info command_id="user specified id" status_code="0"/></response_list>

XML Node Notes




1. Invalid XML.












2.6.5 Get Ad Hoc TV Information

Get a list of available ad hoc TV channels indicating the currently selected channel.


<get_ad_hoc_item_info command_id="user specified id" item_name="adhoc tv item"/></command_list>


28

XML Node Notes




---item_name The name of the ad hoc TV item.


<get_ad_hoc_item_info status_code="0" command_id="1"><data_tv item_name="ad hoc tv">

<choice selected="no">BBC NEWS 24 (S) Stream</choice><choice selected="yes">BBC ONE (S) Stream</choice><choice selected="no">AUX 1 Stream</choice><choice selected="no">CBBC Channel (S) Stream</choice><choice selected="no">BBC TWO (S) Stream</choice>

</data_tv></get_ad_hoc_item_info>

</response_list>

XML Node Notes




1. Invalid XML.












<data_tv> Container element for the ad hoc TV item.


29

XML Node Notes

---item_name Name of the ad hoc TV item.

<choice> Container element for the TV channel. The text node represents one channel.

---selected If yes, this is the currently selected channel.

If no, this is not the selected channel.

2.6.6 Set Ad Hoc TV Information

Add a new ad hoc TV channel.


<set_ad_hoc_item_info command_id="user specified id" item_name="ad hoc tv Control"><data_tv>

<choice>Channel 1</choice></data_tv>


XML Node Notes




---item_name The name of the ad hoc TV item.

<data_tv> Container element for the name of the new TV channel.

---<choice> The name of the new TV channel.




30

XML Node Notes




1. Invalid XML.












2.6.7 Get Ad Hoc Radio Information

Get a list of available ad hoc radio channels indicating the currently selected channel.


<get_ad_hoc_item_info command_id="user specified id" item_name="ad hoc radio example"/></command_list>

XML Node Notes




---item_name The name of the ad hoc radio item.


<get_ad_hoc_item_info status_code="0" command_id="1"><data_radio item_name="ad hoc radio example">


31

<choice selected="no">BBC Radio 1 (S) (Stream)</choice><choice selected="yes">BBC 6 Music (S) (Stream)</choice><choice selected="no">TECH TVG Absolute Radio (Stream)</choice>

</data_radio></get_ad_hoc_item_info>

</response_list>

XML Node Notes




1. Invalid XML.












<data_radio> Container element for the ad hoc radio item.

---item_name Name of the ad hoc radio item.

<choice> Container element for the radio channel. The text node represents one channel.

---selected If yes, this is the currently selected channel.

If no, this is not the currently selected channel.

2.6.8 Set Ad Hoc Radio Information

Add a new ad hoc radio channel.


<set_ad_hoc_item_info command_id="user specified id" item_name="ad hoc radio Control"><data_radio>Channel 1</data_radio>



32

XML Node Notes




---item_name The name of the ad hoc radio item.

<data_radio> Container element for the name of the new radio channel.



XML Node Notes




1. Invalid XML.












Part IIIXML API Version 1

35

Part 3: XML API Version 1The following sections describe the XMLAPI version 1.

This API is deprecated and will be removed in a future version. Use the version 2 XMLAPI for new applications.

3.1 External XML APIAll the external XML APIs can also be used frommedia running within the NTB HTML player.

The following APIs are available.

l Activate Schedule

l Channel Activate

l Channel Publish

l Get Channel Manager Report

3.1.1 Channel Manager

This section contains information that enables you to build very flexible content publishing and subscription networksusing ONELAN digital signage.

3.1.1.1 Channel Manager Status

Function

A detailed report of the channel manager state for the currently active channel on a publisher and the subscribedchannel for a subscriber.

In conjunction with other channel manager XML APIs, this can help build very flexible channel publishing workflows.

Requires

A user account on the NTB with theStatus Monitor permission.

An application that can process HTTP GET requests with digest or basic authentication. (Versions prior to 8.0support basic authentication only.)

Syntax

HTTP GET the URI /status/channel_manager.xml

Publisher

The following is returned:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><channel_manager_status role="publisher"><channel_control_file

channel_name="Channel 2"


36

channel_unique_id="2010-10-04 15:47:18"channel_href="file:channel/2"/>

<channel_control_publish state="Publishing - Copying channel files" ↵state_code="publishing"/><channel_file_list>

<channel_file href="file:control/channel_control.xml"

channel_url="file:channel/2/control/channel_control.xml.↵8aa5ea784c8ee936b15875c87f453a2de.channel" size="7785"/>

<channel_file href="file:control/colours.xml"

channel_url="file:channel/2/control/colours.xml.↵8b1c286d8e9e6c2403865df0e83f04c5c.channel" size="914"/>

<channel_file href="file:media/show/office/back/4x3/Red.png" ↵size="402437" last_error="pending"/>

<channel_file href="file:media/show/soundtrack/the_power_behind_full.mp3"↵size="4215118" last_error="pending"/>

</channel_file_list></channel_manager_status>

The state_code attribute indicates the current status of channel publish and can take any of not_published,publishing or published values.

Subscriber

The following is returned:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><channel_manager_status role="subscriber">

<channel_state_subscribe><active_channel state="activated"

channel_name="channel 1"channel_id="2010-09-27 11:32:21"activated_time="2010-10-04 16:15:39"/>

<pending_channel state="unknown"transfer_start_time="2010-10-04 16:15:29"transfer_end_time="2010-10-04 16:15:34"/>

</channel_state_subscribe><channel_control_subscribe state="Idle"

channel_control_url="ftp://ftpserver/channel/channel_id/control/channel_control.xml"/><channel_file_list>

<channel_file href="ftp://testproxy/channel/14533/control/channel_control.xml" ↵size="9984"/>

<channel_file href="file:control/ad_hoc_control_settings.xml" size="278"/><channel_file href="file:control/ad_hoc_form_settings.xml" size="1066"/><channel_file href="file:control/colours.xml" size="914"/><channel_file href="file:control/rs232_settings_default.xml

</channel_file_list></channel_manager_status>

The active_channel attribute can be either activated or never_activated.

Compatibility

Introduced in 7.4.


37

3.1.1.2 Get Channel Manager Report

Function

Provide information about the NTB channel manager to determine themode and state of all channels.

On a publisher, verify the status of channel publish completion by comparing the total_sizewith total_transferred_size.

On a subscriber, verify the status of channel subscription completion by comparing the total_sizewith total_transferred_size.

In conjunction with Channel Activate and Channel Publish, this provides amechanism to build flexible channelpublishing workflows.

Syntax

Example:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><get_channel_manager_report/>

Examples

Standalonemode example return XML:<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<channel_manager_report><channel_manager_standalone/>

</channel_manager_report>

Publisher mode example return XML:<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<channel_manager_report><channel_manager_publisher

multichannel_id="1" multichannel_active="yes"channel_name="Channel 1" channel_id="2010-09-27 11:32:21"channel_type="ftp" channel_href="ftp://ftpserver/channel/channel_folder"transfer_start_time="2010-09-27 11:32:26"last_connect_time="2010-09-27T11:32:26+0100"total_files="72" total_transferred_files="63"total_size="225393921" total_transferred_size="121803417"/>

<channel_manager_publishermultichannel_id="2" multichannel_active="no"channel_name="Channel 2"channel_type="local_disk" channel_href="file:channel/2"/>


Subscriber Mode Example Return XML:<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<channel_manager_report><channel_manager_subscriber

multichannel_id="1" multichannel_active="yes"last_poll_time="2010-09-30T15:15:35+0100"


38

channel_type="ftp" channel_href="ftp://ftpserver/channel/channel_folder/"pending_channel_name="channel1"pending_channel_id="2010-09-27 11:32:21"transfer_start_time="2010-09-30 15:15:36"next_connect_time="2010-09-30T16:15:36+0100"last_connect_time="2010-09-30T15:15:35+0100"total_files="72" total_transferred_files="59"total_size="225393921" total_transferred_size="38125373"/>


Compatibility

Introduced in 7.4.

3.1.1.3 Channel Publish

Function

A mechanism to publish the currently active channel.

Allows external applications to control when a channel gets published and when subscribers can activate the newchannel.

The currently active channel is published. Activate a channel using Channel Activate.

Requires

A user account on the NTB with theXML Control permission.

An application that can send HTTP POST requests with digest and basic authentication.

Syntax

Publish a channel and set it to be activated immediately:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><channel_publish/>

Publish the currently active channel and set it to be activated later:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><channel_publish activate_after="2010-02-13 01:20:00"/>

Return Status

HTTP status code 200 on success, 500 otherwise.

Compatibility

Introduced in 7.4.


39

3.1.1.4 Channel Activate

Function

A mechanism to activate a channel on the NTB Publisher.

Allows external applications to control channel activation. In conjunction with Channel Publish andGet ChannelManager Report, this allows a single publisher to publish tomultiple channels with verifiable publish completion.

Syntax

Activate a channel with a specified channel id:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><channel_activate multichannel_id="2"/>

The multichannel_id attribute can be extracted from theGet Channel Manager Report.

Return Status


Compatibility

Introduced in 7.4.

3.1.2 Schedule

A calendar of what layouts can play during a given time period.

3.1.2.1 Schedule Status

Function

A mechanism to get important information about schedule status.

This information can be used to determine schedules that can be used with Activate Schedule.

Requires

A user account on the NTB with theMonitor Status permission.

An application that can process HTTP GET requests with digest or basic authentication. (Versions prior to 8.0support basic authentication only.)

Syntax

HTTP GET the URI /status/schedule.xml

The returned XML has an element named schedule_config that contains details of the currently availableschedules.


40

Example return XML:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><status>

<schedule_status>~snip~

</schedule_status><schedule_config href="file:control/channel/active/schedule.xml">

<schedule_override name="special"↵href="file:control/channel/active/schedule/override/override_special.xml"/>

</schedule_config></status>

The schedule_override attribute can be used with Activate Schedule.

Compatibility

Introduced in 7.4.

3.1.2.2 Activate Schedule

Function

A mechanism to activate a specific schedule from the available schedules.

Allows external applications to control schedule overrides.

Syntax

Override with a special schedule:<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<activate_schedule href="file:control/channel/active/schedule/override/↵override_evening.xml"/>

Revert back to normal schedule:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><activate_schedule href="file:control/channel/active/schedule.xml" />

For schedules that can be used with activate_schedule, refer to Schedule Status.

Return Status


Compatibility

Introduced in 7.4.


41

3.2 HTML Player Services

Overview

The NTB HTML player displays HTML and Adobe Flash playlist items. Those items can execute scripts that interactwith NTB features.

In order to interact with the NTB, XMLweb services must be enabled for the HTML player and for each individualHTML playlist item. The XMLweb services are disabled by default.

Enable XML Web Services for the HTML Player

In the NTB UI:

1. Go to theSetup > Player Setup > Players page

2. Select theAllow XML web services to access external sites option to allow the HTML player to accessexternal sites. (The default is Do not allow XML web services to access external sites.)

Enable XML Web Services for Each HTML Playlist Item

Each HTML playlist itemmust also have its Page Services option enabled.

To enablePage Services:

1. Click the HTML playlist item's Edit button.

2. Click theStyle tab.

3. Check thePage Services option.

4. Click theSave Changes button.

3.2.1 Get RS-232 Buffer

Function

A mechanism to read and optionally clear RS-232 buffered input.

Allows external applications to query and optionally clear the RS-232 buffer. This allows devices with the RS-232interface to dynamically interact with the NTB.

Syntax

Get RS-232 buffered data without clearing the buffer:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><get_rs232_buffered_data clear_buffer="no"/>

Get RS-232 buffered data and clear the buffer:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><get_rs232_buffered_data clear_buffer="yes"/>

Return Status



42

Example

If the buffer contained 'Welcome to Digital Signage', the output will be:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rs232_buffered_data>

57656c636f6d6520746f204469676974616c205369676e616765</rs232_buffered_data>

The data element is the hex encoding of 'Welcome to Digital Signage'.

If the buffer is empty the output will be:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rs232_buffered_data></rs232_buffered_data>

Compatibility

Introduced in 8.0.

3.2.2 Transmit RS-232 Data

Function

A mechanism to send RS-232 output from the NTB.

Enables you to write dynamic applications that can drive external RS-232 devices.

Syntax

The datamust be encoded in hex format for transmission:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><transmit_rs232_data>61636b206669727374206d7367</transmit_rs232_data>

Return Status


Compatibility

Introduced in 8.0.

3.2.3 HTTP GET Request

Function

Allow HTML pages being played in the NTB to access resources that might otherwise be unavailable due tocross-domain security policies in the HTML player.

Enables you to build complex mashups for digital signage where content may need to be fetched from differentsources while ensuring the security of the signage system.

This API uses theXML Services proxy, if configured.


43

Syntax

Example XML:<?xml version="1.0" encoding="UTF-8" standalone="yes"?><http_request href="http://www.onelan.co.uk" method="get"

username="fakeuser"password="fakepassword"><header name="accept-language" value="en-GB" />

</http_request>

The header names are case-insensitive.

Youmay set the following HTTP headers to be forwarded to the remote server:

Header Name Description Default

Accept Acceptable content type. text/*

Accept-language Acceptable language for the response en-GB

Cookie An HTTP cookie sent by the server in aprevious call.

User-agent Application type requesting the URI. Mozilla/5.0 (X11; U; Linux i686, en-US; rv:1.8

Gecko/20051111

Firefox/1.5

Return Status

The return status will be the same as if the user had accessed the resource through a browser.

Applications may check for Content-type to determine the returned resource.

Compatibility

Introduced in 8.0.

3.2.4 HTTP POST Request

Function

Allow HTML pages played in the NTB to submit web forms and post data to URIs using the HTTP POSTmethod.

Enables the HTML player to play web pages that require HTML form-based login. To do so, build a custom HTMLpage to HTTP GET the new page, submit a login form, setup a session, and display the content.

This API uses the XMLServices proxy, if configured.

Syntax

POST the following XML to '/XML' with 'Content-type' set to 'text/xml':<?xml version="1.0" encoding="UTF-8" standalone="yes"?><http_request href="http://www.onelan.co.uk"


44

username="fakeuser"password="fakepassword"method="post"><header name='language' value='en-GB' /><content content_type="x-www-form-urlencoded">&query_id=2</content>

</http_request>

Return Status

HTTP status code and content as returned by the remote server on success, 500 otherwise.

Compatibility

Introduced in 8.0.

3.3 Sample CodeThe following is a sample of C# code that POSTs an Advance To command:using System;using System.Text;using System.Net;using System.IO;using System.Xml;using System.Security;

namespace TestNTBPost{class NTBPost{

static public void postAdvanceTo↵(string rendezvous_name, string hostname, string username, string password)

{try{

Console.WriteLine( string.Format↵("Info: Post advance to: {0} to NTB: {1}", rendezvous_name, hostname));

string advance_to_message = string.Format↵("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n↵<advance_to rendezvous_name=\"{0}\"/>", SecurityElement.Escape(rendezvous_name))

string url = string.Format("http://{0}/XML/", hostname);Uri uri = new Uri(url);

HttpWebRequest request = WebRequest.Create(uri) as HttpWebRequest;request.Proxy = null;request.KeepAlive = true;request.PreAuthenticate = true;request.ServicePoint.Expect100Continue = false;

CredentialCache cc = new CredentialCache();cc.Add(uri, "Basic", new NetworkCredential(username, password));cc.Add(uri, "Digest", new NetworkCredential(username, password));request.Credentials = cc;


45

request.Method = "POST";

// Create POST data and convert it to a byte array.byte[] byteArray = Encoding.UTF8.GetBytes(advance_to_message);request.ContentType = "text/xml;charset=utf-8";request.ContentLength = byteArray.Length;using (Stream dataStream = request.GetRequestStream())

{dataStream.Write(byteArray, 0, byteArray.Length);

}

// Get the response.using (HttpWebResponse response = request.GetResponse() as HttpWebResponse){if (response.StatusCode == HttpStatusCode.OK){Console.WriteLine("Info: Successfully posted AdvanceTo message");}else{Console.WriteLine(string.Format(

"Error: Failed to post message. HTTP response - {0}",response.StatusDescription ));

using (Stream dataStream = response.GetResponseStream()){

using (StreamReader reader = new StreamReader(dataStream)){string responseFromServer = reader.ReadToEnd();Console.WriteLine(string.Format("Error: Server responded: {0}",

responseFromServer));}

}}

}}catch (WebException ex){Console.WriteLine(string.Format("Error: WebException when posting message: {0}",

ex.Message));}}

}}

net-top-box technical reference - onelan digital signage€¦ · net-top-boxtechnicalreference 15...

Documents