DSM-CC API for client requests. More...

#include "fs_types.h"
#include "dsm_types.h"

Macros
#define	LOAD_FLAGS_DEFAULT 0x0000007F

#define	LOAD_FLAGS_CACHE_PRIORITY_MASK 0x000000FF

#define	LOAD_FLAGS_REQUEST_FROM_STREAM 0x00000000

#define	LOAD_FLAGS_REQUEST_FILE_ONLY_BIT 0x00000100

#define	LOAD_FLAGS_REQUEST_EXISTANCE_BIT 0x00000400

#define	LOAD_FLAGS_REQUEST_STREAM_OBJ_XML_BIT 0x00002000

#define	LOAD_FLAGS_REQUEST_DEFERRED_SERVICE_BIT 0x00004000

#define	LOAD_FLAGS_REQUEST_EVENT_LIST_BIT 0x00008000

#define	LOAD_FLAGS_REQUEST_DIR_FILE_LIST_BIT 0x00000000

#define	LOAD_FLAGS_REQUEST_DIRECTORY_LIST_BIT 0x00040000

#define	LOAD_FLAGS_REQUEST_SERVICE_CONTEXT_BIT 0x00080000

Typedefs
typedef F_FS_CALLBACK	F_DSM_CBLOAD

typedef void(*	F_DSM_EVENT) (void userData, U8BIT name, U32BIT dataLen, U8BIT *dataPtr)
	Callback function to notify that a DSM-CC stream event has triggered The event name is given, because DSMCC_ClientEventSubscribeName can subscribe to all events on a URL, and then this specifies which event occured. More...

typedef void(*	F_DSM_SE) (U_PARAM userData, E_StreamEventStatus status, U8BIT name, U32BIT dataLen, U8BIT dataPtr)
	Callback function to notify that a DSM-CC stream event has triggered The event name is given, because DSMCC_ClientEventRequest can subscribe to all events on a URL, and then this specifies which event occured. More...

typedef void(*	F_DSM_TYPE) (void *userData, E_DsmObjectType type)
	Callback function to notify client of result for request of object type. More...

Enumerations
enum	E_DsmObjectType { OBJECT_TYPE_UNKNOWN = 0x30, OBJECT_TYPE_FILE, OBJECT_TYPE_DIRECTORY, OBJECT_TYPE_ROOT_DIR, OBJECT_TYPE_STREAM, OBJECT_TYPE_STREAM_WITH_EVENTS }

Functions
E_FsStatus	DSMCC_ClientLoadObject (H_DsmControl dsmctrl, U8BIT path, U32BIT flags, F_DSM_CBLOAD cb_func, S_CONTENT pContent)
	Perform a file load request which is executed synchronously or asynchronously. See load flags above for modifying requests. More...

E_FsStatus	DSMCC_ClientObjectType (H_DsmControl dsmctrl, U8BIT path, F_DSM_TYPE cbfunc, void userData, E_DsmObjectType *pType)
	Request object type for given path. This may be executed synchronously or asynchronously - see comment for DSMCC_ClientLoadObject() More...

void	DSMCC_ClientPreloadHint (H_DsmControl dsmctrl, U8BIT *path)
	Provide a hint that the specified file may be required in the future. If possible this should be loaded into the DSM-CC cache. More...

E_FsStatus	DSMCC_ClientEventSubscribeName (H_DsmControl dsmctrl, FS_HANDLE streamObject, U8BIT eventName, F_DSM_EVENT cb_func, void userData, H_DsmEvent *pEventHandle)
	Client request to subscribe to DSMCC Stream Event, specified by name. DSMCC notifies when the named stream event occurs, by calling cb_func (a callback function defined by the Client). Before calling this function the Client must request that the stream object of interest be loaded using DSMCC_ClientLoadObject() 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. More...

E_FsStatus	DSMCC_ClientEventSubscribeId (H_DsmControl dsmctrl, U16BIT associationTag, U16BIT eventId, F_DSM_EVENT cb_func, void userData, H_DsmEvent pEventHandle)
	Client request to subscribe to DSMCC Stream Event, specified by event ID and association tag of stream object. DSMCC notifies when the stream event occurs, by calling cb_func (a callback function defined by the Client). More...

void	DSMCC_ClientEventUnsubscribe (H_DsmControl dsmctrl, H_DsmEvent event)
	Client request to UN-subscribe to DSMCC Stream Event. More...

