Main API to DSM-CC core layer (provided functions and required callbacks). More...

#include "cldsmtypes.h"

Data Structures
struct	clDsmSetup_t
Defines
#define	NUM_OPEN_DSM_OBJECTS_MAX 128
#define	DSMCC_MINIMUM_CACHE_SIZE (1024 * 1024 * 1)
#define	DSMCC_DEFAULT_CACHE_SIZE (1024 * 1024 * 6)
#define	CACHE_RULES_DEFAULT 0x003F
#define	CACHE_RULES_FROM_STREAM (0)
#define	CACHE_RULES_STATIC 0x0080
#define	CACHE_RULES_EXISTS 0x0400
#define	CLDSM_PROG_CURR_SERVICE_CACHE_FULL 0
Typedefs
typedef struct _clDsmTimerRef_struct *	clDsmTimerRef_t
typedef enum clDsmTimerEventStatus_t *	pclDsmTimerEventStatus_t
typedef struct s_ObjCarousel *	clDsmOCHandle_t
typedef struct _clDsmObjectHandle_struct *	clDsmObjHandle_t
typedef enum clDsmObjectKind_t *	pclDsmObjectKind_t
typedef enum clDsmObjLoadStatus_t *	pclDsmObjLoadStatus_t
typedef struct s_ObjUserData *	H_ObjUserData
typedef struct _clDsmStreamEventHandle_struct *	clDsmStreamEventHandle_t
typedef void (	clDsmAllocFunc_t )(U32BIT sizeInBytes)
typedef void(*	clDsmFreeFunc_t )(void *memory)
typedef void(*	clDsmErrorFunc_t )(clDsmErr_t err, void *args)
typedef void(*	clDsmProgressFunc_t )(U32BIT prog, void *args)
typedef clDsmErr_t(*	clDsmStartTimerFunc_t )(H_DsmControl dsmControl, U32BIT timePeriod, void clDsmTmrUserData, void *pTimerHandle)
typedef void(*	clDsmStopTimerFunc_t )(H_DsmControl dsmControl, void *timerHandle)
typedef clDsmErr_t(*	clDsmStartSIQueryFunc_t )(H_SiqInstance siqInstance, pclDsmSIQuery_t pQuery, clDsmSIQueryRef_t clDsmSIQueryRef, void clDsmSIUserData, clDsmSIQueryResult_t pResult)
typedef void(*	clDsmStopSIQueryFunc_t )(H_SiqInstance siqInstance, void *queryHandle, clDsmSIQueryRef_t clDsmSIQueryRef)
typedef clDsmErr_t(*	clDsmSubscribeSIChanged_t )(H_SiqInstance siqInstance, U16BIT service_id)
typedef void(*	clDsmUnsubscribeSIChanged_t )(H_SiqInstance siqInstance, U16BIT service_id)
typedef void (	clDsmAddSectionFilterFunc_t )(H_SfmInstance sfm, pclDsmSFilter_t pFilter, clDsmSFRef_t dsmFilterRef)
typedef void(*	clDsmDelSectionFilterFunc_t )(H_SfmInstance sfm, void *filterHandle, clDsmSFRef_t clDsmFilterRef)
typedef void(*	clDsmSFPriorityChangedFunc_t )(H_SfmInstance sfm, void *filterHandle, clDsmSFRef_t clDsmFilterRef, clDsmSFPriority_t priority)
typedef void(*	clDsmNotifyCarouselLoadEventFunc_t )(clDsmOCHandle_t clDsmCarouselHandle, E_OCLoadStatus status, U32BIT carouselId)
typedef void(*	clDsmNotifyObjectLoadEventFunc_t )(clDsmObjHandle_t clDsmObjectHandle, clDsmObjLoadStatus_t status, H_ObjUserData pCopyOfObjLoadUserData)
typedef void(*	clDsmNotifyStreamEventFunc_t )(H_DsmEvent eventHandle, clDsmSENotifyStatus_t status, void userData1, void userData2, U8BIT namePtr, U8BIT dataPtr, U8BIT namelen, U8BIT dataLen)
	The Client defines this function to enable the DSMCC to communicate to the Client when any subscribed to stream event has occurred. DSMCC prototypes this function; the Client defines this function. i.e. This function must be implemented in the Client not in the DSMCC. There will be a single callback function that will be called when an event occurs. This callback function was specified when the Client created the DSMCC instance. The callback may be called a number of times if the event is re-defined. The clDsmStreamEventSubscribe() function must have been successfully called before the Client callback function will be called. The callback can be called when an error occurs. The callback is also called when an unsubscribe has completed. The 'status' argument to the callback differentiates between unsubscribe, errors and event triggered. The two streamEventUserData values allow the Client to differentiate between the many stream events that are notified through the single callback function.
typedef void(*	clDsmNotifyDeferredServiceFunc_t )(void userData1, void userData2, S_DvbLocator *pDeferredService)
	Called when request for deferred service of stream object has completed after clDsmStreamGetDeferredService returned CLDSM_PENDING userData values supplied for flexibility.
