mh5control.c File Reference

(STB) can call directly. They build the interface to the MHEG5 engine. This file defines the api to the MHEG engine and the functions the engine needs from the system to run properly. All engine specific functions start with |MHEG5|, all system specific functions start with |OSD|. More...

#include "mheg5_events.h"
#include "dvb_service.h"
#include "mh5application.h"
#include "mh5scene.h"
#include "mh5queue.h"
#include "glue_memory.h"
#include "glue_queue.h"
#include "glue_timers.h"
#include "glue_main.h"
#include "glue_debug.h"
#include "mh5display.h"
#include "mh5fileorm.h"
#include "mh5misc.h"
#include "mh5streamevent.h"
#include "mh5gate.h"
#include "mg_osd.h"
#include "mg_api.h"
#include "stb_vtc.h"
#include "dvb_video.h"
#include "dvb_audio.h"
#include "mh5storage.h"
#include "glue_dsmcc.h"
#include "dsm_control.h"
#include "mh5control.h"
#include "mh5keypress.h"
#include "mheg5_ci.h"

Macros
#define	MAX_HANDLERS   2
#define	UND_LANGUAGE_CODE   (0x00756E64) /* 'und' */
#define	ENG_STAT_STRING()
#define	TINFO_QUIET_BIT   0x01
#define	TINFO_NON_DESTRUCT_BIT   0x02
#define	TINFO_EXPLICIT_CRSL_BIT   0x04
#define	TINFO_MAP_CRSL_INIT_BIT   0x08
#define	TINFO_NATIVE_APP_BIT   0x10
#define	LC_STATE_NONE   0x00
#define	LC_STATE_QUIET   TINFO_QUIET_BIT
#define	LC_STATE_NDT_ENABLE   TINFO_NON_DESTRUCT_BIT
#define	LC_STATE_NATIVE_APP   TINFO_NATIVE_APP_BIT
#define	LC_STATE_MHG_TUNING   0x80

Enumerations
enum	E_ENGINE_STATUS {   ENG_STOPPED, ENG_DSM_STARTING, ENG_DSM_STARTED, ENG_CI_STARTING,   ENG_CI_STARTED }

Functions
int	ASN1_MemInit (void)
void	ASN1_MemExit (void)
E_MhegErr	MHEG5Initialise (S_MhegConfig *cfg_params)
	initialise MHEG5 component More...
void	MHEG5_Terminate (void)
	Terminate MHEG5 component. More...
void	MHEG5RefreshDisplay (void)
E_MhegErr	MHEG5ResetResolution (U16BIT screenWidth, U16BIT screenHeight)
BOOLEAN	MHEG5_DvbRegisterEventHandler (F_NotifyMhegEvent handler)
void	MHEG5_DvbUnregisterEventHandler (F_NotifyMhegEvent handler)
void	MHEG5engineStart (U8BIT *app_name, BOOLEAN isCi)
	Start the engine with the initial application. More...
void	MHEG5NotifyEngineStarted (void)
void	MHEG5ProcessDsmccBooted (void *carousel)
void	MHEG5AutoPathComplete (E_FsStatus result)
void	MHEG5NotifyEngineStartFailed (void)
BOOLEAN	MHEG5ProcessAutoBoot (void)
void	MHEG5NotifyEngineQuit (void)
void	MHEG5engineTerminate (void)
	Force the engine to terminate. More...
MHEG5Bool	MHEG5TuneIndex (MHEG5Int serviceIndex)
	Ref: [1] - 3.10.6.2 Tune to the specified service. If the tuner fails to tune to the service it should attempt to return to the previous tuned service. If tuning to previously tuned service fails, the receiver shall allow the user to choose another service. More...
void	MHEG5TuneIndexInfo (MHEG5Int tuneInfo)
	Sets the way the application expects the receiver is to perform all subsequence application initiated tuning. Normal (0) means subsequent tuning will be performed as if the user had tuned via the remote control. Silently (1) means subsequent tuning will be performed without showing any OSD (channel info banner) and the user initiating a channel change will use the source channel as the reference point This function is used by the SI_TuneIndexInfo resident program. See UK1.06 profile section 3.10.6.4. More...
E_ChannelStartMode	MHEG5TuningInfoMode (S32BIT serviceIndex)
U32BIT	MHEG5tuneProcess (S_DvbLocator *pDvbLoc, S32BIT serviceIndex)
BOOLEAN	MHEG5isProcessingNDT (BOOLEAN *native_app_ok)
U8BIT	MHEG5HandleEngineStopAction (U8BIT action)
BOOLEAN	MHEG5engineDsmTerminate (void)
	Force the engine to terminate any DSM-CC based MHEG application. More...
BOOLEAN	MHEG5engineIsCiAppRunning (void)
void	MHEG5StartReboot (void *param)
void	MHEG5Pause (void)
void	MHEG5Resume (void)
void	MHEG5NotifyCarouselUnload (void *carousel)
E_MhegErr	MHEG5_StartCIApplication (U32BIT module, U8BIT *application)
	Instruct the MHEG5 component to start a specified CI application. This process may be stopped by a call to DVB_MhegStopCIApplications. This function will asynchronously return either MHEG5_CI_APPLICATION_START_FAILED, MHEG5_CI_APPLICATION_STARTED or MHEG5_CI_APPLICATION_STOPPED through the component progress function DVB_MhegNotifyComponentProgress. Asynchronous notifications that will occur during the start of a CI application process are: More...
E_MhegErr	MHEG5_StopCIApplication (U32BIT module)
	Stop any currently running CI MHEG5 applications. This is a non-blocking function, and may return before completion. This function will asynchronously return MHEG5_CI_APPLICATION_STOPPED, through the component progress function DVB_MhegNotifyComponentProgress, when the current CI application(s) have been stopped. If there are no CI applications running then the notification, MHEG5_CI_APPLICATION_STOPPED, will still be sent. If any currently running CI application is stopped then the default DSM-CC auto-boot application will be launched. See section 6.10 of reference [1] for details of interaction between the MHEG-5 component and the CI module. More...
E_MhegErr	MHEG5_CiFileAcknowledge (U32BIT module, BOOLEAN fileOK, U8BIT *pFileData, U32BIT fileSize)
	The MMI FileAcknowledge message, which is a reply from the CI module to an MMI FileRequest sent using STB_CIFileRequest. The memory for storing the fileData is managed by the controlling application. When the MHEG5 component has finished using the fileData it will invoke the MHEG5CiAckData function. More...
void	MHEG5CiAckData (U8BIT *pData)
	Acknowledge receipt of the data or message from the CI, so that the CI component can free or reuse the memory. This function is invoked after data has been returned from the CI component as a result of a call to either DVB_MhegCiGetFile() or DVB_MhegCiSendMessage() This MUST be a non-blocking function. See functions DVB_MhegCiGetFile() and DVB_MhegCiSendMessage(). More...

Detailed Description

(STB) can call directly. They build the interface to the MHEG5 engine. This file defines the api to the MHEG engine and the functions the engine needs from the system to run properly. All engine specific functions start with |MHEG5|, all system specific functions start with |OSD|.

Date

01/02/2002

Author

R.Freeman

Macro Definition Documentation

#define ENG_STAT_STRING

(

)

Value:

(mheg_engine_status == ENG_STOPPED) ? "STOPPED" : \
   (mheg_engine_status == ENG_DSM_STARTING) ? "STARTING DSM" : \
   (mheg_engine_status == ENG_DSM_STARTED) ? "STARTED DSM" : \
   (mheg_engine_status == ENG_CI_STARTING) ? "STARTING CI" : "STARTED CI"

#define LC_STATE_MHG_TUNING   0x80

#define LC_STATE_NATIVE_APP   TINFO_NATIVE_APP_BIT

#define LC_STATE_NDT_ENABLE   TINFO_NON_DESTRUCT_BIT

#define LC_STATE_NONE   0x00

#define LC_STATE_QUIET   TINFO_QUIET_BIT

#define MAX_HANDLERS   2

#define TINFO_EXPLICIT_CRSL_BIT   0x04

#define TINFO_MAP_CRSL_INIT_BIT   0x08

#define TINFO_NATIVE_APP_BIT   0x10

#define TINFO_NON_DESTRUCT_BIT   0x02

#define TINFO_QUIET_BIT   0x01

#define UND_LANGUAGE_CODE   (0x00756E64) /* 'und' */

Enumeration Type Documentation

