Synchronous Client API functions and general purpose asynchronous client API functions (for DSM object access) More...

#include <string.h>
#include "clDsmSystem.h"
#include "dsmObject.h"
#include "module.h"
#include "dataCarousel.h"
#include "objectCarousel.h"
#include "updateCarousel.h"
#include "loadMgr.h"
#include "sectionFilter.h"
#include "siQuery.h"
#include "clDsmUtils.h"
#include "moduleData.h"

Classes
struct	S_CarouselLocator

Macros
#define	PATH_SEPARATOR_LIST_STRING "\\/:" /* -- Recognised path seperators */

Functions
E_DscError	CDSM_LoadCarousel (H_DsmCoreInst instance, U16BIT serviceId, U32BIT couId, E_SIQueryKind kind, H_DsmCarousel *pclDsmCarouselHandle)
	Request load of a DSM-CC Object Carousel (service domain).

E_DscError	CDSM_GetCarouselId (H_DsmCoreInst instance, H_DsmCarousel hCarousel, 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 idp, H_DsmCarousel hCarousel)
	Sets current carousel for DSM-CC Instance. More...

E_DscError	CDSM_CarouselLoadFileGroups (H_DsmCoreInst instance, H_DsmCarousel hCarousel, 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 hCarousel, S_CarouselInfoFileGroup *groups)
	Release "File Group Info" data allocated by used by CDSM_CarouselLoadFileGroups() More...

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_LoadObject (H_DsmCoreInst idp, 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_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. The object MUST be one of the following types: . Stream Object . Stream Object with Events . File Object . Service Gateway Object. 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_ObjectGetKind (H_DsmObject object, E_DsmObjectKind *pKind)

E_DscError	CDSM_ObjectGetCarouselHandle (H_DsmObject object, 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...

Detailed Description

Synchronous Client API functions and general purpose asynchronous client API functions (for DSM object access)

Date: 7/2/2002

Author: N Kirkland

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. The object MUST be one of the following types: . Stream Object . Stream Object with Events . File Object . Service Gateway Object.

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

Classes

Macros

Functions

Detailed Description

Function Documentation