HBBTV control. More...

#include <string.h>
#include "dbgfuncs.h"
#include "techtype.h"
#include "hbbtv.h"
#include "hbbtv_js.h"
#include "hbbtv_sif_os.h"
#include "hbbtv_sif_service.h"
#include "hbbtv_sif_decoding.h"
#include "debug.h"
#include "timer.h"
#include "queue.h"
#include "hbbtv_control.h"
#include "ait.h"
#include "oipf_obj_factory.h"
#include "parental_rating_scheme.h"
#include "oipf_app_mgr.h"
#include "av_control.h"
#include "video_broadcast.h"
#include "scheduled_recording.h"
#include "oipf_recording_scheduler.h"
#include "local_system.h"
#include "network_interface.h"
#include "oipf_drm_agent.h"
#include "hbbtv_string.h"
#include "dsmclient.h"
#include "app.h"

Macros
#define	AIT_TIMEOUT 3000

#define	HBBTV_SUPPORTED_OPTIONS (HBBTV_CAP_PVR \| HBBTV_CAP_DRM)

Functions
E_HBBTV_ERR	HBBTV_Initialise (U32BIT task_priority, E_HBBTV_STRING_FORMAT string_format, U8BIT options)
	Initialises the HBBTV module. More...

BOOLEAN	HBBTV_CheckOptions (U8BIT mask)
	Checks whether the features represented by the specified mask are supported by the HBBTV module. This depends on the way the module has been initialised (see HBBTV_Initialise) and on the features currently supported by this version of the HBBTV module. More...

void	HBBTV_Finalise (void)
	Finalises the HBBTV module.

void	HBBTV_Start (S_HBBTV_DVB_LOCATOR *p_dvb_locator)
	Allows the HbbTV engine to run on the specified channel and handle the applications lifecyle as specified by the HbbTV standard. More...

void	HBBTV_Stop (void)
	Stops the HbbTV engine and prevents any HbbTV application to be displayed.

BOOLEAN	HBBTV_IsRunning (void)

void	HBBTV_ResetAitTimer (void)

void	HBBTV_PreserveVideoAspectRatio (S_HBBTV_RECT *rect)

E_HBBTV_ERR	HBBTV_HbbTvSetUrl (const U8BIT *url)
	Launches a "Broadcast-INDEPENDENT" application. The url could be an XML-AIT file. More...

E_HBBTV_ERR	HBBTV_GetBroadcastAppList (S_HBBTV_BROADCAST_APP *apps, U32BIT total)
	Returns a list of HbbTv Broadcast Appications signalled in the current AIT. The list must be freed using HBBTV_ReleaseAppList. More...

void	HBBTV_ReleaseAppList (S_HBBTV_BROADCAST_APP *apps)
	Releases the list of applications allocated by HBBTV_GetBroadcastAppList. More...

E_HBBTV_ERR	HBBTV_LaunchApplication (U32BIT org_id, U16BIT app_id)
	Launches the specified application. More...

E_HBBTV_ERR	HBBTV_NotifyServiceListChange (void)
	Notifies the HbbTV ending that it must update Service list. This will cause the engine to subsequently call HBBTV_ObtainServiceList(). More...

E_HBBTV_ERR	HBBTV_NotifyParentalRatingChange (BOOLEAN blocked)
	Notifies the HbbTV engine that the parental rating of the currently playing service has changed. More...

E_HBBTV_ERR	HBBTV_NotifyChannelChangeStatus (U16BIT onet_id, U16BIT trans_id, U16BIT serv_id, E_HBBTV_CHANNEL_CHANGE_STATUS status)
	Notifies the HbbTV engine of a change in the status of the service identified by the specified DVB triplet. More...

E_HBBTV_ERR	HBBTV_NotifyProgrammeChanged (void)
	Notifies the HbbTV engine that the present/following events have changed on the current service. More...

E_HBBTV_ERR	HBBTV_NotifyRecordingEvent (U32BIT id, E_HBBTV_RECORDING_EVENT event)
	Notifies the HbbTV engine of a recording event. More...

E_HBBTV_ERR	HBBTV_NotifyKeyPress (E_HBBTV_KEY key)
	Notify the HbbTV engine of a user key press. If the key is not required by an active HbbTV application, then the function returns HBBTV_IGNORED_REQUEST. More...

