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 "loadMgr.h"
#include "sectionFilter.h"
#include "siQuery.h"
#include "clDsmUtils.h"

Data Structures
struct	S_CarouselLocator
Defines
#define	PATH_SEPARATOR_LIST_STRING "\\/:" /* -- Recognised path seperators */
Functions
clDsmErr_t	clDsmLoadCarousel (clDsmInstHandle_t instance, U16BIT service_id, U32BIT carousel_id, U32BIT timeout, E_OCLoadStatus pStatus, clDsmOCHandle_t pclDsmCarouselHandle)
clDsmErr_t	clDsmGetCarouselId (clDsmInstHandle_t instance, clDsmOCHandle_t hCarousel, 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 idp, clDsmOCHandle_t hCarousel)
	Sets current carousel for DSM-CC Instance.
clDsmErr_t	clDsmCarouselLoadFileGroups (clDsmInstHandle_t instance, clDsmOCHandle_t 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.
clDsmErr_t	clDsmCarouselUnloadFileGroups (clDsmInstHandle_t instance, clDsmOCHandle_t hCarousel, S_CarouselInfoFileGroup *groups)
	Release "File Group Info" data allocated by used by clDsmCarouselLoadFileGroups()
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	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. The object MUST be one of the following types: . Stream Object . Stream Object with Events . File Object . Service Gateway Object.
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	dsmObjectGetKind (clDsmObjHandle_t object, clDsmObjectKind_t *pKind)
clDsmErr_t	dsmObjectGetCarouselHandle (clDsmObjHandle_t object, 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.

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

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

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

Data Structures

Defines

Functions

Detailed Description

Function Documentation