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 "moduleDecompress.h"
#include "dataCarousel.h"
#include "objectCarousel.h"
#include "loadMgr.h"
#include "siQuery.h"
#include "defMemUtilsContig.h"
#include "pmtUpdate.h"
#include "sectionTimer.h"
#include "streamEvent.h"
#include <stdio.h>

Data Structures
struct	_accelerate_carousel_loading_struct
Typedefs
typedef struct _accelerate_carousel_loading_struct	accelerateCarouselLoading_t
Functions
void	clDsmSetPrintFuncs (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.
void	clDsmSetPrintState (U32BIT state)
	Sets debug print state to select areas of debug.
clDsmErr_t	clDsmSysCreate (pclDsmSetup_t pSetup, clDsmInstHandle_t pInstance, void *pMemContext)
clDsmErr_t	clDsmSysDestroy (clDsmInstHandle_t 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.
H_DsmControl	clDsmSysGetControl (clDsmInstHandle_t instance)
	Get control handle from DSM instance .
clDsmErr_t	clDsmUnloadAllObjects (pclDsmInstData_t idp, E_DsmRstMode mode)
clDsmErr_t	clDsmUnloadAllCarousels (pclDsmInstData_t idp, U8BIT mode)
clDsmErr_t	clDsmCheckAllQueries (pclDsmInstData_t idp)
clDsmErr_t	clDsmSysReset (clDsmInstHandle_t instance, E_DsmRstMode mode)
	Reset DSM-CC Core Layer instance. Resets conditions to the same state as after clDsmSysCreate (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.
void	clDsmSysSetMemoryMax (clDsmInstHandle_t instance, U32BIT maxMemory)
	Set maximum memory usage.
clDsmErr_t	clDsmSysSetCurrService (clDsmInstHandle_t 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.
U16BIT	clDsmSysCurrServiceId (clDsmInstHandle_t instance)
clDsmErr_t	clDsmSysProcessTimerEvent (clDsmInstHandle_t instance, void clDsmTmrUserData, clDsmTimerEventStatus_t status, void timerHandle)
clDsmErr_t	clDsmSysProcessSIQueryEvent (clDsmInstHandle_t instance, clDsmSIQueryRef_t clDsmSIQueryRef, void *clDsmSIUserData, pclDsmSIQueryResult_t 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.
clDsmErr_t	clDsmSysProcessSIChangeEvent (clDsmInstHandle_t instance, clDsmSIChangeEvent_t 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:
clDsmErr_t	clDsmSectionPriority (clDsmInstHandle_t instance, clDsmSFRef_t dsmFilterRef, clDsmSFPriority_t *priority)
clDsmErr_t	clDsmSysProcessPrivateSection (clDsmInstHandle_t instance, U8BIT *pSection, clDsmSFRef_t dsmFilterRef)
U8BIT *	SkipTaps (U8BIT *pData)
U8BIT *	SkipServiceContexts (U8BIT *pData)
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 clDsmSetPrintFuncs	(	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 clDsmSetPrintState ( U32BIT state )

Sets debug print state to select areas of debug.

Parameters:

U32BIT state See defines above

Returns:: void

clDsmErr_t clDsmSysDestroy	(	clDsmInstHandle_t	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 clDsmSysGetControl ( clDsmInstHandle_t instance )

Get control handle from DSM instance .

Parameters:

instance

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

clDsmErr_t clDsmSysProcessSIChangeEvent	(	clDsmInstHandle_t	instance,
		clDsmSIChangeEvent_t	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:

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.

clDsmErr_t clDsmSysProcessSIQueryEvent	(	clDsmInstHandle_t	instance,
		clDsmSIQueryRef_t	clDsmSIQueryRef,
		void *	clDsmSIUserData,
		pclDsmSIQueryResult_t	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.

clDsmErr_t clDsmSysProcessTimerEvent	(	clDsmInstHandle_t	instance,
		void *	clDsmTmrUserData,
		clDsmTimerEventStatus_t	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)

clDsmErr_t clDsmSysReset	(	clDsmInstHandle_t	instance,
		E_DsmRstMode	mode
	)

Reset DSM-CC Core Layer instance. Resets conditions to the same state as after clDsmSysCreate (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.

clDsmErr_t clDsmSysSetCurrService	(	clDsmInstHandle_t	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 clDsmSysSetMemoryMax	(	clDsmInstHandle_t	instance,
		U32BIT	maxMemory
	)

Set maximum memory usage.

Parameters:

instance

Returns:: n/a

Data Structures

Typedefs

Functions

Variables

Detailed Description

Function Documentation