void	HBBTV_SetKeyNotifyFunc (F_KEY_NOTIFY accept, F_KEY_NOTIFY consume)
	Internal function to set the 'accept' and 'consume' key function pointers. More...

void	HBBTV_GetCurrentChannel (S_HBBTV_DVB_LOCATOR *dvb_locator)
	Returns the current channel, passed the HBBTV engine on Start, as a DVB locator. More...

E_HBBTV_ERR	HBBTV_NotifyVideoAspectRatio (E_HBBTV_ASPECT_RATIO ratio)
	Notifies the HBBTV module of the aspect ratio of the video stream. This is used by the engine to correctly preserve the aspect ratio of resised videos as specified by the HbbTV specification. More...

E_HBBTV_ERR	HBBTV_SetSystemInfo (S_HBBTV_SYSTEM_INFO *info)
	Informs the HbbTV engine of some information regarding the system. The HbbTV engine makes a copy of the strings in the structure. More...

S_HBBTV_SYSTEM_INFO *	HBBTV_GetSystemInfo (void)
	Returns the pointer to the internal copy of the system information structure set by HBBTV_SetSystemInfo. More...

E_HBBTV_ERR	HBBTV_NotifyPvrStorageEvent (E_HBBTV_PVR_STORAGE_EVENT event)
	Notifies the HbbTV engine of a PVR storage event. More...

E_HBBTV_ERR	HBBTV_NotifyNetworkEvent (void *handle, E_HBBTV_NW_EVENT event)
	Notifies the HbbTV engine of a network event. More...

E_HBBTV_ERR	HBBTV_NotifyDRMSystemMessage (U8BIT *message, U32BIT length, U16BIT ca_system_id)
	Notifies an incoming message from the DRM system. The HbbTV engine copies the content of message before returning. More...

E_HBBTV_ERR	HBBTV_NotifyDRMMessageResult (U32BIT id, U8BIT *message, U32BIT length, U8BIT result_code)
	Notifies the result message from the DRM system.The HbbTV engine copies the content of message before returning. More...

E_HBBTV_ERR	HBBTV_NotifyDRMRightsError (E_HBBTV_DRM_ERROR_STATE error_state, U16BIT ca_system_id, U8BIT *rights_issuer_url, U32BIT rights_issuer_length)
	Notifies an incoming rights error from the DRM system. More...

E_HBBTV_ERR	HBBTV_NotifyLowMemory (void)
	Notifies the HbbTv engine that the device is running low on available memory for running applications. More...

E_HBBTV_ERR	HBBTV_SetFreesatCallbacks (S_HBBTV_FREESAT_CALLBACKS *callbacks)
	Registers Freesat callbacks with the HbbTV engine. More...

S_HBBTV_FREESAT_CALLBACKS *	HBBTV_GetFreesatCallbacks (void)
	Returns the pointer to the internal structure holding the Freesat callbacks. More...

BOOLEAN	HBBTV_GetEngineInitialised (void)
	Returns the initialisation status of the HbbTV engine.

Detailed Description

HBBTV control.

Date: 17 January 2013

Author: Adam Sturtridge

Function Documentation

BOOLEAN HBBTV_CheckOptions ( U8BIT mask )

Checks whether the features represented by the specified mask are supported by the HBBTV module. This depends on the way the module has been initialised (see HBBTV_Initialise) and on the features currently supported by this version of the HBBTV module.

Parameters

mask	bit mask representing the features to be checked

Returns: TRUE if all the features in mask are supported by the HBBTV module, FALSE otherwise

Note: This function is meant to be internal to the HBBTV module

E_HBBTV_ERR HBBTV_GetBroadcastAppList	(	S_HBBTV_BROADCAST_APP **	apps,
		U32BIT *	total
	)

Returns a list of HbbTv Broadcast Appications signalled in the current AIT. The list must be freed using HBBTV_ReleaseAppList.

Parameters

apps	Pointer to S_HBBTV_BROADCAST_APP containng the list of available applications
total	Number of applications in the returned list.

Returns: HBBTV_ERR_ALLOCATING_MEMORY if the list could not be allocated, HBBTV_OK otherwise

void HBBTV_GetCurrentChannel ( S_HBBTV_DVB_LOCATOR * dvb_locator )

Returns the current channel, passed the HBBTV engine on Start, as a DVB locator.

Parameters

dvb_locator pointer to the variable where the dvb locator will be stored

S_HBBTV_FREESAT_CALLBACKS* HBBTV_GetFreesatCallbacks ( void )

Returns the pointer to the internal structure holding the Freesat callbacks.

Returns: Pointer to the internal Freesat callback structure.

S_HBBTV_SYSTEM_INFO* HBBTV_GetSystemInfo ( void )

Returns the pointer to the internal copy of the system information structure set by HBBTV_SetSystemInfo.

Returns the pointer to the internal copy of the local system information structure set by HBBTV_SetSystemInfo.

E_HBBTV_ERR HBBTV_HbbTvSetUrl ( const U8BIT * url )

Launches a "Broadcast-INDEPENDENT" application. The url could be an XML-AIT file.

Parameters

url	URL where application is to be found

Returns: HBBTV_OK if the application could be launched, HBBTV_ERR_OTHER otherwise

E_HBBTV_ERR HBBTV_Initialise	(	U32BIT	task_priority,
		E_HBBTV_STRING_FORMAT	string_format,
		U8BIT	options
	)

Initialises the HBBTV module.

Parameters

task_priority
string_format	Format of the strings returned to the HbbTV engine. The engine will translate them if they're in DVB SI format or use them as they are otherwise.
options	Mask representing the optional modules required. It is a combination of HBBTV_CAP_DL, HBBTV_CAP_PVR and HBBTV_CAP_DRM

Returns: HBBTV_OK on success, otherwise error code

E_HBBTV_ERR HBBTV_LaunchApplication	(	U32BIT	org_id,
		U16BIT	app_id
	)

Launches the specified application.

Parameters

org_id	Organisation ID as found in the list returned by HBBTV_GetBroadcastAppList
app_id	Application ID as found in the list returned by HBBTV_GetBroadcastAppList

Returns: HBBTV_ERR_OBJECT_NOT_FOUND if the application could not be found, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyChannelChangeStatus	(	U16BIT	onet_id,
		U16BIT	trans_id,
		U16BIT	serv_id,
		E_HBBTV_CHANNEL_CHANGE_STATUS	status
	)

Notifies the HbbTV engine of a change in the status of the service identified by the specified DVB triplet.

Parameters

onet_id	Original Network ID
trans_id	Transport Stream ID
serv_id	Service ID
status	New status

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyDRMMessageResult	(	U32BIT	id,
		U8BIT *	message,
		U32BIT	length,
		U8BIT	result_code
	)

Notifies the result message from the DRM system.The HbbTV engine copies the content of message before returning.

Parameters

id	Message ID idenfying the message the result refers to.
message	Buffer containing the incoming message.
length	Number of bytes in the buffer.
result_code	Result code from the DRM.

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_IGNORED_REQUEST if the engine has not been initialised with the DRM capability, HBBTV_OK otherwise.

E_HBBTV_ERR HBBTV_NotifyDRMRightsError	(	E_HBBTV_DRM_ERROR_STATE	error_state,
		U16BIT	ca_system_id,
		U8BIT *	rights_issuer_url,
		U32BIT	rights_issuer_length
	)

Notifies an incoming rights error from the DRM system.

Parameters

error_state
ca_system_id
rights_issuer_url
right_issuer_length

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_IGNORED_REQUEST if the engine has not been initialised with the DRM capability, HBBTV_OK otherwise.

E_HBBTV_ERR HBBTV_NotifyDRMSystemMessage	(	U8BIT *	message,
		U32BIT	length,
		U16BIT	ca_system_id
	)

Notifies an incoming message from the DRM system. The HbbTV engine copies the content of message before returning.

Parameters

message	Buffer containing the incoming message.
length	Number of bytes in the buffer.
ca_system_id	CA system ID of the originating DRM system.

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_IGNORED_REQUEST if the engine has not been initialised with the DRM capability, HBBTV_OK otherwise.

E_HBBTV_ERR HBBTV_NotifyKeyPress ( E_HBBTV_KEY key )

Notify the HbbTV engine of a user key press. If the key is not required by an active HbbTV application, then the function returns HBBTV_IGNORED_REQUEST.

Notifies the HbbTV engine of a user key press. If the key is not required by an active HbbTV application, then the function returns HBBTV_IGNORED_REQUEST.

Parameters

key	Value representing the user pressed key

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_OK if the HbbTV engine used the key, HBBTV_IGNORED_REQUEST otherwise

E_HBBTV_ERR HBBTV_NotifyLowMemory ( void )

Notifies the HbbTv engine that the device is running low on available memory for running applications.

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_OK otherwise.

E_HBBTV_ERR HBBTV_NotifyNetworkEvent	(	void *	handle,
		E_HBBTV_NW_EVENT	event
	)

Notifies the HbbTV engine of a network event.

Parameters

handle	Network interface handle as returned in the S_HBBTV_NW_INTERFACE structure
event	Event to be notified

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyParentalRatingChange ( BOOLEAN blocked )

Notifies the HbbTV engine that the parental rating of the currently playing service has changed.

Parameters

blocked TRUE if the current service is blocked by the parental control system.

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyProgrammeChanged ( void )

Notifies the HbbTV engine that the present/following events have changed on the current service.

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyPvrStorageEvent ( E_HBBTV_PVR_STORAGE_EVENT event )

Notifies the HbbTV engine of a PVR storage event.

Parameters

event Event to be notified

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyRecordingEvent	(	U32BIT	id,
		E_HBBTV_RECORDING_EVENT	event
	)

Notifies the HbbTV engine of a recording event.

Parameters

id	Scheduled recording ID
event	Recording event

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyServiceListChange ( void )

Notifies the HbbTV ending that it must update Service list. This will cause the engine to subsequently call HBBTV_ObtainServiceList().

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

E_HBBTV_ERR HBBTV_NotifyVideoAspectRatio ( E_HBBTV_ASPECT_RATIO ratio )

Notifies the HBBTV module of the aspect ratio of the video stream. This is used by the engine to correctly preserve the aspect ratio of resised videos as specified by the HbbTV specification.

Parameters

ratio HBBTV_VIDEO_ASPECT_RATIO_16x9 or HBBTV_VIDEO_ASPECT_RATIO_4x3

Returns: HBBTV_ERR_COMP_NOT_STARTED if the engine has not been started, HBBTV_OK otherwise

void HBBTV_ReleaseAppList ( S_HBBTV_BROADCAST_APP * apps )

Releases the list of applications allocated by HBBTV_GetBroadcastAppList.

Parameters

apps	Pointer to S_HBBTV_BROADCAST_APPS to be released

E_HBBTV_ERR HBBTV_SetFreesatCallbacks ( S_HBBTV_FREESAT_CALLBACKS * callbacks )

Registers Freesat callbacks with the HbbTV engine.

Parameters

callbacks Pointer to the structure containing the function pointers. If it's NULL all the previously registered functions will be unregistered. If a pointer in the structure is NULL, that particular function is unregistered.

Returns

HBBTV_OK on success
HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised

void HBBTV_SetKeyNotifyFunc	(	F_KEY_NOTIFY	accept,
		F_KEY_NOTIFY	consume
	)

Internal function to set the 'accept' and 'consume' key function pointers.

Parameters

accept	function pointer of type F_KEY_NOTIFY, used by the engine to determine whether a key will be consumed by the active application
consume	function pointer of type F_KEY_NOTIFY, used by the engine to deliver a key to the active application

E_HBBTV_ERR HBBTV_SetSystemInfo ( S_HBBTV_SYSTEM_INFO * info )

Informs the HbbTV engine of some information regarding the system. The HbbTV engine makes a copy of the strings in the structure.

Parameters

info	Structure containing information regarding the system.

Returns: HBBTV_ERR_COMP_NOT_OPEN if the engine has not been initialised, HBBTV_OK otherwise.

void HBBTV_Start ( S_HBBTV_DVB_LOCATOR * p_dvb_locator )

Allows the HbbTV engine to run on the specified channel and handle the applications lifecyle as specified by the HbbTV standard.

Parameters

p_dvb_locator pointer to the DVB locator representing the current channel

Macros

Functions

Detailed Description

Function Documentation