E_FsStatus	DSMCC_ClientSubscribeEvents (H_DsmControl dsmctrl, U8BIT path, U8BIT eventName, F_DSM_SE cb_func, U_PARAM userData)
	Client request to subscribe to DSMCC Stream Event, specified by stream object given by 'path' and the event given by eventName. DSMCC notifies when the stream object has been resolved (or not) using the client callback function with which the event handle is returned. This handle should be given to DSMCC_ClientEventUnsubscribe when un-subscribing to this stream event. It also notifies with same callback when named stream event occurs. More...

E_FsStatus	DSMCC_ClientSubscribeEventId (H_DsmControl dsmctrl, U8BIT *name, U16BIT associationTag, U16BIT eventId, F_DSM_SE cb_func, U_PARAM userData)
	Client request to subscribe to DSMCC Stream Event, specified by event ID and association tag. The supplied event name is simply held and returned by DSM-CC in the callback function 'cf_func'. DSMCC notifies when the stream event occurs, by calling cb_func (a callback function defined by the Client). More...

void	DSMCC_ClientUnsubscribeEvent (H_DsmControl dsmctrl, F_DSM_SE cb_func, U_PARAM userData)
	Client request to UN-subscribe to DSMCC Stream Event. More...

void	DSMCC_StreamEventUnload (H_DsmControl dsmctrl, U32BIT carouselId)
	Unload any stream event that was loaded with a stream object on given carousel Any Client Callback will notified and unsubscribe. More...

BOOLEAN	DSMCC_ClientLoadFileGroups (H_DsmControl dsmctrl, H_ObjCarousel hOC, U16BIT total, S_CarouselInfoFileGroup *pGroups)
	Client request to retrieve MHEG5 File system acceleration file groups The client must release the array of group data, by calling DSMCC_ClientUnloadFileGroups, when finished with the data. More...

void	DSMCC_ClientUnloadFileGroups (H_DsmControl dsmctrl, H_ObjCarousel hOC, S_CarouselInfoFileGroup *groups)
	Client request to release file group data returned from DSMCC_ClientLoadFileGroups. More...

Detailed Description

DSM-CC API for client requests.

Date: 11/12/2013

Author: Adam Sturtridge

Typedef Documentation

typedef void(* F_DSM_EVENT) (void *userData, U8BIT *name, U32BIT dataLen, U8BIT *dataPtr)

Callback function to notify that a DSM-CC stream event has triggered The event name is given, because DSMCC_ClientEventSubscribeName can subscribe to all events on a URL, and then this specifies which event occured.

Parameters

userData	User data passed to DSMCC_ClientEventSubscribe...
name	Name of event (null terminated string)
dataLen	Length of event data
dataPtr	Pointer to event data (only valid in callback function)

typedef void(* F_DSM_SE) (U_PARAM userData, E_StreamEventStatus status, U8BIT *name, U32BIT dataLen, U8BIT *dataPtr)

Callback function to notify that a DSM-CC stream event has triggered The event name is given, because DSMCC_ClientEventRequest can subscribe to all events on a URL, and then this specifies which event occured.

Parameters

userData	User data passed to DSMCC_ClientSubscribeEvent...
status	status of event - i.e. triggered, or some error occured
name	Name of event (null terminated string)
dataLen	Length of event data (only non zero when triggerd)
dataPtr	Pointer to event data (only valid in callback function)

typedef void(* F_DSM_TYPE) (void *userData, E_DsmObjectType type)

Callback function to notify client of result for request of object type.

Parameters

userData	User data passed to DSMCC_ClientObjectType
type	Type of object - set to OBJECT_TYPE_UNKNOWN if an error occured

Function Documentation

E_FsStatus DSMCC_ClientEventSubscribeId	(	H_DsmControl	dsmctrl,
		U16BIT	associationTag,
		U16BIT	eventId,
		F_DSM_EVENT	cb_func,
		void *	userData,
		H_DsmEvent *	pEventHandle
	)

Client request to subscribe to DSMCC Stream Event, specified by event ID and association tag of stream object. DSMCC notifies when the stream event occurs, by calling cb_func (a callback function defined by the Client).

Parameters

dsmctrl	DSMCC Instance
associationTag	association tag.
evemntId	Id of stream event.
cb_func	Callback function for client.
userData	Optional data to be passed back to client. It is stored and returned unchanged.
pEventHandle	Handle to the stream event returned by subscribe. The caller may use this handle when calling DSMCC_ClientEventUnsubscribe

Returns: E_FsStatus FS_STATUS_OK The event has been successfully subscribed to.

E_FsStatus DSMCC_ClientEventSubscribeName	(	H_DsmControl	dsmctrl,
		FS_HANDLE	streamObject,
		U8BIT *	eventName,
		F_DSM_EVENT	cb_func,
		void *	userData,
		H_DsmEvent *	pEventHandle
	)

Client request to subscribe to DSMCC Stream Event, specified by name. DSMCC notifies when the named stream event occurs, by calling cb_func (a callback function defined by the Client). Before calling this function the Client must request that the stream object of interest be loaded using DSMCC_ClientLoadObject() 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.

Parameters

dsmctrl	DSMCC Instance
streamObject	DSMCCs file system handle
eventName	Name of required stream event. When NULL, any event on stream object
cb_func	Callback function for client.
userData	Optional data to be passed back to client. It is stored and returned unchanged.
pEventHandle	Handle to the stream event returned by subscribe. The caller may use this handle when calling DSMCC_ClientEventUnsubscribe

Returns: E_FsStatus FS_STATUS_OK The event has been successfully subscribed to.

void DSMCC_ClientEventUnsubscribe	(	H_DsmControl	dsmctrl,
		H_DsmEvent	eventHandle
	)

Client request to UN-subscribe to DSMCC Stream Event.

Parameters

dsmctrl	DSMCC Instance
event	Handle to previously subscribed event

Returns: void

BOOLEAN DSMCC_ClientLoadFileGroups	(	H_DsmControl	dsmctrl,
		H_ObjCarousel	hOC,
		U16BIT *	total,
		S_CarouselInfoFileGroup **	pGroups
	)

Client request to retrieve MHEG5 File system acceleration file groups The client must release the array of group data, by calling DSMCC_ClientUnloadFileGroups, when finished with the data.

Parameters

dsmctrl	DSMCC Instance
hOC	Handle to carousel
total	Pointer to return number of file groups in the carousel info
pGroups	Pointer to return an array of file group data.

Returns: BOOLEAN - TRUE if success

E_FsStatus DSMCC_ClientLoadObject	(	H_DsmControl	dsmctrl,
		U8BIT *	path,
		U32BIT	flags,
		F_DSM_CBLOAD	cb_func,
		S_CONTENT *	pContent
	)

Perform a file load request which is executed synchronously or asynchronously. See load flags above for modifying requests.

Synchronous behaviour: If DSM-CC is able to determine that the file does not exist, the function returns with the FS_STATUS_ERROR.

If DSM-CC has the requested file in cache, it can read the file contents and pass a pointer to it in the pFileData return parameter, along with the file length in the pFileSize returned parameter. Once the contents of the file has been used, resource allocated to it must be released by calling the dsmFDataAck function. The function return value will be set to FS_STATUS_OK.

Asynchronous behaviour: If DSM-CC does not have the file in cache it will perform an asynchronous load. This is indicated by returning FS_STATUS_PENDING. When the load is completed, the 'cb_func' is called

If the path parameter points to a stream object within the DSM-CC carousel this will be loaded. The referenced multiplex will be located and a reference to this will be passed back to the MHEG-5 engine.

Parameters

dsmctrl	DSMCC controling Instance
path	Path of Object (directory, file or stream)
flags	Load flags containing cache priority, and other control bits
cb_func	Call-back Function
pContent	Pointer to the file content details. Note: When content data for object is no longer required, the destroy function in S_CONTENT must be called to free any allocated resource.

Returns: E_FsStatus FS_STATUS_OK The Object has been sucessfully loaded

E_FsStatus DSMCC_ClientObjectType	(	H_DsmControl	dsmctrl,
		U8BIT *	path,
		F_DSM_TYPE	cbfunc,
		void *	userData,
		E_DsmObjectType *	pType
	)

Request object type for given path. This may be executed synchronously or asynchronously - see comment for DSMCC_ClientLoadObject()

Parameters

dsmctrl	DSMCC controling Instance
path	Path of Object (directory, file or stream)
cbfunc	Call-back Function
userData	User data to be passed back to client in callback function.
pType	Pointer to object type - return value is valid when FS_STATUS_OK.

Returns: E_FsStatus, FS_STATUS_OK - The Object has been sucessfully found

