cldsmcc.h File Reference

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

Go to the source code of this file.

Classes
struct	s_UserInfo
struct	S_DsmSetup

Typedefs
typedef U8BIT	E_CacheRules
typedef struct s_DsmObject *	H_DsmObject
typedef struct s_ObjUserData *	H_ObjUserData
typedef struct s_UserInfo	S_UserInfo
typedef void(*	F_Error) (E_DscError err, void *args)
typedef void(*	F_Progress) (U32BIT prog, void *args)
typedef E_DscError(*	F_StartTimer) (H_DsmControl dsmControl, U32BIT timePeriod, void *clDsmTmrUserData, void **pTimerHandle)
typedef void(*	F_StopTimer) (H_DsmControl dsmControl, void *timerHandle)
typedef E_DscError(*	F_StartSIQuery) (H_SiqInstance siqInstance, P_SIQueryRequest pQuery, H_SIQueryRef clDsmSIQueryRef, void *clDsmSIUserData, P_SIQueryResult pResult)
typedef void(*	F_StopSIQuery) (H_SiqInstance siqInstance, void *queryHandle, H_SIQueryRef clDsmSIQueryRef)
typedef E_DscError(*	F_SubscribeSIChanged) (H_SiqInstance siqInstance, U16BIT service_id)
typedef void(*	F_UnsubscribeSIChanged) (H_SiqInstance siqInstance, U16BIT service_id)
typedef void *(*	F_AddSectionFilter) (H_SfmInstance sfm, P_SecFilter pFilter, H_DscSFRef dsmFilterRef)
typedef void(*	F_DelSectionFilter) (H_SfmInstance sfm, void *filterHandle, H_DscSFRef clDsmFilterRef)
typedef void(*	F_SFPriorityChanged) (H_SfmInstance sfm, void *filterHandle, H_DscSFRef clDsmFilterRef, E_SFPriority priority)
typedef void(*	F_NotifyCarouselLoadEvent) (H_DsmCarousel clDsmCarouselHandle, E_OCLoadStatus status, U32BIT carouselId)
typedef void(*	F_NotifyObjectLoadEvent) (H_DsmObject clDsmObjectHandle, E_ObjLoadStatus status, H_ObjUserData pCopyOfObjLoadUserData)
typedef void(*	F_NotifyStreamEvent) (H_DsmEvent eventHandle, E_StreamEventStatus status, S_UserInfo userInfo, 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 CDSM_StreamEventSubscribe() 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. More...
typedef void(*	F_NotifyDeferredService) (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. More...
typedef BOOLEAN(*	F_IsUserDataMatch) (H_ObjUserData pUserData1, H_ObjUserData pUserData2)
typedef struct S_DsmSetup *	P_DsmSetup

Enumerations
enum	E_TimerStatus { TIMER_TRIGGERED = 0, TIMER_ABORTED }
enum	E_DsmObjectKind {   ANON_OBJ = 0, FILE_OBJ, DIRECTORY_OBJ, SERVICE_GATEWAY_OBJ,   STREAM_OBJ, STREAM_OBJ_WITH_EVENTS, LINK_TO_ALTERNATE_OC_OBJ }
enum	E_ObjLoadStatus {   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, OBJ_LOAD_ABORTED_UNLOAD }

Functions
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_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. 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. 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 instance, 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. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: addSectionFilter stopSIQuery notifyObjectLoadEvent notifyCarouselLoadEvent deleteSectionFilter stopTimer. More...
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: More...
E_DscError	CDSM_SysProcessPrivateSection (H_DsmCoreInst instance, U8BIT *pSection, H_DscSFRef dsmFilterRef)
E_DscError	CDSM_SectionFilterPriority (H_DsmCoreInst instance, H_DscSFRef dsmFilterRef, E_SFPriority *pPriority)
E_DscError	CDSM_LoadCarousel (H_DsmCoreInst instance, U16BIT service_id, U32BIT carousel_id, E_SIQueryKind kind, H_DsmCarousel *pclDsmCarouselHandle)
	Request load of a DSM-CC Object Carousel (service domain).
E_DscError	CDSM_UnloadCarousel (H_DsmCoreInst instance, H_DsmCarousel 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 CDSM_CarouselHandle(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. More...
E_DscError	CDSM_UnloadModule (H_DsmCoreInst idp, H_DsmCarousel hCarousel, U32BIT moduleRef)
	Unload SSU module. To be called once the client has finished saving this module data. More...
E_DscError	CDSM_GetCarouselId (H_DsmCoreInst instance, H_DsmCarousel carouselHandle, U32BIT *pCarouselId)
	Retrieve Carousel Id for the loaded DSM-CC Object Carousel. More...
H_DsmCarousel	CDSM_CurrentCarousel (H_DsmCoreInst instance)
	Retrieve handle to the current carousel for DSM-CC Instance. More...
E_DscError	CDSM_SetCurrentCarousel (H_DsmCoreInst instance, H_DsmCarousel carouselHandle)
	Sets current carousel for DSM-CC Instance. More...
E_DscError	CDSM_CarouselLoadFileGroups (H_DsmCoreInst instance, H_DsmCarousel 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. More...
E_DscError	CDSM_CarouselUnloadFileGroups (H_DsmCoreInst instance, H_DsmCarousel clDsmCarouselHandle, S_CarouselInfoFileGroup *groups)
	Release "File Group Info" data allocated by used by CDSM_CarouselLoadFileGroups() More...
E_DscError	CDSM_LoadObject (H_DsmCoreInst instance, U8BIT *pathname, U32BIT timeout, E_CacheRules cachingRules, H_ObjUserData pUserData, U32BIT sizeOfUserData, E_ObjLoadStatus *pStatus, H_DsmObject *pclDsmObjectHandle)
E_DscError	CDSM_UnloadObject (H_DsmCoreInst instance, H_DsmObject 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 CDSM_ObjectHandle(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. More...
E_DscError	CDSM_UnloadMatchingObject (H_DsmCoreInst instance, F_IsUserDataMatch matchFunc, H_ObjUserData pUserData, E_DsmRstMode mode)
E_DscError	CDSM_OpenObject (H_DsmCoreInst instance, H_DsmObject clDsmObjectHandle, E_DsmObjectKind *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. More...
E_DscError	CDSM_CloseObject (H_DsmCoreInst instance, H_DsmObject clDsmObjectHandle)
H_DsmCoreInst	CDSM_ObjectGetInstance (H_DsmObject clDsmObjectHandle)
	Get DSM instance to which the object belongs. More...
E_DscError	CDSM_SetObjectCachingRules (H_DsmCoreInst instance, U8BIT *pathname, E_CacheRules cachingRules)
E_DscError	CDSM_PrefetchObject (H_DsmCoreInst instance, U8BIT *pathname, U32BIT timeout)
E_DscError	CDSM_StreamEventSubscribe (H_DsmCoreInst dsmccInstance, H_DsmObject streamObject, U8BIT *eventName, S_UserInfo *pUserInfo, 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 F_NotifyStreamEvent for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the CDSM_ObjectLoad() 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. More...
E_DscError	CDSM_StreamEventUnsubscribe (H_DsmCoreInst 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. More...
E_DscError	CDSM_SpecialEventSubscribe (H_DsmCoreInst dsmccInstance, U8BIT *name, U16BIT associationTag, U16BIT eventId, S_UserInfo *pUserInfo, 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. More...
E_DscError	CDSM_SpecialEventUnsubscribe (H_DsmCoreInst dsmccInstance, H_DsmEvent eventHandle)
	Same as clDsmStreamEventUnsubscribe - used in conjuction with clDsmSpecialEventSubscribe. More...
E_DscError	CDSM_StreamUnsubscribeEvent (H_DsmCoreInst idp, S_UserInfo *pUserInfo)
	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 streamEventHandle. More...
void	CDSM_StreamEventUnload (H_DsmCoreInst idp, U32BIT carouselId)
	This function is called by the Client to unload any stream event loaded from a stream object on the given carousel. Callback made to acknowledge unsubscribe. All data relating to this stream event will no longer be valid, including the streamEventHandle. More...
E_DscError	CDSM_ObjectGetKind (H_DsmObject clDsmObjectHandle, E_DsmObjectKind *pKind)
E_DscError	CDSM_ObjectGetCarouselHandle (H_DsmObject clDsmObjectHandle, void **hCarouselHandle)
E_DscError	CDSM_ObjectGetServiceContext (H_DsmObject 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. More...
E_DscError	CDSM_FileGetSize (H_DsmObject clDsmFileObjectHandle, U32BIT *pSize)
E_DscError	CDSM_FileRead (H_DsmObject clDsmFileObjectHandle, U32BIT numBytes, U8BIT *pDest, U32BIT *pNumBytesActual)
E_DscError	CDSM_FileDirect (H_DsmObject clDsmFileObjectHandle, U8BIT **ppDest, U32BIT *pNumBytesActual)
E_DscError	CDSM_FileReadByte (H_DsmObject clDsmFileObjectHandle, U8BIT *pDest)
E_DscError	CDSM_FileSetPosAbs (H_DsmObject clDsmFileObjectHandle, U32BIT absPosition)
E_DscError	CDSM_FileSetPosRel (H_DsmObject clDsmFileObjectHandle, S32BIT relPosition)
E_DscError	CDSM_FileGetPos (H_DsmObject clDsmFileObjectHandle, U32BIT *pPosition)
E_DscError	CDSM_DirEntrySizes (H_DsmObject dirObj, U16BIT *nameCount, U16BIT *totalNameLength)
E_DscError	CDSM_DirEntryFirst (H_DsmObject dirObj, void **pFirstEntry)
E_DscError	CDSM_DirEntryNext (void *entryHandle, void **pNextEntry)
U16BIT	CDSM_DirEntryNameLength (void *entryHandle)
U16BIT	CDSM_DirEntryNameCopy (void *entryHandle, U8BIT *pName)
E_DsmObjectKind	CDSM_DirEntryKind (void *entryHandle)
E_DscError	CDSM_StreamGetDeferredService (H_DsmCoreInst instance, H_DsmObject 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. More...
E_DscError	CDSM_StreamEventNameList (H_DsmCoreInst dsmccInstance, H_DsmObject 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 CDSM_ObjectLoad() 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. More...
E_DscError	CDSM_StreamEventXmlData (H_DsmCoreInst dsmccInstance, H_DsmObject streamObject, U8BIT **ppXmlData, U16BIT *pXmlLen)
	The Client uses this function to request data in XML format for stream object and associated events. This XML format is defined by 'TS 102 809' v 1.2.1, section 8.2 Before calling this function the Client must request that the stream object of interest be loaded using the CDSM_ObjectLoad() function. More...
U32BIT	CDSM_UtilCalculateCRC (U8BIT *msg, U32BIT len)

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(* F_NotifyDeferredService) (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(* F_NotifyStreamEvent) (H_DsmEvent eventHandle, E_StreamEventStatus status, S_UserInfo userInfo, 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 CDSM_StreamEventSubscribe() 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.
userInfo	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

E_DscError CDSM_CarouselLoadFileGroups	(	H_DsmCoreInst	instance,
		H_DsmCarousel	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

E_DscError CDSM_CarouselUnloadFileGroups	(	H_DsmCoreInst	instance,
		H_DsmCarousel	clDsmCarouselHandle,
		S_CarouselInfoFileGroup *	groups
	)

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

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.

H_DsmCarousel CDSM_CurrentCarousel

(

H_DsmCoreInst

instance

)

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

Parameters

instance

DSMCC instance handle

Returns

H_DsmCarousel - handle to current carousel

E_DscError CDSM_GetCarouselId	(	H_DsmCoreInst	instance,
		H_DsmCarousel	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

H_DsmCoreInst CDSM_ObjectGetInstance

(

H_DsmObject

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

E_DscError CDSM_ObjectGetServiceContext	(	H_DsmObject	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'

E_DscError CDSM_OpenObject	(	H_DsmCoreInst	instance,
		H_DsmObject	clDsmObjectHandle,
		E_DsmObjectKind *	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.

E_DscError CDSM_SetCurrentCarousel	(	H_DsmCoreInst	instance,
		H_DsmCarousel	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

E_DscError CDSM_SpecialEventSubscribe	(	H_DsmCoreInst	dsmccInstance,
		U8BIT *	name,
		U16BIT	associationTag,
		U16BIT	eventId,
		S_UserInfo *	pUserInfo,
		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.
name	Name of stream event (null terminated string - copy taken).
associationTag	Association tag used to retrieve PID that contains required stream events
eventId	Stream event ID required by the Client.
pUserInfo	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.
name	Name of stream event (null terminated string - copy taken).
associationTag	Association tag used to retrieve PID that contains required stream events
eventId	Stream event ID required by the Client.
pUserInfo	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_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.

E_DscError CDSM_SpecialEventUnsubscribe	(	H_DsmCoreInst	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

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 streamEventHandle is not valid. CLDSM_OK The stream event was successfully unsubscribed

E_DscError CDSM_StreamEventNameList	(	H_DsmCoreInst	dsmccInstance,
		H_DsmObject	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 CDSM_ObjectLoad() 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.

E_DscError CDSM_StreamEventSubscribe	(	H_DsmCoreInst	dsmccInstance,
		H_DsmObject	streamObject,
		U8BIT *	eventName,
		S_UserInfo *	pUserInfo,
		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 F_NotifyStreamEvent for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the CDSM_ObjectLoad() 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.
pUserInfo	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 F_NotifyStreamEvent for information about the callback function. Before calling this function the Client must request that the stream object of interest be loaded using the CDSM_ObjectLoad() 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.
pUserInfo	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.

void CDSM_StreamEventUnload	(	H_DsmCoreInst	idp,
		U32BIT	carouselId
	)

This function is called by the Client to unload any stream event loaded from a stream object on the given carousel. Callback made to acknowledge unsubscribe. All data relating to this stream event will no longer be valid, including the streamEventHandle.

Parameters

idp	instance of a DSMCC.
carouselId

E_DscError CDSM_StreamEventUnsubscribe	(	H_DsmCoreInst	idp,
		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

E_DscError CDSM_StreamEventXmlData	(	H_DsmCoreInst	dsmccInstance,
		H_DsmObject	streamObject,
		U8BIT **	pXmlData,
		U16BIT *	pXmlLen
	)

The Client uses this function to request data in XML format for stream object and associated events. This XML format is defined by 'TS 102 809' v 1.2.1, section 8.2 Before calling this function the Client must request that the stream object of interest be loaded using the CDSM_ObjectLoad() function.

Parameters

dsmccInstance	instance of DSMCC.
streamObject	handle to stream object
pXmlPtr	Pointer to XML data for Stream Object
pXmlLen	Length of XML data for Stream Object

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 - streamObject is not a BIOP::StreamEventMessage CLDSM_ERR_MEM_HEAP_FULL - Out of memory. CLDSM_OK - Successfully retrieved XML data for stream object.

E_DscError CDSM_StreamGetDeferredService	(	H_DsmCoreInst	instance,
		H_DsmObject	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.

E_DscError CDSM_StreamUnsubscribeEvent	(	H_DsmCoreInst	idp,
		S_UserInfo *	pUserInfo
	)

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

Parameters

dsmccInstance	Allows support of >= 1 instance of a DSMCC.
pUserInfo	Copy of User Info supplied to CDSM_StreamEventSubscribe or CDSM_SpecialEventSubscribe

Returns

CLDSM_ERR_INVALID_STREAM_EVENT_HANDLE The listener details not found. CLDSM_OK The stream event was successfully unsubscribed

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

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. 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 CDSM_SysSetMemoryMax	(	H_DsmCoreInst	instance,
		U32BIT	maxMemory
	)

Set maximum memory usage.

Parameters

instance

Returns

n/a

E_DscError CDSM_UnloadCarousel	(	H_DsmCoreInst	instance,
		H_DsmCarousel	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 CDSM_CarouselHandle(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.

E_DscError CDSM_UnloadModule	(	H_DsmCoreInst	idp,
		H_DsmCarousel	hCarousel,
		U32BIT	moduleRef
	)

Unload SSU module. To be called once the client has finished saving this module data.

Parameters

idp	DSMCC instance handle.
hCarousel	Handle to the DSMCC Update Carousel
moduleRef	Reference to a module

Returns

error type

Parameters

idp	DSMCC instance handle.
hCarousel	Handle to the DSMCC Update Carousel
downloadId	Download ID
moduleId	Module ID

Returns

error type

E_DscError CDSM_UnloadObject	(	H_DsmCoreInst	instance,
		H_DsmObject	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 CDSM_ObjectHandle(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.