enum E_ENGINE_STATUS

Enumerator
ENG_STOPPED
ENG_DSM_STARTING
ENG_DSM_STARTED
ENG_CI_STARTING
ENG_CI_STARTED

Function Documentation

void ASN1_MemExit

(

void

)

int ASN1_MemInit

(

void

)

E_MhegErr MHEG5_CiFileAcknowledge	(	U32BIT	module,
		BOOLEAN	fileOK,
		U8BIT *	pFileData,
		U32BIT	fileSize
	)

The MMI FileAcknowledge message, which is a reply from the CI module to an MMI FileRequest sent using STB_CIFileRequest. The memory for storing the fileData is managed by the controlling application. When the MHEG5 component has finished using the fileData it will invoke the MHEG5CiAckData function.

The MMI FileAcknowledge message, which is a reply from the CI module to an MMI FileRequest sent using STB_CIFileRequest. The memory for storing the fileData is managed by the controlling application. When the MHEG5 component has finished using the fileData it will invoke the DVB_MhegCiAckData function.

Parameters

fileOK	FileOK flag from the FileAcknowledge message
pFileData	Pointer to the response data, following the FileOK flag
fileSize	Size of response data

Returns

MHERR_OK - Success MHERR_COMP_NOT_STARTED - Component not started. MHERR_BAD_PARAMETER - Invalid parameter.

BOOLEAN MHEG5_DvbRegisterEventHandler

(

F_NotifyMhegEvent

handler

)

void MHEG5_DvbUnregisterEventHandler

(

F_NotifyMhegEvent

handler

)

E_MhegErr MHEG5_StartCIApplication	(	U32BIT	module,
		U8BIT *	application
	)

Instruct the MHEG5 component to start a specified CI application. This process may be stopped by a call to DVB_MhegStopCIApplications. This function will asynchronously return either MHEG5_CI_APPLICATION_START_FAILED, MHEG5_CI_APPLICATION_STARTED or MHEG5_CI_APPLICATION_STOPPED through the component progress function DVB_MhegNotifyComponentProgress. Asynchronous notifications that will occur during the start of a CI application process are:

Instruct the MHEG5 component to start a specified CI application. This process may be stopped by a call to MHEG5_StopCIApplications. This function will asynchronously return either MHEG5_CI_APPLICATION_START_FAILED, MHEG5_CI_APPLICATION_STARTED or MHEG5_CI_APPLICATION_STOPPED through event call back function F_NotifyMhegEvent. Asynchronous notifications that will occur during the start of a CI application process are:

1. MHEG5_CI_APPLICATION_START_FAILED - Failed to launch the CI application because it was either not present, a CI session was not established or there was an internal error.
2. MHEG5_CI_APPLICATION_STARTED - CI application started successfully.
3. MHEG5_CI_APPLICATION_STOPPED - Returned after call to either DVB_MhegStopCIApplications() or DVB_MhegStop() whilst trying to start the CI application. This notification will also occur when the CI application has completed with a quit application action. This is a non-blocking function, which may return before completion.

   Parameters

   application

   Application name, relative to the root of the CI file system. This has a maximum length of 64 characters.

   Returns

   MHERR_OK - Success MHERR_COMP_NOT_STARTED - Component not started. MHERR_BAD_PARAMETER - Invalid parameter. MHERR_INTERNAL - Internal MHEG5 component error.

E_MhegErr MHEG5_StopCIApplication

(

U32BIT

module

)

Stop any currently running CI MHEG5 applications. This is a non-blocking function, and may return before completion. This function will asynchronously return MHEG5_CI_APPLICATION_STOPPED, through the component progress function DVB_MhegNotifyComponentProgress, when the current CI application(s) have been stopped. If there are no CI applications running then the notification, MHEG5_CI_APPLICATION_STOPPED, will still be sent. If any currently running CI application is stopped then the default DSM-CC auto-boot application will be launched. See section 6.10 of reference [1] for details of interaction between the MHEG-5 component and the CI module.

Stop any currently running CI MHEG5 applications. This is a non-blocking function, and may return before completion. This function will asynchronously return MHEG5_CI_APPLICATION_STOPPED, through through event call back function F_NotifyMhegEvent, when the current CI application(s) have been stopped. If there are no CI applications running then the notification, MHEG5_CI_APPLICATION_STOPPED, will still be sent. If any currently running CI application is stopped then the default DSM-CC auto-boot application will be launched. See section 6.10 of reference [1] for details of interaction between the MHEG-5 component and the CI module.

Returns

MHERR_OK - Success MHERR_COMP_NOT_STARTED - Component not started. MHERR_INTERNAL - Internal MHEG5 component error.

void MHEG5_Terminate

(

void

)

Terminate MHEG5 component.

Returns

none

void MHEG5AutoPathComplete

(

E_FsStatus

result

)

void MHEG5CiAckData

(

U8BIT *

pData

)

Acknowledge receipt of the data or message from the CI, so that the CI component can free or reuse the memory. This function is invoked after data has been returned from the CI component as a result of a call to either DVB_MhegCiGetFile() or DVB_MhegCiSendMessage() This MUST be a non-blocking function. See functions DVB_MhegCiGetFile() and DVB_MhegCiSendMessage().

Parameters

pData

Reference to the memory location of the data or message.

Returns

The following return values are allowed from this function (see note [a]): MHERR_OK - Success. MHERR_BAD_PARAMETER - Invalid parameter. MHERR_OTHER - Controlling application specific error. The return value from this function is for debug purposes only and will be ignored in retail mode.

BOOLEAN MHEG5engineDsmTerminate

(

void

)

Force the engine to terminate any DSM-CC based MHEG application.

Returns

TRUE if app existed and was terminated.

BOOLEAN MHEG5engineIsCiAppRunning

(

void

)

Returns

TRUE if CI app exists

void MHEG5engineStart	(	U8BIT *	app_name,
		BOOLEAN	isCi
	)

Start the engine with the initial application.

Parameters

application

Start application name and path.

Returns

void

void MHEG5engineTerminate

(

void

)

Force the engine to terminate.

Returns

None.

U8BIT MHEG5HandleEngineStopAction

(

U8BIT

action

)

E_MhegErr MHEG5Initialise

(

S_MhegConfig *

cfg_params

)

initialise MHEG5 component

Returns

MHERR_OK - success MHERR_INTERNAL - failure

BOOLEAN MHEG5isProcessingNDT

(

BOOLEAN *

native_app_ok

)

void MHEG5NotifyCarouselUnload

(

void *

carousel

)

void MHEG5NotifyEngineQuit

(

void

)

void MHEG5NotifyEngineStarted

(

void

)

void MHEG5NotifyEngineStartFailed

(

void

)

void MHEG5Pause

(

void

)

BOOLEAN MHEG5ProcessAutoBoot

(

void

)

void MHEG5ProcessDsmccBooted

(

void *

carousel

)

void MHEG5RefreshDisplay

(

void

)

E_MhegErr MHEG5ResetResolution	(	U16BIT	screenWidth,
		U16BIT	screenHeight
	)

void MHEG5Resume

(

void

)

void MHEG5StartReboot

(

void *

param

)

MHEG5Bool MHEG5TuneIndex

(

MHEG5Int

serviceIndex

)

Ref: [1] - 3.10.6.2 Tune to the specified service. If the tuner fails to tune to the service it should attempt to return to the previous tuned service. If tuning to previously tuned service fails, the receiver shall allow the user to choose another service.

Parameters

serviceIndex

The service to which the tuner is to attempt to tune.

Returns

Boolean MHEG5TRUE - service available. MHEG5FALSE - service not available.

void MHEG5TuneIndexInfo

(

MHEG5Int

tuneInfo

)

Sets the way the application expects the receiver is to perform all subsequence application initiated tuning. Normal (0) means subsequent tuning will be performed as if the user had tuned via the remote control. Silently (1) means subsequent tuning will be performed without showing any OSD (channel info banner) and the user initiating a channel change will use the source channel as the reference point This function is used by the SI_TuneIndexInfo resident program. See UK1.06 profile section 3.10.6.4.

Parameters

tuneInfo

tuning information

Returns

TRUE if successful, else FALSE.

U32BIT MHEG5tuneProcess	(	S_DvbLocator *	pDvbLoc,
		S32BIT	serviceIndex
	)

E_ChannelStartMode MHEG5TuningInfoMode

(

S32BIT

serviceIndex

)