Main Synchronous System (broadcast) API functions References: [1] - BS ISO/IEC 13818-6:1998 [2] - ETSI/DVB TR 101 202 v1.1.1 (1999-02) More...

#include "cldsmcc.h"
#include "clDsmSystem.h"
#include "clDsmUtils.h"
#include "linkList.h"
#include "sectionFilter.h"
#include "dsmObject.h"
#include "module.h"
#include "dataCarousel.h"
#include "objectCarousel.h"
#include "updateCarousel.h"
#include "moduleDecompress.h"
#include "loadMgr.h"
#include "siQuery.h"
#include "cacheMgr.h"
#include "defMemUtilsContig.h"
#include "pmtUpdate.h"
#include "streamEvent.h"
#include <stdio.h>

Classes
struct	_accelerate_carousel_loading_struct

Macros
#define	DSI_MSG_ID 0x1006

#define	DII_MSG_ID 0x1002

#define	DDB_MSG_ID 0x1003

Typedefs
typedef struct _accelerate_carousel_loading_struct	accelerateCarouselLoading_t

Functions
void	CDSM_SetPrintFuncs (F_Printf errorFunc, F_Printf warnFunc, F_Printf debugFunc, F_Printf infoFunc)
	Sets debug print functions for four different levels of detail. Any of these parameters can be set to NULL to turn off output All can be same function and default is NULL for all. More...

void	CDSM_SetPrintState (U32BIT state)
	Sets debug print state to select areas of debug. More...

void	CDSM_SetDebugState (H_DsmCoreInst dsm, U32BIT dbgMask)
	Set Debug mask for core DSM. More...

E_DscError	CDSM_SysCreate (P_DsmSetup pSetup, H_DsmCoreInst pInstance, void *pMemContext)

E_DscError	CDSM_SysDestroy (H_DsmCoreInst instance, H_SiqInstance pSiqInst, H_SfmInstance pSfmInst)
	Destroy DSM-CC Core Layer instance. De-allocates all 'static' memory used by the instance (via freeFunc). Only call at shutdown of DSM-CC instance. NB. clDsmDestroy will not 'fail' to execute even if it detects error conditions - ie. it will always de-allocate the instance memory. API calls MUST NOT be made with the old (stale) instance value after clDsmDestroy has been called since they will cause illegal memory accesses. To avoid problems, the instance should always be reset (via clDsmReset) before calling clDsmDestroy. This will detect if there are any active client or system transactions - eg. loaded objects or pending SI Query events. This would indicate it may be dangerous to call clDsmDestroy until they are completed. If clDsmDestroy detects that the instance is not in a reset state - ie. immediately after clDsmSysCreate or after clDsmReset has been successfully called (with force switches if necessary), it will return an error. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: freeFunc. More...

H_DsmControl	CDSM_SysGetControl (H_DsmCoreInst instance)
	Get control handle from DSM instance . More...

E_DscError	CDSM_UnloadAllCarousels (P_DsmCoreInst idp, U8BIT mode)

E_DscError	CDSM_SysReset (H_DsmCoreInst instance, E_DsmRstMode mode)
	Reset DSM-CC Core Layer instance. Resets conditions to the same state as after CDSM_SysCreate(ie. keeps setup parameters). In normal operation the client MUST first unsubscribe all events, close and and unload all objects and unload all carousels before calling this function. This will have also stopped/deleted all associated system resources (ie. SI queries, timers, SI change monitors, section filters). If any client transactions or system transactions are still active when clDsmReset is called the reset will not be executed and an error returned. NB. The calling environment (system side) must acknowledge stop commands for SI Queries and timers (via processSIQueryEvent, processTimerEvent) and that these may occur asynchronously (ie. after a delay). This means that there may still be some active system transactions for some time after all objects and carousels are unloaded. FORCING RESET IN ERROR CONDITIONS: If all client and system transactions are apparently completed but still returns an error (eg. because handles are unknown/lost or system resource stop requests are not acknowledged) then clDsmReset can be called with appropriate force switches to clear the error condition. Any client transaction errors must first be cleared before system transaction errors can be cleared and both force switches cannot be set at the same time. NB. Only use force switches in known error conditions. It is potentially fatal (may cause illegal memory access) to call the functions: streamEventUnsubscribe, unloadObject, unloadCarousel, processSIQueryEvent, processTimerEvent with old/stale handles after clDsmReset has been forced. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: deleteSectionFilter stopTimer stopSIQuery unsubscribeSIChange. More...

void	CDSM_SysSetMemoryMax (H_DsmCoreInst instance, U32BIT maxMemory)
	Set maximum memory usage. More...

E_DscError	CDSM_SysSetCurrService (H_DsmCoreInst instance, U16BIT original_network_id, U16BIT transport_stream_id, U16BIT service_id)
	Set/notify the current service (initially and when changing it). This MUST be called initially (ie. after clDsmCreate or clDsmReset), before the boot carousel (or any carousels) can be loaded. To change the current service (ie. once one is already set) then the client MUST first unsubscribe all stream events and successfully unload all objects and carousels (from the current service). If any errors occur then clDsmReset may need to be called (with force switches - see Additional information below) before a new (or even the same) service can be set. ** NB. THIS FUNCTIONALITY IS NOT CURRENTLY IMPLEMENTED When this function is re-called. If the service details match those currently set then it will take no action. If they are different then the new service details are stored (unless objects and/or carousels are still loaded, in which case they are ignored and an error generated). NB. THIS FUNCTIONALITY IS NOT CURRENTLY IMPLEMENTED ** To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none. More...

U16BIT	CDSM_SysCurrServiceId (H_DsmCoreInst instance)

E_DscError	CDSM_SysProcessTimerEvent (H_DsmCoreInst instance, void clDsmTmrUserData, E_TimerStatus status, void timerHandle)

E_DscError	CDSM_SysProcessSIQueryEvent (H_DsmCoreInst idp, H_SIQueryRef clDsmSIQueryRef, void *clDsmSIUserData, P_SIQueryResult pResult)
	Notifies the result of the specified SI query (ie. a callback to startSIQueryFunc that returned SIQUERY_PENDING) or notifies that the query was stopped (aborted) before completion. Meaning of status values in this context: SIQUERY_SUCCESS - Query has returned successful result. SIQUERY_FAILURE - Query has failed to determine requested information (for any reason). SIQUERY_PENDING - * INVALID VALUE FOR THIS CALL * SIQUERY_ABORTED - Query has been stopped before completion. If the queryHandle supplied here is non-NULL it will supercede any value returned from the startSIQueryFunc callback (when input to the stopSIQueryFunc callback). NB. Although this function should be called synchronously with the other (synchronous) API functions, it can also be called from within the stopSIQueryFunc (required API) callback if required. Discard siQuery when there is no current service or siQueries generation count is different to the DSMCC instances generation count. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: addSectionFilter stopSIQuery notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopTimer. More...

E_DscError	CDSM_SysProcessSIChangeEvent (H_DsmCoreInst instance, E_SIChangeEvent event, U16BIT service_id, U32BIT carousel_id)
	Notify that the SI for the indicated service has changed Changes should be notified in the following situations: More...

E_DscError	CDSM_SectionPriority (H_DsmCoreInst instance, H_DscSFRef dsmFilterRef, E_SFPriority *priority)

E_DscError	CDSM_SysProcessPrivateSection (H_DsmCoreInst idp, U8BIT *pSection, H_DscSFRef dsmFilterRef)

Variables
F_Printf	DBG_ErrorPrintfFunc = NULL

F_Printf	DBG_WarnPrintfFunc = NULL

F_Printf	DBG_DebugPrintfFunc = NULL

F_Printf	DBG_InfoPrintfFunc = NULL

U32BIT	dsmDbgState = 0

accelerateCarouselLoading_t	accCarouselLoadingInfos

Detailed Description

Main Synchronous System (broadcast) API functions References: [1] - BS ISO/IEC 13818-6:1998 [2] - ETSI/DVB TR 101 202 v1.1.1 (1999-02)

Date: 28/9/2001

Author: R Taylor

Function Documentation

void CDSM_SetDebugState	(	H_DsmCoreInst	dsm,
		U32BIT	dbgMask
	)

Set Debug mask for core DSM.

Parameters

dsm	DSMCC core instance handle.
dbgMask	Mask to filter debug messages

Returns

void CDSM_SetPrintFuncs	(	F_Printf	errorFunc,
		F_Printf	warnFunc,
		F_Printf	debugFunc,
		F_Printf	infoFunc
	)

Sets debug print functions for four different levels of detail. Any of these parameters can be set to NULL to turn off output All can be same function and default is NULL for all.

Parameters

F_Printf	errorFunc Pointer to error print function
F_Printf	warmFunc Pointer to warn print function
F_Printf	debugFunc Pointer to debug print function
F_Printf	infoFunc Pointer to info print function

Returns: void

void CDSM_SetPrintState ( U32BIT state )

Sets debug print state to select areas of debug.

Parameters

U32BIT state See defines above

Returns: void

E_DscError CDSM_SysDestroy	(	H_DsmCoreInst	instance,
		H_SiqInstance *	pSiqInst,
		H_SfmInstance *	pSfmInst
	)

Destroy DSM-CC Core Layer instance. De-allocates all 'static' memory used by the instance (via freeFunc). Only call at shutdown of DSM-CC instance. NB. clDsmDestroy will not 'fail' to execute even if it detects error conditions - ie. it will always de-allocate the instance memory. API calls MUST NOT be made with the old (stale) instance value after clDsmDestroy has been called since they will cause illegal memory accesses. To avoid problems, the instance should always be reset (via clDsmReset) before calling clDsmDestroy. This will detect if there are any active client or system transactions - eg. loaded objects or pending SI Query events. This would indicate it may be dangerous to call clDsmDestroy until they are completed. If clDsmDestroy detects that the instance is not in a reset state - ie. immediately after clDsmSysCreate or after clDsmReset has been successfully called (with force switches if necessary), it will return an error. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: freeFunc.

Parameters

instance DSMCC instance handle

Returns: CLDSM_OK (0) Destroy was executed with no problems. CLDSM_ERR_INSTANCE_NOT_RESET Destroy was executed but instance was not in a reset state so there may still be client and system transactions outstanding. CLDSM_ERR_MEMSTOP_PROBLEM Destroy was executed but memory manager detected a problem while stopping. NB. Should be regarded as an internal error unless clDsmMemMgrAPI is mapped to a system (external) memory manager (DSM_SYSTEM_MEMMGR defined).

H_DsmControl CDSM_SysGetControl ( H_DsmCoreInst instance )

Get control handle from DSM instance .

Parameters

instance

Returns: NULL if an invalid instance handle, otherwise returns control handle

E_DscError CDSM_SysProcessSIChangeEvent	(	H_DsmCoreInst	instance,
		E_SIChangeEvent	evnt,
		U16BIT	service_id,
		U32BIT	carousel_id
	)

Notify that the SI for the indicated service has changed Changes should be notified in the following situations:

The service cannot be located
The service is deleted from the multiplex (eg. PAT updated)

The service info is updated (ie. PMT updated). CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: errorFunc startSIQueryFunc delSectionFilterFunc addSectionFilterFunc CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: addSectionFilter stopSIQuery notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopTimer

Parameters

instance	DSMCC instance handle
clDsmSIQueryRef	Refererence for this query (value supplied at start time).
clDsmSIUserData	User data for this query (value supplied at start time).
status	Status of query results.
pResult	Pointer to results of query (if successful).