void DSMCC_ClientPreloadHint	(	H_DsmControl	dsmctrl,
		U8BIT *	path
	)

Provide a hint that the specified file may be required in the future. If possible this should be loaded into the DSM-CC cache.

Parameters

dsmctrl	DSMCC Instance
path	Path of Object (directory, file or stream)

Returns: void

E_FsStatus DSMCC_ClientSubscribeEventId	(	H_DsmControl	dsmctrl,
		U8BIT *	name,
		U16BIT	associationTag,
		U16BIT	eventId,
		F_DSM_SE	cb_func,
		U_PARAM	userData
	)

Client request to subscribe to DSMCC Stream Event, specified by event ID and association tag. The supplied event name is simply held and returned by DSM-CC in the callback function 'cf_func'. DSMCC notifies when the stream event occurs, by calling cb_func (a callback function defined by the Client).

Parameters

dsmctrl	DSMCC Instance
name	Name of stream event (null terminated string, copy returned to 'cb_func')
associationTag	association tag.
eventId	Id of stream event.
cb_func	Callback function for client.
userData	Optional data to be passed back to client. It is stored and returned unchanged.

Returns: E_FsStatus FS_STATUS_OK The event has been successfully subscribed to.

Parameters

dsmctrl	DSMCC Instance
name	Name of stream event (returned to 'cb_func').
associationTag	association tag.
eventId	Id of stream event.
cb_func	Callback function for client.
userData	Optional data to be passed back to client. It is stored and returned unchanged.

Returns: E_FsStatus FS_STATUS_OK The event has been successfully subscribed to.

E_FsStatus DSMCC_ClientSubscribeEvents	(	H_DsmControl	dsmctrl,
		U8BIT *	path,
		U8BIT *	eventName,
		F_DSM_SE	cb_func,
		U_PARAM	userData
	)

Client request to subscribe to DSMCC Stream Event, specified by stream object given by 'path' and the event given by eventName. DSMCC notifies when the stream object has been resolved (or not) using the client callback function with which the event handle is returned. This handle should be given to DSMCC_ClientEventUnsubscribe when un-subscribing to this stream event. It also notifies with same callback when named stream event occurs.

Parameters

dsmctrl	DSMCC Instance
path	Path of stream object describing stream events
eventName	Name of required stream event. When NULL, any event on stream object
cb_func	Client callback function to notify status events
userData	Unique data to be passed back to client. It is stored and returned unchanged.

Returns: E_FsStatus FS_STATUS_OK The stream event object has been successfully requested

Client request to subscribe to DSMCC Stream Event, specified by stream object given by 'path' and the event given by eventName. DSMCC notifies when the stream object has been resolved (or not) using the client callback function with which the event handle is returned. This handle should be given to DSMCC_ClientEventUnsubscribe when un-subscribing to this stream event. It also notifies with same callback when named stream event occurs.

Parameters

dsmctrl	DSMCC Instance
path	Path of stream object describing stream events
eventName	Name of required stream event. When NULL, any event on stream object
cb_func	Client callback function to notify status events
userData	Optional data to be passed back to client. It is stored and returned unchanged.

Returns: E_FsStatus FS_STATUS_OK The stream event object has been successfully requested

void DSMCC_ClientUnloadFileGroups	(	H_DsmControl	dsmctrl,
		H_ObjCarousel	hOC,
		S_CarouselInfoFileGroup *	groups
	)

Client request to release file group data returned from DSMCC_ClientLoadFileGroups.

Parameters

dsmctrl	DSMCC Instance
hOC	Handle to carousel
groups	Array of file group data.

Returns: void

void DSMCC_ClientUnsubscribeEvent	(	H_DsmControl	dsmctrl,
		F_DSM_SE	cb_func,
		U_PARAM	userData
	)

Client request to UN-subscribe to DSMCC Stream Event.

Parameters

dsmctrl	DSMCC Instance
cb_func	Callback function for client.
userData	Client's unique user data - same as provided to DSMCC_ClientSubscribeEvent... function

Returns: void

Parameters

dsmctrl	DSMCC Instance
event	Handle to previously subscribed event

Returns: void

void DSMCC_StreamEventUnload	(	H_DsmControl	dsmctrl,
		U32BIT	carouselId
	)

Unload any stream event that was loaded with a stream object on given carousel Any Client Callback will notified and unsubscribe.

Parameters

dsmctrl	DSMCC Instance
carouselId

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation