mh5fileorm.c File Reference

File based synchronous/asynchrounous ORM. More...

#include "mh5fileorm.h"
#include "mh5stream.h"
#include "mh5memory.h"
#include "mh5debug.h"
#include "mh5profile.h"
#include "mh5object.h"
#include "mh5queue.h"
#include "mh5gate.h"
#include "mh5misc.h"
#include "mh5control.h"
#include <string.h>
#include "dvb_ci.h"
#include "glue_queue.h"
#include "glue_main.h"
#include "glue_timers.h"
#include "glue_dsmcc.h"

Data Structures
struct	CiMessageContext_struct
struct	sOrmRequest
struct	sOrmGetRequest
struct	sOrmPostRequest
struct	sOrmCiMessageRequest

Macros
#define	MAX_PATHNAME_LENGTH   (1024)
#define	MAX_CI_REQUESTS   (1)
#define	CI_ACK_TIMEOUT   9999 /* about 10 secs */
#define	MIN_HTTP_REPLY_BLOCK   (128)
#define	MAX_REDIRECTS   (5)
#define	DEFAULT_ORIGIN   ORIGIN_DSM
#define	GET_REQUEST_MASK   (ORM_TYPE_DSM_GET | ORM_TYPE_CI_GET)
#define	EXISTS_REQUEST_MASK   (ORM_TYPE_DSM_EXISTS | ORM_TYPE_CI_EXISTS)
#define	IS_HTTP_REQUEST(r)   (((r)->type) & HTTP_REQUEST_MASK)
#define	IS_POST_REQUEST(r)   (((r)->type) & POST_REQUEST_MASK)
#define	IS_GET_REQUEST(r)   (((r)->type) & GET_REQUEST_MASK)
#define	IS_EXISTS_REQUEST(r)   (((r)->type) & EXISTS_REQUEST_MASK)
#define	IS_HTTPS_REQUEST(r)   (((r)->type) & HTTPS_REQUEST_MASK)
#define	IS_HYBRID_REQUSET(r)   (((r)->type) & HYBRID_REQUEST_MASK)
#define	CHECK_ORM_MAGIC
#define	ORM_REQUEST_MAGIC   0xdeadbeef
#define	ORM_REQUEST_BAD_MAGIC   0xfeedface
#define	SET_ORM_MAGIC(r)   (r)->magic = ORM_REQUEST_MAGIC
#define	CLEAR_ORM_MAGIC(r)   (r)->magic = ORM_REQUEST_BAD_MAGIC
#define	VERIFY_ORM_MAGIC(r)   assert((r)->magic == ORM_REQUEST_MAGIC)
#define	ORM_DBG_CODE(c)
#define	MH5FILEORM_DEBUG
#define	PRINT(x)
#define	PRINT_ERROR(x)
#define	ORM_STATE_STRING(r)
#define	PRINTFILE(t, n, d, s)

Typedefs
typedef struct CiMessageContext_struct	CiMessageContext
typedef void(*	PostCallback )(void *userData, MHEG5String responseData, MHEG5Int responseCode)
typedef struct sOrmRequest	OrmRequest
typedef struct sOrmGetRequest	OrmGetRequest
typedef struct sOrmPostRequest	OrmPostRequest
typedef struct sOrmCiMessageRequest	OrmCiMessageRequest
typedef OrmRequest *(*	OrmGetRequestCreate )(MHEG5String, U8BIT *, U16BIT, F_CB_Good, F_CB_Fail, void *)

Enumerations
enum	FileOrigin {   ORIGIN_DSM, ORIGIN_CI, ORIGIN_DVB, ORIGIN_REC,   ORIGIN_ERROR }
enum	OrmRetcode { ORM_PENDING, ORM_FOUND, ORM_ERROR }
enum	OrmState {   ORM_STATE_START, ORM_STATE_QUEUED, ORM_STATE_WAIT_ACCESS, ORM_STATE_CHECK_ACCESS,   ORM_STATE_HAS_ACCESS, ORM_STATE_WAIT_CERT, ORM_STATE_HAS_CERT, ORM_STATE_REQUESTED,   ORM_STATE_WAIT_VERIFY, ORM_STATE_CHECK_VERIFY, ORM_STATE_SUCCEEDED, ORM_STATE_FAILED,   ORM_STATE_ABORTED }
enum	OrmType {   ORM_TYPE_DSM_GET = 0x0001, ORM_TYPE_DSM_EXISTS = 0x0002, ORM_TYPE_CI_GET = 0x0004, ORM_TYPE_CI_EXISTS = 0x0008,   ORM_TYPE_DVB_RESOLVE = 0x0010, ORM_TYPE_CI_MESSAGE = 0x2000 }
enum	OrmRequestType { ORM_EXISTS, ORM_GET, ORM_POST }

Functions
void	MHEG5FileOrmInit (void)
	Initialise the file ORM module. More...
void	MHEG5FileOrmReset (MHEG5FileOrmResetMode resetMode)
	Reset the ORM module. This function supports two modes: More...
