source/dsmain/src/dsm_client.c File Reference

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

#include <string.h>
#include "stb_os.h"
#include "cldsmcc.h"
#include "fs_types.h"
#include "dsm_client.h"
#include "dm_debug.h"
#include "dsm_main.h"

Data Structures
struct	s_DsmControl
struct	s_DsmRefs
struct	s_ObjUserData
Typedefs
typedef struct s_DsmControl	S_DsmControl
typedef struct s_DsmRefs	S_DsmRefs
typedef struct s_ObjUserData	S_ObjUserData
Functions
void	DsmccObjectLoadEventFunc (clDsmObjHandle_t objectHandle, clDsmObjLoadStatus_t status, H_ObjUserData pUserData)
	Callback function provided to DSM-CC library. Object load events are passed to this callback by the DSM-CC library.
void	DsmccStreamEventFunc (H_DsmEvent eventHandle, clDsmSENotifyStatus_t status, void *userData1, void *userData2, U8BIT *namePtr, U8BIT *dataPtr, U8BIT nameLen, U8BIT dataLen)
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.
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.
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.
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).
void	DSMCC_ClientEventUnsubscribe (H_DsmControl dsmctrl, H_DsmEvent eventHandle)
	Client request to UN-subscribe to DSMCC Stream Event.
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.
void	DSMCC_ClientUnloadFileGroups (H_DsmControl dsmctrl, H_ObjCarousel hOC, S_CarouselInfoFileGroup *groups)
	Client request to release file group data returned from DSMCC_ClientLoadFileGroups.

---

Detailed Description

API functions for DSM-CC client requests.

Date:

01/12/2004

Author:

Ocean Blue

---

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 funcrtion 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 stream event required by the Client.
cb_func	Callback funcrtion 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

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

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 DsmccObjectLoadEventFunc	(	clDsmObjHandle_t	objectHandle,
		clDsmObjLoadStatus_t	status,
		H_ObjUserData	pUserData
	)

Callback function provided to DSM-CC library. Object load events are passed to this callback by the DSM-CC library.

Parameters:

objectHandle	Handle to the object (returned by clDsmLoadObject)
status	Status of the load request for the specified object.
engineLoadRef	Reference from MHEG5 engine
objLoadUserData2	DsmCmd_t cammand value (passing in as void*)

Returns:

void