Returns: CLDSM_OK (0) The process SI query event was executed with no problems. CLDSM_ERR_INVALID_SIQUERY_REF Supplied clDsmSIQueryRef does not reference a valid query. CLDSM_ERR_INVALID_SIQUERY_STATUS Supplied status value is invalid here. CLDSM_ERR_SYSTEM_ADD_SECTION_FILTER, Problem with add section filter callback.

E_DscError CDSM_SysProcessSIQueryEvent	(	H_DsmCoreInst	idp,
		H_SIQueryRef	clDsmSIQueryRef,
		void *	clDsmSIUserData,
		P_SIQueryResult	pResult
	)

Notifies the result of the specified SI query (ie. a callback to startSIQueryFunc that returned SIQUERY_PENDING) or notifies that the query was stopped (aborted) before completion. Meaning of status values in this context: SIQUERY_SUCCESS - Query has returned successful result. SIQUERY_FAILURE - Query has failed to determine requested information (for any reason). SIQUERY_PENDING - *** INVALID VALUE FOR THIS CALL *** SIQUERY_ABORTED - Query has been stopped before completion. If the queryHandle supplied here is non-NULL it will supercede any value returned from the startSIQueryFunc callback (when input to the stopSIQueryFunc callback). NB. Although this function should be called synchronously with the other (synchronous) API functions, it can also be called from within the stopSIQueryFunc (required API) callback if required. Discard siQuery when there is no current service or siQueries generation count is different to the DSMCC instances generation count. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: addSectionFilter stopSIQuery notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopTimer.

Notifies the result of the specified SI query (ie. a callback to startSIQueryFunc that returned SIQUERY_PENDING) or notifies that the query was stopped (aborted) before completion. Meaning of status values in this context: SIQUERY_SUCCESS - Query has returned successful result. SIQUERY_FAILURE - Query has failed to determine requested information (for any reason). SIQUERY_PENDING - *** INVALID VALUE FOR THIS CALL *** SIQUERY_ABORTED - Query has been stopped before completion. If the queryHandle supplied here is non-Null it will supercede any value returned from the startSIQueryFunc callback (when input to the stopSIQueryFunc callback). NB. Although this function should be called synchronously with the other (synchronous) API functions, it can also be called from within the stopSIQueryFunc (required API) callback if required. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: addSectionFilter stopSIQuery notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopTimer.

Parameters

instance	DSMCC instance handle
clDsmSIQueryRef	Refererence for this query (value supplied at start time).
clDsmSIUserData	User data for this query (value supplied at start time).
status	Status of query results.
pResult	Pointer to results of query (if successful).
queryHandle	Calling env. handle to query (optional - NULL if not used).

Returns: CLDSM_OK (0) The process SI query event was executed with no problems. CLDSM_ERR_INVALID_SIQUERY_REF Supplied clDsmSIQueryRef does not reference a valid query. CLDSM_ERR_INVALID_SIQUERY_STATUS Supplied status value is invalid here. CLDSM_ERR_SYSTEM_ADD_SECTION_FILTER, Problem with add section filter callback.

E_DscError CDSM_SysProcessTimerEvent	(	H_DsmCoreInst	instance,
		void *	clDsmTmrUserData,
		E_TimerStatus	status,
		void *	timerHandle
	)

Notifies that the specified timer has either timed-out (triggered) or been stopped (aborted) before triggering. Input parameter clDsmTmrUserData must be set to the value supplied when the timer was started. If the timerHandle supplied here is non-Null it will supercede any value returned from the startTimerFunc callback (when input to stopTimerFunc callback). NB. Although this function should be called synchronously with the other (synchronous) API functions, it can also be called from within the stopTimerFunc (required API) callback if required. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: case (status) TIMER_TRIGGERED: notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopSIQuery stopTimer TIMER_ABORTED none endcase RETURNS: CLDSM_OK (0)

E_DscError CDSM_SysReset	(	H_DsmCoreInst	instance,
		E_DsmRstMode	mode
	)

Reset DSM-CC Core Layer instance. Resets conditions to the same state as after CDSM_SysCreate(ie. keeps setup parameters). In normal operation the client MUST first unsubscribe all events, close and and unload all objects and unload all carousels before calling this function. This will have also stopped/deleted all associated system resources (ie. SI queries, timers, SI change monitors, section filters). If any client transactions or system transactions are still active when clDsmReset is called the reset will not be executed and an error returned. NB. The calling environment (system side) must acknowledge stop commands for SI Queries and timers (via processSIQueryEvent, processTimerEvent) and that these may occur asynchronously (ie. after a delay). This means that there may still be some active system transactions for some time after all objects and carousels are unloaded. FORCING RESET IN ERROR CONDITIONS: If all client and system transactions are apparently completed but still returns an error (eg. because handles are unknown/lost or system resource stop requests are not acknowledged) then clDsmReset can be called with appropriate force switches to clear the error condition. Any client transaction errors must first be cleared before system transaction errors can be cleared and both force switches cannot be set at the same time. NB. Only use force switches in known error conditions. It is potentially fatal (may cause illegal memory access) to call the functions: streamEventUnsubscribe, unloadObject, unloadCarousel, processSIQueryEvent, processTimerEvent with old/stale handles after clDsmReset has been forced. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: deleteSectionFilter stopTimer stopSIQuery unsubscribeSIChange.

Parameters

instance	DSMCC instance handle
mode	RST_MODE_FORCE or RST_MODE_PENDING

Returns: CLDSM_OK (0) The reset was executed with no problems.

E_DscError CDSM_SysSetCurrService	(	H_DsmCoreInst	instance,
		U16BIT	original_network_id,
		U16BIT	transport_stream_id,
		U16BIT	service_id
	)

Set/notify the current service (initially and when changing it). This MUST be called initially (ie. after clDsmCreate or clDsmReset), before the boot carousel (or any carousels) can be loaded. To change the current service (ie. once one is already set) then the client MUST first unsubscribe all stream events and successfully unload all objects and carousels (from the current service). If any errors occur then clDsmReset may need to be called (with force switches - see Additional information below) before a new (or even the same) service can be set. **** NB. THIS FUNCTIONALITY IS NOT CURRENTLY IMPLEMENTED **** When this function is re-called. If the service details match those currently set then it will take no action. If they are different then the new service details are stored (unless objects and/or carousels are still loaded, in which case they are ignored and an error generated). **** NB. THIS FUNCTIONALITY IS NOT CURRENTLY IMPLEMENTED **** To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Set/notify the current service (initially and when changing it). This MUST be called initially (ie. after clDsmCreate or clDsmReset), before the boot carousel (or any carousels) can be loaded. To change the current service (ie. once one is already set) then the client MUST first unsubscribe all stream events and successfully unload all objects and carousels (from the current service). If any errors occur then clDsmReset may need to be called (with force switches - see Additional information below) before a new (or even the same) service can be set. When this function is re-called. If the service details match those currently set then it will take no action. If they are different then the new service details are stored (unless objects and/or carousels are still loaded, in which case they are ignored and an error generated). To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters

instance	DSMCC instance handle
original_network_id	DVB Network Identifier
transport_stream_id	DVB Transport stream/Multiplex Identifier
service_id	DVB Service Identifier

Returns: CLDSM_OK (0) The new current service details were successfully set. CLDSM_ERR_CAROUSELS_STILL_LOADED The new current service details could not be set because one or more carousels from this service were still loaded CLDSM_ERR_OBJECTS_STILL_LOADED The new current service details could not be set because one or more objects from this service were still loaded

void CDSM_SysSetMemoryMax	(	H_DsmCoreInst	instance,
		U32BIT	maxMemory
	)

Set maximum memory usage.

Parameters

instance

Returns: n/a

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Function Documentation