BOOLEAN	MHEG5FileOrmIsReset (MHEG5FileOrmResetMode *resetMode)
	Tell whether the ORM module is currently being reset. If it is, the function also returns the current reset mode. This information is required in order to decide whether to generate an EngineEvent when a file load fails. If a file cannot be loaded (doesn't exist, timeout) then an event is required, but if a file load "fails" because the ORM module is being reset, then no event should be generated. resetMode is an optional parameter, and it can also be NULL. More...
BOOLEAN	MHEG5FileOrmProcess (void)
	Check for any file requests that have arrived since this function was last called. For each arrived file the callback will be called. The function may have to be called more than once in case a file the arrived affects other files as well. More...
void	MHEG5FileOrmClear (void *orm_ref)
	Remove outstanding file request for the given handle. More...
void *	MHEG5FileOrmGet (MHEG5String name, U16BIT priority, void *userData, F_CB_Good callback, F_CB_Fail failCallback)
	Initiate retrieval of a file. The file will be loaded and the callback function called when it is available. More...
void	MHEG5FileOrmPreloadHint (MHEG5String name)
	Provide a preload hint to DSM-CC that the specified file may be required in the future. DSM-CC could (but is not required to) acquire the file into cache. More...
void	MHEG5ciSetModuleId (U32BIT module_id)
void	MHEG5ciFileAcknowledge (BOOLEAN fileOK, U8BIT *pFileData, U32BIT length)
	Process the FileAcknowledge message sent from the CI module. More...

Detailed Description

File based synchronous/asynchrounous ORM.

Date

01/02/2002

Author

R.Freeman

Macro Definition Documentation

#define CHECK_ORM_MAGIC

#define CI_ACK_TIMEOUT   9999 /* about 10 secs */

#define CLEAR_ORM_MAGIC

(

r

)

(r)->magic = ORM_REQUEST_BAD_MAGIC

#define DEFAULT_ORIGIN   ORIGIN_DSM

#define EXISTS_REQUEST_MASK   (ORM_TYPE_DSM_EXISTS | ORM_TYPE_CI_EXISTS)

#define GET_REQUEST_MASK   (ORM_TYPE_DSM_GET | ORM_TYPE_CI_GET)

#define IS_EXISTS_REQUEST

(

r

)

(((r)->type) & EXISTS_REQUEST_MASK)

#define IS_GET_REQUEST

(

r

)

(((r)->type) & GET_REQUEST_MASK)

#define IS_HTTP_REQUEST

(

r

)

(((r)->type) & HTTP_REQUEST_MASK)

#define IS_HTTPS_REQUEST

(

r

)

(((r)->type) & HTTPS_REQUEST_MASK)

#define IS_HYBRID_REQUSET

(

r

)

(((r)->type) & HYBRID_REQUEST_MASK)

#define IS_POST_REQUEST

(

r

)

(((r)->type) & POST_REQUEST_MASK)

#define MAX_CI_REQUESTS   (1)

#define MAX_PATHNAME_LENGTH   (1024)

#define MAX_REDIRECTS   (5)

#define MH5FILEORM_DEBUG

#define MIN_HTTP_REPLY_BLOCK   (128)

#define ORM_DBG_CODE

(

c

)

#define ORM_REQUEST_BAD_MAGIC   0xfeedface

#define ORM_REQUEST_MAGIC   0xdeadbeef

#define ORM_STATE_STRING

(

r

)

Value:

((r)->state == ORM_STATE_START ? "ORM_STATE_START" :                 \
    (r)->state == ORM_STATE_QUEUED ? "ORM_STATE_QUEUED" :               \
    (r)->state == ORM_STATE_WAIT_ACCESS ? "ORM_STATE_WAIT_ACCESS" :     \
    (r)->state == ORM_STATE_CHECK_ACCESS ? "ORM_STATE_WAIT_ACCESS" :    \
    (r)->state == ORM_STATE_HAS_ACCESS ? "ORM_STATE_HAS_ACCESS" :       \
    (r)->state == ORM_STATE_WAIT_CERT ? "ORM_STATE_WAIT_CERT" :         \
    (r)->state == ORM_STATE_HAS_CERT ? "ORM_STATE_HAS_CERT" :           \
    (r)->state == ORM_STATE_REQUESTED ? "ORM_STATE_REQUESTED" :         \
    (r)->state == ORM_STATE_WAIT_VERIFY ? "ORM_STATE_WAIT_VERIFY" :     \
    (r)->state == ORM_STATE_CHECK_VERIFY ? "ORM_STATE_CHECK_VERIFY" :   \
    (r)->state == ORM_STATE_SUCCEEDED ? "ORM_STATE_SUCCEEDED" :         \
    (r)->state == ORM_STATE_FAILED ? "ORM_STATE_FAILED" :               \
    (r)->state == ORM_STATE_ABORTED ? "ORM_STATE_ABORTED" :             \
    "UNKNOWN")

#define PRINT

(

x

)

#define PRINT_ERROR

(

x

)

#define PRINTFILE	(		t,
			n,
			d,
			s
	)

#define SET_ORM_MAGIC

(

r

)

(r)->magic = ORM_REQUEST_MAGIC

#define VERIFY_ORM_MAGIC

(

r

)

assert((r)->magic == ORM_REQUEST_MAGIC)

Typedef Documentation

typedef struct CiMessageContext_struct CiMessageContext

typedef struct sOrmCiMessageRequest OrmCiMessageRequest

typedef struct sOrmGetRequest OrmGetRequest

typedef OrmRequest*(* OrmGetRequestCreate)(MHEG5String, U8BIT *, U16BIT, F_CB_Good, F_CB_Fail, void *)

typedef struct sOrmPostRequest OrmPostRequest

typedef struct sOrmRequest OrmRequest

typedef void(* PostCallback)(void *userData, MHEG5String responseData, MHEG5Int responseCode)

Enumeration Type Documentation

enum FileOrigin

Enumerator
ORIGIN_DSM
ORIGIN_CI
ORIGIN_DVB
ORIGIN_REC
ORIGIN_ERROR

enum OrmRequestType

Enumerator
ORM_EXISTS
ORM_GET
ORM_POST

enum OrmRetcode

Enumerator
ORM_PENDING
ORM_FOUND
ORM_ERROR

enum OrmState

Enumerator
ORM_STATE_START
ORM_STATE_QUEUED
ORM_STATE_WAIT_ACCESS
ORM_STATE_CHECK_ACCESS
ORM_STATE_HAS_ACCESS
ORM_STATE_WAIT_CERT
ORM_STATE_HAS_CERT
ORM_STATE_REQUESTED
ORM_STATE_WAIT_VERIFY
ORM_STATE_CHECK_VERIFY
ORM_STATE_SUCCEEDED
ORM_STATE_FAILED
ORM_STATE_ABORTED

enum OrmType

Enumerator
ORM_TYPE_DSM_GET
ORM_TYPE_DSM_EXISTS
ORM_TYPE_CI_GET
ORM_TYPE_CI_EXISTS
ORM_TYPE_DVB_RESOLVE
ORM_TYPE_CI_MESSAGE

Function Documentation

void MHEG5ciFileAcknowledge	(	BOOLEAN	fileOK,
		U8BIT *	pFileData,
		U32BIT	length
	)

Process the FileAcknowledge message sent from the CI module.

Parameters

fileOK	FileOK field of the FileAcknowledge message
pFileData	Pointer to file data in the FileAcknowledge message
length	Number of bytes in the file data

Returns

void

void MHEG5ciSetModuleId

(

U32BIT

module_id

)

void MHEG5FileOrmClear

(

void *

orm_ref

)

Remove outstanding file request for the given handle.

Aborts a request for file.

Parameters

orm_ref

Handle given back by MHEG5FileOrmGet

Returns

None.

void* MHEG5FileOrmGet	(	MHEG5String	name,
		U16BIT	priority,
		void *	userData,
		F_CB_Good	callback,
		F_CB_Fail	failCallback
	)

Initiate retrieval of a file. The file will be loaded and the callback function called when it is available.

Parameters

name	Name of file to retrieve. This will be expanded using the rules specified by the UK1 profile.
cachePriority	Cache priority with which to fetch the object.
callback	Pointer to callback function that will be called when the file is retreived. The callback function is passed a pointer to the file content data, the group id and id of the object, the file size in bytes and the object carousel.
failCallback	Pointer to callback function that will be called when the file cannot be retrieved. The callback function is passed the group id and id of the object.

Returns

void* - the FileOrm request handle

void MHEG5FileOrmInit

(

void

)

Initialise the file ORM module.

Returns

always returns 1

BOOLEAN MHEG5FileOrmIsReset

(

MHEG5FileOrmResetMode *

resetMode

)

Tell whether the ORM module is currently being reset. If it is, the function also returns the current reset mode. This information is required in order to decide whether to generate an EngineEvent when a file load fails. If a file cannot be loaded (doesn't exist, timeout) then an event is required, but if a file load "fails" because the ORM module is being reset, then no event should be generated. resetMode is an optional parameter, and it can also be NULL.

Parameters

resetMode

Reset mode (if return value is TRUE)

Returns

TRUE if the ORM module is being reset, FALSE otherwise

void MHEG5FileOrmPreloadHint

(

MHEG5String

name

)

Provide a preload hint to DSM-CC that the specified file may be required in the future. DSM-CC could (but is not required to) acquire the file into cache.

Parameters

name	Name of file to preload

Returns

void

BOOLEAN MHEG5FileOrmProcess

(

void

)

Check for any file requests that have arrived since this function was last called. For each arrived file the callback will be called. The function may have to be called more than once in case a file the arrived affects other files as well.

Returns

TRUE if the function should be called again, FALSE otherwise

void MHEG5FileOrmReset

(

MHEG5FileOrmResetMode

resetMode

)

Reset the ORM module. This function supports two modes:

• In "objects" mode, only outstanding file requests that are related to MHEG-5 objects are cancelled.
• In "all" mode, every outstanding file request is cleared. This includes file requests to certificates and access files.

  Parameters

  resetMode

  Reset mode

  Returns

  None.