typedef U32BIT	clDsmCachingRules_t
typedef struct clDsmSetup_t *	pclDsmSetup_t
Enumerations
enum	clDsmTimerEventStatus_t { TIMER_TRIGGERED = 0, TIMER_ABORTED }
enum	clDsmObjectKind_t { ANON_OBJ = 0, FILE_OBJ, DIRECTORY_OBJ, SERVICE_GATEWAY_OBJ, STREAM_OBJ, STREAM_OBJ_WITH_EVENTS, LINK_TO_ALTERNATE_OC_OBJ }
enum	clDsmObjLoadStatus_t { OBJ_LOAD_UNINITIATED = 0, OBJ_LOAD_IN_PROGRESS, OBJ_LOAD_COMPLETED, OBJ_LOAD_ABORTED_TIMEOUT, OBJ_LOAD_ABORTED_PATH_ERROR, OBJ_LOAD_ABORTED_ERROR, OBJ_LOAD_ABORTED_UNLOAD }
enum	clDsmSENotifyStatus_t { SEN_INITIAL, SEN_NOTIFIED, SEN_ABORTED_OBJ_LOAD_FAILED, SEN_ABORTED_SUBSCRIBE_FAILED, SEN_TRIGGERED, SEN_ACKNOWLEDGE_UNSUBSCRIBE }
Functions
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	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. 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.
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. 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	clDsmSysProcessPrivateSection (clDsmInstHandle_t instance, U8BIT *pSection, clDsmSFRef_t dsmFilterRef)
clDsmErr_t	clDsmSectionFilterPriority (clDsmInstHandle_t instance, clDsmSFRef_t dsmFilterRef, clDsmSFPriority_t *pPriority)
clDsmErr_t	clDsmLoadCarousel (clDsmInstHandle_t instance, U16BIT service_id, U32BIT carousel_id, U32BIT timeout, E_OCLoadStatus pStatus, clDsmOCHandle_t pclDsmCarouselHandle)
clDsmErr_t	clDsmUnloadCarousel (clDsmInstHandle_t instance, clDsmOCHandle_t clDsmCarouselHandle, E_DsmRstMode mode)
	Unload (or cancel the requested load of) a DSM-CC Object Carousel (service domain). The client MUST first unload all objects before calling this function (which implies it must also have previously closed and/or unsubscribed any events on any loaded objects). If there are any active object loads in the carousel when clDsmUnloadCarousel is called then the unload will not be executed and an error returned. If the carousel is in the process of loading and/or booting the load operation will be aborted (and the notifyCarouselLoadEventFunc callback made with status OC_LOAD_ABORTED_UNLOAD). Any carousel load request that returned a valid clDsmCarouselHandle (ie. did not generate an error at clDsmLoadCarousel call time), must be explicitly unloaded via clDsmUnloadCarousel. This is necessary, whether the carousel was successfully loaded or the load was aborted due to timeout or error. Once unload is called for a carousel, the clDsmCarouselHandle is no longer valid and must not be used by the client/calling env. If it needs to access the carousel subsequently it must re-load it and get a new clDsmCarouselHandle value. To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. Note that this physically deletes them from the cache whereas unloading (objects or carousels) does not. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: delSectionFilterFunc stopTimerFunc stopSIQueryFunc unsubscribeSIChange notifyCarouselLoadEventFunc.
clDsmErr_t	clDsmGetCarouselId (clDsmInstHandle_t instance, clDsmOCHandle_t carouselHandle, U32BIT *pCarouselId)
	Retrieve Carousel Id for the loaded DSM-CC Object Carousel.
clDsmOCHandle_t	clDsmCurrentCarousel (clDsmInstHandle_t instance)
	Retrieve handle to the current carousel for DSM-CC Instance.
clDsmErr_t	clDsmSetCurrentCarousel (clDsmInstHandle_t instance, clDsmOCHandle_t carouselHandle)
	Sets current carousel for DSM-CC Instance.
clDsmErr_t	clDsmCarouselLoadFileGroups (clDsmInstHandle_t instance, clDsmOCHandle_t clDsmCarouselHandle, U16BIT total, S_CarouselInfoFileGroup *pGroups)
	Retrieve from Object Carousel's User Info, the "File Group Info" used by Australia and South Africa MHEG profiles.
clDsmErr_t	clDsmCarouselUnloadFileGroups (clDsmInstHandle_t instance, clDsmOCHandle_t clDsmCarouselHandle, S_CarouselInfoFileGroup *groups)
	Release "File Group Info" data allocated by used by clDsmCarouselLoadFileGroups()
clDsmErr_t	clDsmLoadObject (clDsmInstHandle_t instance, U8BIT pathname, U32BIT timeout, clDsmCachingRules_t cachingRules, H_ObjUserData pUserData, U32BIT sizeOfUserData, clDsmObjLoadStatus_t pStatus, clDsmObjHandle_t *pclDsmObjectHandle)
clDsmErr_t	clDsmUnloadObject (clDsmInstHandle_t instance, clDsmObjHandle_t clDsmObjectHandle, E_DsmRstMode mode)
	Unload (or cancel the requested load of) a DSM-CC object The client MUST first close and/or unsubscribe any events on the object before calling this function. If the object is open or there are any active subscribed events on it when clDsmUnloadObject is called then the unload will not be executed and an error returned. If the object load is still in progress the load operation will be aborted (and the notifyObjectLoadEventFunc callback made with status OBJ_LOAD_ABORTED_UNLOAD). If the object load is completed then unloading the object does not (necessarily) mean it (or it's parent module) is deleted from the cache. It does mean the cached object (or parent module) can now be updated from the input stream or deleted from the cache when creating space for new items. All object load requests that return a valid clDsmObjectHandle (ie. did not generate an error at clDsmLoadObject call time) must be explicitly unloaded via clDsmUnloadObject. This is mandatory, whether the object was successfully loaded or the load was aborted due to timeout or error. Once unload is called for an object, the clDsmObjectHandle is no longer valid and must not be used by the client/calling env. If it needs to access the object subsequently it must re-load it and get a new clDsmObjectHandle value. ** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED ** Unloading an object causes the object's current caching rules to be applied and these affect whether or not it is subsequently kept in the cache. If fromStream is set, the object (or parent module) is deleted from the cache. If the same object is loaded multiple times in parallel, then the caching rules are applied only when the last of the object load instances is unloaded. NB. For module based caching (as currently implemented) the whole module inherits the caching rules MOST RECENTLY SPECIFIED for any object in that module. The rules for when multiple objects from the same module are requested (or loaded) in parallel are applied to a module on the same basis as described for multiple instances of the same object. To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. Note that this physically deletes them from the cache whereas unloading (objects or carousels) does not. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: delSectionFilterFunc stopTimerFunc stopSIQueryFunc notifyObjectLoadEventFunc.
clDsmErr_t	clDsmOpenObject (clDsmInstHandle_t instance, clDsmObjHandle_t clDsmObjectHandle, clDsmObjectKind_t *pKind)
	Open object data for subsequent access via API functions for given object kind. The object must have already been loaded. Data that is specific to object kind is read and possibly stored here. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.
clDsmErr_t	clDsmCloseObject (clDsmInstHandle_t instance, clDsmObjHandle_t clDsmObjectHandle)
clDsmInstHandle_t	clDsmObjectGetInstance (clDsmObjHandle_t clDsmObjectHandle)
	Get DSM instance to which the object belongs.
clDsmErr_t	clDsmSetObjectCachingRules (clDsmInstHandle_t instance, U8BIT *pathname, clDsmCachingRules_t cachingRules)
clDsmErr_t	clDsmPrefetchObject (clDsmInstHandle_t instance, U8BIT *pathname, U32BIT timeout)
clDsmErr_t	clDsmStreamEventSubscribe (clDsmInstHandle_t dsmccInstance, clDsmObjHandle_t streamObject, U8BIT eventName, void userData1, void userData2, H_DsmEvent pEventHandle)
	The Client uses this function to request that the DSMCC notifies it when a named stream event occurs. The notification is implemented by means of a callback function defined by the Client. Refer to the description of clDsmNotifyStreamEventFunc_t for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the clDsmObjectLoad() function. This action will deliver a handle to the object stream - this is passed as the streamObject argument to this function. Do not have to wait until load is completed before subscribing. Do not have to open an object before subscribing (since synchronous function). CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.
clDsmErr_t	clDsmStreamEventUnsubscribe (clDsmInstHandle_t dsmccInstance, H_DsmEvent eventHandle)
	This function is called by the Client to let DSMCC know when a previously subscribed stream event is no longer needed. Callback made to acknowledge unsubscribe. All data relating to this stream event will no longer be valid, including the eventHandle. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.
clDsmErr_t	clDsmSpecialEventSubscribe (clDsmInstHandle_t dsmccInstance, U16BIT associationTag, U16BIT eventId, void userData1, void userData2, H_DsmEvent *pEventHandle)
	Like clDsmStreamEventSubscribe, except that no stream object is required. This function subscribes to events specified by event ID, and association tag for the current service.
clDsmErr_t	clDsmSpecialEventUnsubscribe (clDsmInstHandle_t dsmccInstance, H_DsmEvent eventHandle)
	Same as clDsmStreamEventUnsubscribe - used in conjuction with clDsmSpecialEventSubscribe.
clDsmErr_t	dsmObjectGetKind (clDsmObjHandle_t clDsmObjectHandle, clDsmObjectKind_t *pKind)
clDsmErr_t	dsmObjectGetCarouselHandle (clDsmObjHandle_t clDsmObjectHandle, void **hCarouselHandle)
clDsmErr_t	dsmGetObjectServiceContext (clDsmObjHandle_t clDsmObjectHandle, U32BIT serviceId, U8BIT *pSrvCtxtData, U32BIT pSrvCtxtLen)
	This function gets service context of DSM object (if available) Need by MHEG5 for specified service gateway (SRG) object. The Dsm object (clDsmObjectHandle) must be LOADED and OPEN. When serviceId cannot be found then matched then a pathname of '\0' is returned. On return from this function the current location within the SRG object message will remain the same as before the function was called. This means that this function can be called more than once in succession without reopening the memory sequence.
clDsmErr_t	dsmFileGetSize (clDsmObjHandle_t clDsmFileObjectHandle, U32BIT *pSize)
clDsmErr_t	clDsmFileRead (clDsmObjHandle_t clDsmFileObjectHandle, U32BIT numBytes, U8BIT pDest, U32BIT pNumBytesActual)
clDsmErr_t	clDsmFileDirect (clDsmObjHandle_t clDsmFileObjectHandle, U8BIT *ppDest, U32BIT pNumBytesActual)
clDsmErr_t	dsmFileReadByte (clDsmObjHandle_t clDsmFileObjectHandle, U8BIT *pDest)
clDsmErr_t	dsmFileSetPosAbs (clDsmObjHandle_t clDsmFileObjectHandle, U32BIT absPosition)
clDsmErr_t	dsmFileSetPosRel (clDsmObjHandle_t clDsmFileObjectHandle, S32BIT relPosition)
clDsmErr_t	dsmFileGetPos (clDsmObjHandle_t clDsmFileObjectHandle, U32BIT *pPosition)
clDsmErr_t	dsmDirEntrySizes (clDsmObjHandle_t dirObj, U16BIT nameCount, U16BIT totalNameLength)
clDsmErr_t	dsmDirEntryFirst (clDsmObjHandle_t dirObj, void **pFirstEntry)
clDsmErr_t	dsmDirEntryNext (void entryHandle, void *pNextEntry)
U16BIT	dsmDirEntryNameLength (void *entryHandle)
U16BIT	dsmDirEntryNameCopy (void entryHandle, U8BIT pName)
clDsmObjectKind_t	dsmDirEntryKind (void *entryHandle)
clDsmErr_t	dsmStreamGetProgramAssocTag (clDsmObjHandle_t streamObjectHandle, U16BIT *pAssociation_tag)
	The Client calls this function to obtain the Association Tag which can be used to determine the PID on which stream data can be found. Before calling this function the Client must have completed loading and opened the stream object.
clDsmErr_t	clDsmStreamGetDeferredService (clDsmInstHandle_t instance, clDsmObjHandle_t streamObject, void userData1, void userData2, S_DvbLocator **ppDeferredService)
	The Client calls this function to obtain the Association Tag which can be used to determine the PID on which stream data can be found. Before calling this function the Client must have completed loading and opened the stream object.
clDsmErr_t	clDsmStreamEventNameList (clDsmInstHandle_t dsmccInstance, clDsmObjHandle_t streamObject, U8BIT *pNamesPtr, U16BIT pNamesLen)
	The Client uses this function to request list of event names for stream object Before calling this function the Client must request that the stream object of interest be loaded using the clDsmObjectLoad() function. This action will deliver a handle to the object stream - this is passed as the streamObject argument to this function. Do not have to wait until load is completed Do not have to open an object.

Detailed Description

Main API to DSM-CC core layer (provided functions and required callbacks).

Date:: 01/02/2002

Author:: R.Freeman

Typedef Documentation

typedef void(* clDsmNotifyDeferredServiceFunc_t)(void *userData1, void *userData2, S_DvbLocator *pDeferredService)

Called when request for deferred service of stream object has completed after clDsmStreamGetDeferredService returned CLDSM_PENDING userData values supplied for flexibility.

Parameters:

userData1	Optional data to be used by client. This data was supplied by the Client when a subscription was taken out on a stream event.
userData2	Optional data to be used by client. This data was supplied by the Client when a subscription was taken out on a stream event.
deferredService	Deferred Service for Stream object .

Returns:: There is no return value.

typedef void(* clDsmNotifyStreamEventFunc_t)(H_DsmEvent eventHandle, clDsmSENotifyStatus_t status, void *userData1, void *userData2, U8BIT *namePtr, U8BIT *dataPtr, U8BIT namelen, U8BIT dataLen)

The Client defines this function to enable the DSMCC to communicate to the Client when any subscribed to stream event has occurred. DSMCC prototypes this function; the Client defines this function. i.e. This function must be implemented in the Client not in the DSMCC. There will be a single callback function that will be called when an event occurs. This callback function was specified when the Client created the DSMCC instance. The callback may be called a number of times if the event is re-defined. The clDsmStreamEventSubscribe() function must have been successfully called before the Client callback function will be called. The callback can be called when an error occurs. The callback is also called when an unsubscribe has completed. The 'status' argument to the callback differentiates between unsubscribe, errors and event triggered. The two streamEventUserData values allow the Client to differentiate between the many stream events that are notified through the single callback function.

Parameters:

eventHandle	This is the handle obtained when the stream event was subscribed to. The client will use this handle when this stream event is referred to in the future.
status	Status of the subscription.
userData1	Optional data to be used by client. This data was supplied by the Client when a subscription was taken out on a stream event.
userData2	Optional data to be used by client. This data was supplied by the Client when a subscription was taken out on a stream event.
namePtr	Event Name pointer
dataPtr	Event Data pointer
namelen	Event Name length
dataLen	Event Data length

Returns:: There is no return value.

Function Documentation

clDsmErr_t clDsmCarouselLoadFileGroups	(	clDsmInstHandle_t	instance,
		clDsmOCHandle_t	clDsmCarouselHandle,
		U16BIT *	total,
		S_CarouselInfoFileGroup **	pGroups
	)

Retrieve from Object Carousel's User Info, the "File Group Info" used by Australia and South Africa MHEG profiles.

Parameters:

instance	DSMCC instance handle
clDsmCarouselHandle	Handle to carousel.
total	total number of file groups
pGroups	array of File Group Info

Returns:: CLDSM_OK CLDSM_ERR_INVALID_CAROUSEL_HANDLE

clDsmErr_t clDsmCarouselUnloadFileGroups	(	clDsmInstHandle_t	instance,
		clDsmOCHandle_t	clDsmCarouselHandle,
		S_CarouselInfoFileGroup *	groups
	)

Release "File Group Info" data allocated by used by clDsmCarouselLoadFileGroups()

Parameters:

instance	DSMCC instance handle
clDsmCarouselHandle	Handle to carousel to be unloaded.
groups	array of File Group Info

Returns:: CLDSM_OK (0) Unload was executed with no problems. CLDSM_ERR_INVALID_CAROUSEL_HANDLE Unload was not executed because an invalid carousel handle was supplied.

clDsmOCHandle_t clDsmCurrentCarousel ( clDsmInstHandle_t instance )

Retrieve handle to the current carousel for DSM-CC Instance.

Parameters:

instance DSMCC instance handle

Returns:: clDsmOCHandle_t - handle to current carousel

clDsmErr_t clDsmGetCarouselId	(	clDsmInstHandle_t	instance,
		clDsmOCHandle_t	carouselHandle,
		U32BIT *	pCarouselId
	)

Retrieve Carousel Id for the loaded DSM-CC Object Carousel.

Parameters:

instance	DSMCC instance handle
clDsmCarouselHandle	Handle to carousel to be unloaded.
pCarouselId	Carousel ID

Returns:: CLDSM_OK CLDSM_ERR_INVALID_CAROUSEL_HANDLE

clDsmInstHandle_t clDsmObjectGetInstance ( clDsmObjHandle_t clDsmObjectHandle )

Get DSM instance to which the object belongs.

Parameters:

clDsmObjectHandle DSM object handle

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

clDsmErr_t clDsmOpenObject	(	clDsmInstHandle_t	instance,
		clDsmObjHandle_t	clDsmObjectHandle,
		clDsmObjectKind_t *	pKind
	)

Open object data for subsequent access via API functions for given object kind. The object must have already been loaded. Data that is specific to object kind is read and possibly stored here. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

instance	Instance of DSMCC containing object
clDsmObjectHandle	Handle to the Object
pKind	Populated with the object kind

Returns:: CLDSM_OK The object was successfully opened CLDSM_ERR_INVALID_OBJECT_HANDLE The handle is not a valid object handle CLDSM_ERR_OBJECT_NOT_LOADED The object has not been loaded CLDSM_ERR_OPEN_OBJECT_LIMIT The maximum number of open objects allowed has been reached CLDSM_ERR_OBJECT_OPEN The object is already open CLDSM_ERR_INVALID_OBJECT_TYPE The object is not a 'Stream Object', or a 'Stream Object with Events' or a 'File Object'. CLDSM_ERR_END_OF_DATA The object has zero length.

Open object data for subsequent access via API functions for given object kind. The object must have already been loaded. Data that is specific to object kind is read and possibly stored here. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

instance	Instance of DSMCC containing object
clDsmObjectHandle	Handle to the Object
pKind	Populated with the object kind

Returns:: CLDSM_OK The object was successfully opened CLDSM_ERR_INVALID_OBJECT_HANDLE The handle is not a valid object handle CLDSM_ERR_OBJECT_NOT_LOADED The object has not been loaded CLDSM_ERR_OPEN_OBJECT_LIMIT The maximum number of open objects allowed has been reached CLDSM_ERR_OBJECT_OPEN The object is already open CLDSM_ERR_INVALID_OBJECT_TYPE The object is not a supported object type (see above list of valid types). CLDSM_ERR_END_OF_DATA The object has zero length.

clDsmErr_t clDsmSetCurrentCarousel	(	clDsmInstHandle_t	instance,
		clDsmOCHandle_t	carouselHandle
	)

Sets current carousel for DSM-CC Instance.

Parameters:

instance	DSMCC instance handle
carouselHandle	Handle to carousel

Returns:: CLDSM_OK CLDSM_ERR_INVALID_CAROUSEL_HANDLE

clDsmErr_t clDsmSpecialEventSubscribe	(	clDsmInstHandle_t	dsmccInstance,
		U16BIT	associationTag,
		U16BIT	eventId,
		void *	userData1,
		void *	userData2,
		H_DsmEvent *	pEventHandle
	)

Like clDsmStreamEventSubscribe, except that no stream object is required. This function subscribes to events specified by event ID, and association tag for the current service.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
associationTag	Association tag used to retrieve PID that contains required stream events
eventId	Stream event ID required by the Client.
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
pEventHandle	The is the handle to the stream event returned by subscribe. The caller will use this handle when the stream event being subscribed to is referred to in the future.

Returns:: CLDSM_ERR_INVALID_INSTANCE The Instance value is invalid CLDSM_ERR_INVALID_STREAM_EVENT_NAME The supplied event name is invalid CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle is invalid CLDSM_ERR_INVALID_OBJECT_TYPE The message referred to by streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_NO_STREAM_EVENT_NOTIFY_CALLBACK If Stream Events are to be used then a callback must be registered. CLDSM_ERR_MEM_HEAP_FULL Out of memory. CLDSM_ERR_NO_CURRENT_SERVICE_SET clDsmSysSetCurrService has not been called prior to calling this function CLDSM_OK The event has been successfully subscribed to.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This references a BIOP::StreamEventMessage as well as indicating the carousel, module and the kind of the object.
eventName	Name of stream event required by the Client.
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
pStatus	Status of the subscription.
pEventHandle	The is the handle to the stream event returned by subscribe. The caller will use this handle when the stream event being subscribed to is referred to in the future.

Returns:: CLDSM_ERR_INVALID_INSTANCE The Instance value is invalid CLDSM_ERR_INVALID_STREAM_EVENT_NAME The supplied event name is invalid CLDSM_ERR_SUBSCRIBE_FAILURE The event could not be subscribed to CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle is invalid CLDSM_ERR_INVALID_OBJECT_TYPE The message referred to by streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_NO_STREAM_EVENT_NOTIFY_CALLBACK If Stream Events are to be used then a callback must be registered. CLDSM_ERR_MEM_HEAP_FULL Out of memory. CLDSM_OK The event has been successfully subscribed to.

clDsmErr_t clDsmSpecialEventUnsubscribe	(	clDsmInstHandle_t	dsmccInstance,
		H_DsmEvent	eventHandle
	)

Same as clDsmStreamEventUnsubscribe - used in conjuction with clDsmSpecialEventSubscribe.

Parameters:

dsmccInstance	Allows support of >= 1 instance of a DSMCC.
eventHandle	This is a handle to an entry which is to be deleted from a list of subscribed to stream events

Returns:: CLDSM_ERR_INVALID_STREAM_EVENT_HANDLE The eventHandle is not valid. CLDSM_OK The stream event was successfully unsubscribed

Parameters:

dsmccInstance	Allows support of >= 1 instance of a DSMCC.
eventHandle	This is a handle to an entry which is to be deleted from a list of subscribed to stream events

Returns:: CLDSM_ERR_INVALID_STREAM_EVENT_HANDLE The streamEventHandle is not valid. CLDSM_OK The stream event was successfully unsubscribed

clDsmErr_t clDsmStreamEventNameList	(	clDsmInstHandle_t	dsmccInstance,
		clDsmObjHandle_t	streamObject,
		U8BIT **	pNamesPtr,
		U16BIT *	pNamesLen
	)

The Client uses this function to request list of event names for stream object Before calling this function the Client must request that the stream object of interest be loaded using the clDsmObjectLoad() function. This action will deliver a handle to the object stream - this is passed as the streamObject argument to this function. Do not have to wait until load is completed Do not have to open an object.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This references a BIOP::StreamEventMessage as well as indicating the carousel, module and the kind of the object.
pNamesPtr	Pointer to comma separated list of Event names
pNamesLen	Length of comma separated list of Event names

Returns:: CLDSM_ERR_INVALID_INSTANCE The Instance value is invalid CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle is invalid CLDSM_ERR_INVALID_OBJECT_TYPE The message referred to by streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_MEM_HEAP_FULL Out of memory. CLDSM_OK Successfully retrieved list of names for this stream object.

clDsmErr_t clDsmStreamEventSubscribe	(	clDsmInstHandle_t	dsmccInstance,
		clDsmObjHandle_t	streamObject,
		U8BIT *	eventName,
		void *	userData1,
		void *	userData2,
		H_DsmEvent *	pEventHandle
	)

The Client uses this function to request that the DSMCC notifies it when a named stream event occurs. The notification is implemented by means of a callback function defined by the Client. Refer to the description of clDsmNotifyStreamEventFunc_t for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the clDsmObjectLoad() function. This action will deliver a handle to the object stream - this is passed as the streamObject argument to this function. Do not have to wait until load is completed before subscribing. Do not have to open an object before subscribing (since synchronous function). CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This references a BIOP::StreamEventMessage as well as indicating the carousel, module and the kind of the object.
eventName	Name of stream event required by the Client.
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
pEventHandle	The is the handle to the stream event returned by subscribe. The caller will use this handle when the stream event being subscribed to is referred to in the future.

Returns:: CLDSM_ERR_INVALID_INSTANCE The Instance value is invalid CLDSM_ERR_INVALID_STREAM_EVENT_NAME The supplied event name is invalid CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle is invalid CLDSM_ERR_INVALID_OBJECT_TYPE The message referred to by streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_NO_STREAM_EVENT_NOTIFY_CALLBACK If Stream Events are to be used then a callback must be registered. CLDSM_ERR_MEM_HEAP_FULL Out of memory. CLDSM_OK The event has been successfully subscribed to.

The Client uses this function to request that the DSMCC notifies it when a named stream event occurs. The notification is implemented by means of a callback function defined by the Client. Refer to the description of clDsmNotifyStreamEventFunc_t for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the clDsmObjectLoad() function. This action will deliver a handle to the object stream - this is passed as the streamObject argument to this function. Do not have to wait until load is completed before subscribing. Do not have to open an object before subscribing (since synchronous function). CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This references a BIOP::StreamEventMessage as well as indicating the carousel, module and the kind of the object.
eventName	Name of stream event required by the Client.
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
pStatus	Status of the subscription.
pEventHandle	The is the handle to the stream event returned by subscribe. The caller will use this handle when the stream event being subscribed to is referred to in the future.

Returns:: CLDSM_ERR_INVALID_INSTANCE The Instance value is invalid CLDSM_ERR_INVALID_STREAM_EVENT_NAME The supplied event name is invalid CLDSM_ERR_SUBSCRIBE_FAILURE The event could not be subscribed to CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle is invalid CLDSM_ERR_INVALID_OBJECT_TYPE The message referred to by streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_NO_STREAM_EVENT_NOTIFY_CALLBACK If Stream Events are to be used then a callback must be registered. CLDSM_ERR_MEM_HEAP_FULL Out of memory. CLDSM_OK The event has been successfully subscribed to.

clDsmErr_t clDsmStreamEventUnsubscribe	(	clDsmInstHandle_t	dsmccInstance,
		H_DsmEvent	eventHandle
	)

This function is called by the Client to let DSMCC know when a previously subscribed stream event is no longer needed. Callback made to acknowledge unsubscribe. All data relating to this stream event will no longer be valid, including the eventHandle. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

dsmccInstance	Allows support of >= 1 instance of a DSMCC.
eventHandle	This is a handle to an entry which is to be deleted from a list of subscribed to stream events

Returns:: CLDSM_ERR_INVALID_STREAM_EVENT_HANDLE CLDSM_OK

This function is called by the Client to let DSMCC know when a previously subscribed stream event is no longer needed. Callback made to acknowledge unsubscribe. All data relating to this stream event will no longer be valid, including the eventHandle. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: none.

Parameters:

dsmccInstance	Allows support of >= 1 instance of a DSMCC.
eventHandle	This is a handle to an entry which is to be deleted from a list of subscribed to stream events

Returns:: CLDSM_ERR_INVALID_STREAM_EVENT_HANDLE The eventHandle is not valid. CLDSM_OK The stream event was successfully unsubscribed

clDsmErr_t clDsmStreamGetDeferredService	(	clDsmInstHandle_t	instance,
		clDsmObjHandle_t	streamObject,
		void *	userData1,
		void *	userData2,
		S_DvbLocator **	ppDeferredService
	)

The Client calls this function to obtain the Association Tag which can be used to determine the PID on which stream data can be found. Before calling this function the Client must have completed loading and opened the stream object.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This handle indicates the stream object
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
ppDeferredService	return a pointer to deferred service structure

Returns:: CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle was not valid. CLDSM_ERR_INVALID_OBJECT_TYPE The streamObject does not refer to data containing the association tag. CLDSM_ERR_OBJECT_NOT_LOADED The streamObject does not refer to a loaded object. CLDSM_ERR_OBJECT_NOT_OPEN The streamObject does not refer to an open object. CLDSM_ERR_UNABLE_TO_GET_PROGRAM_ASSOC_TAG No BIOP_PROGRAM_USE tap could be found. CLDSM_PENDING Deferred service request is pending, and will be given in callback CLDSM_OK Deferred service successfully obtained.

Parameters:

dsmccInstance	Allows support >= 1 instance of a DSMCC.
streamObject	This handle indicates the stream object
userData1	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
userData2	Optional data to be used by client. This data is stored and returned unchanged to the Client using a callback.
pDeferredService	return a pointer to deferred service structure

Returns:: CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle was not valid. CLDSM_ERR_INVALID_OBJECT_TYPE The streamObject does not refer to data containing the association tag. CLDSM_ERR_OBJECT_NOT_LOADED The streamObject does not refer to a loaded object. CLDSM_ERR_OBJECT_NOT_OPEN The streamObject does not refer to an open object. CLDSM_ERR_UNABLE_TO_GET_PROGRAM_ASSOC_TAG No BIOP_PROGRAM_USE tap could be found. CLDSM_ERR_SI_QUERY_FAILED SI Query Failed CLDSM_OK Association Tag was successfully obtained.

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. 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.

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. 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

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

clDsmErr_t clDsmUnloadCarousel	(	clDsmInstHandle_t	instance,
		clDsmOCHandle_t	clDsmCarouselHandle,
		E_DsmRstMode	mode
	)

Unload (or cancel the requested load of) a DSM-CC Object Carousel (service domain). The client MUST first unload all objects before calling this function (which implies it must also have previously closed and/or unsubscribed any events on any loaded objects). If there are any active object loads in the carousel when clDsmUnloadCarousel is called then the unload will not be executed and an error returned. If the carousel is in the process of loading and/or booting the load operation will be aborted (and the notifyCarouselLoadEventFunc callback made with status OC_LOAD_ABORTED_UNLOAD). Any carousel load request that returned a valid clDsmCarouselHandle (ie. did not generate an error at clDsmLoadCarousel call time), must be explicitly unloaded via clDsmUnloadCarousel. This is necessary, whether the carousel was successfully loaded or the load was aborted due to timeout or error. Once unload is called for a carousel, the clDsmCarouselHandle is no longer valid and must not be used by the client/calling env. If it needs to access the carousel subsequently it must re-load it and get a new clDsmCarouselHandle value. To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. Note that this physically deletes them from the cache whereas unloading (objects or carousels) does not. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: delSectionFilterFunc stopTimerFunc stopSIQueryFunc unsubscribeSIChange notifyCarouselLoadEventFunc.

Parameters:

instance	DSMCC instance handle
clDsmCarouselHandle	Handle to carousel to be unloaded.

Returns:: CLDSM_OK (0) Unload was executed with no problems. CLDSM_ERR_INVALID_CAROUSEL_HANDLE Unload was not executed because an invalid carousel handle was supplied. CLDSM_ERR_OBJECTS_STILL_LOADED Unload was not executed because there were still active object loads.

clDsmErr_t clDsmUnloadObject	(	clDsmInstHandle_t	instance,
		clDsmObjHandle_t	clDsmObjectHandle,
		E_DsmRstMode	mode
	)

Unload (or cancel the requested load of) a DSM-CC object The client MUST first close and/or unsubscribe any events on the object before calling this function. If the object is open or there are any active subscribed events on it when clDsmUnloadObject is called then the unload will not be executed and an error returned. If the object load is still in progress the load operation will be aborted (and the notifyObjectLoadEventFunc callback made with status OBJ_LOAD_ABORTED_UNLOAD). If the object load is completed then unloading the object does not (necessarily) mean it (or it's parent module) is deleted from the cache. It does mean the cached object (or parent module) can now be updated from the input stream or deleted from the cache when creating space for new items. All object load requests that return a valid clDsmObjectHandle (ie. did not generate an error at clDsmLoadObject call time) must be explicitly unloaded via clDsmUnloadObject. This is mandatory, whether the object was successfully loaded or the load was aborted due to timeout or error. Once unload is called for an object, the clDsmObjectHandle is no longer valid and must not be used by the client/calling env. If it needs to access the object subsequently it must re-load it and get a new clDsmObjectHandle value. **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED **** Unloading an object causes the object's current caching rules to be applied and these affect whether or not it is subsequently kept in the cache. If fromStream is set, the object (or parent module) is deleted from the cache. If the same object is loaded multiple times in parallel, then the caching rules are applied only when the last of the object load instances is unloaded. NB. For module based caching (as currently implemented) the whole module inherits the caching rules MOST RECENTLY SPECIFIED for any object in that module. The rules for when multiple objects from the same module are requested (or loaded) in parallel are applied to a module on the same basis as described for multiple instances of the same object. To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. Note that this physically deletes them from the cache whereas unloading (objects or carousels) does not. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: delSectionFilterFunc stopTimerFunc stopSIQueryFunc notifyObjectLoadEventFunc.

Parameters:

instance	DSMCC instance handle
clDsmObjectHandle	Handle to object to be unloaded. mode IN

Returns:: CLDSM_OK (0) Unload was executed with no problems. CLDSM_ERR_INVALID_OBJECT_HANDLE Unload was not executed because an invalid object handle was supplied. CLDSM_ERR_OBJECT_OPEN Unload was not executed because the object was still open. CLDSM_ERR_STREAM_EVENTS_SUBSCRIBED Unload was not executed because there were still subscribed events on this object.

clDsmErr_t dsmGetObjectServiceContext	(	clDsmObjHandle_t	clDsmObjectHandle,
		U32BIT	serviceId,
		U8BIT **	pSrvCtxtData,
		U32BIT *	pSrvCtxtLen
	)

This function gets service context of DSM object (if available) Need by MHEG5 for specified service gateway (SRG) object. The Dsm object (clDsmObjectHandle) must be LOADED and OPEN. When serviceId cannot be found then matched then a pathname of '\0' is returned. On return from this function the current location within the SRG object message will remain the same as before the function was called. This means that this function can be called more than once in succession without reopening the memory sequence.

Parameters:

clDsmSRGObjectHandle	SRG object handle supplied when object was loaded (via clDsmLoadObject).
serviceId	ServiceID in a ServiceContextList in a ServiceGatewayMessage. For MHEG this is made from data_broadcast_id (hi-order bytes) and application_type_code (lo-order bytes).
pSrvCtxtData	Returned pointer of service context data
pSrvCtxtLen	Returned length of service context data

Returns:: CLDSM_OK (0) The SRG object was successfully parsed for an MHEG5 initial object path (nb. this does not imply an initial object path was actually found). CLDSM_ERR_INVALID_OBJECT_HANDLE clDsmSRGObjectHandle is not a valid object reference. CLDSM_ERR_INVALID_OBJECT_TYPE The object is not an SRG. CLDSM_ERR_OBJECT_NOT_LOADED The object is not yet loaded. CLDSM_ERR_OBJECT_NOT_OPEN The object is not open. CLDSM_ERR_END_OF_DATA No matching service context for 'serviceId'

clDsmErr_t dsmStreamGetProgramAssocTag	(	clDsmObjHandle_t	streamObjectHandle,
		U16BIT *	pAssociation_tag
	)

The Client calls this function to obtain the Association Tag which can be used to determine the PID on which stream data can be found. Before calling this function the Client must have completed loading and opened the stream object.

Parameters:

streamObjectHandle	This handle indicates the stream object for which the association tag is required.
pAssociation_tag	This value is indirectly used by the Client to access elementary stream data, i.e. video/audio PIDs.

Returns:: CLDSM_ERR_INVALID_OBJECT_HANDLE The supplied object handle was not valid. CLDSM_ERR_INVALID_OBJECT_TYPE The streamObjectHandle does not refer to data containing the association tag. CLDSM_ERR_OBJECT_NOT_LOADED The streamObjectHandle does not refer to a loaded object. CLDSM_ERR_OBJECT_NOT_OPEN The streamObjectHandle does not refer to an open object. CLDSM_ERR_UNABLE_TO_GET_PROGRAM_ASSOC_TAG No BIOP_PROGRAM_USE tap could be found. CLDSM_OK Association Tag was successfully obtained.

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation