cldsmcc.h

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2004 Ocean Blue Software Ltd
 * Copyright © 2000 Koninklijke Philips Electronics N.V
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 * 
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 * 
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
/*
 * DVB DSM-CC Object Carousel Core Layer API
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * 
 * OVERVIEW:
 * 
 * This API has been specified in standard ANSI C and is designed as a completely
 * OS and Platform (ie. HW and SW driver) independent interface to the core
 * DSM-CC layer.
 * 
 * To avoid confusion over the sizes of standard C types on different platforms, it
 * assumes that a standard set of unambiguous type names have been defined to
 * platform specific types in the file clDsmPlatformAPI.h (also standard
 * definitions for TRUE/FALSE/Null). NB. This currently matches the recommended DVP
 * coding standards.
 * 
 * 
 * DSM-CC code conforming to this API should be readily portable to any platform
 * and OS environment. It assumes that this environment (designated 'the
 * calling environment') can provide the following:
 * 
 * - Filtering of MPEG2 private sections from a single transport stream on multiple
 * simultaneous PID values and section filter values.
 * 
 * - Acquisition and parsing of PMT(s) for specified program stream, query/lookup
 *       of specific information from the SI data
 * 
 * - Basic block memory allocation and de-allocation (at startup and shutdown)
 * 
 * - Semaphore or queuing mechanisms for synchronising API calls initiated by
 * asynchronously running tasks or threads
 * 
 * - Queuing mechanisms, eg. for notifying clients of asynchronous object loads
 * 
 * - Multiple timers (eg. 10mS resolution)
 * 
 * - Dynamic (heap) memory management that conforms to the API specified in
 * clDsmMemMgrApi.h
 * 
 * NB. A non-fragmenting linked-block based memory manager that conforms to this
 * API is supplied along with the DSM-CC core stack (clDsmMemMgrBlock.c).
 * 
 * 
 * It is intended that all platform (and DSM-CC profile) specific functions
 * including handling of multiple clients/apps (if required) are implemented in
 * wrapper layers that call into this API. Only these layers should need to
 * be modified when porting to a new platform (or DSM-CC profile).
 * 
 * 
 * BASIC DATA FLOW AND LAYERS:
 *
 *          +-----------+                     +-----load/unload-----------------+
 *          |  DEMUX &  |   DSM-CC            |      carousel                   |
 *     TS-->|  section  |---private------+    |                                 |
 *          |  filters  |   sections     |    |    +--subscribe/unsubscribe--+  |
 *          +-----------+                |    |    |    for stream event     |  |
 *                A                      |    |    |                         |  |
 *                |                      |    |    |      load/unload +---------------+
 *                +---add/delete-----+   |    |    |    +-open/close--|    CLIENT(s)  |
 *                  section filter   |   |    |    |    |   object    +---------------+
 *                                   |   |    |    |    |               A    A      A
 *                +---SI Query--+    |   |    |    |    |               |    |      |
 *                |     result  |    |   V    V    V    V               |    |      |
 *         +----------------+   |  +------------------------+           |    |      |
 *     SI->|  SI (PAT/PMT)  |   +->|                        |  object/  |    |      |
 *         |    database    |      |                        |--carousel-+    |      |
 *         +----------------+  +---|                        |  loaded        |      |
 *                A            |   |                        |                |      |
 *                |            |   |   Platform & Profile   |--stream event--+      |
 *                +--SI Query--+   | (eg.MHEG/MHP) specific |                       |
 *                                 |   'porting' layer(s)   |    +-object data/info-+
 *                    +--Trigger-->|                        |    |
 *      +----------+  |            |                        |    |
 *      |  Timers  |--+      +-----|                        |    |
 *      +----------+         |     |------synchronous-------+-asynchronous-+
 *           A               |     |==============(clDsmAPI)===============|
 *           |               |     |                                       |
 *           +---start/stop--+     |                                       |
 *                                 |                DSM-CC                 |
 *                                 |            CORE (IP) LAYER            |
 *                                 |                                       |
 *                                 |                                       |
 *                                 |                                       |
 *                                 +-------------------/\------------------+
 *                                            +--------\/--------+
 *                                            | DSMCC DATA CACHE |
 *                                            +------------------+
 * 
 * 
 * --------------------------------------------------------------------------------
 */
#ifndef _DSMCC_H_
#define _DSMCC_H_

/*---includes for this file--------------------------------------------------*/
#include "cldsmtypes.h"

#ifdef __cplusplus
extern "C" {
#endif


/*---Constant and macro definitions for public use---------------------------*/

#define NUM_OPEN_DSM_OBJECTS_MAX    128

#define DSMCC_MINIMUM_CACHE_SIZE    (1024 * 1024 * 1)
#define DSMCC_DEFAULT_CACHE_SIZE    (1024 * 1024 * 6)

/* -- caching priority rules */
#define CACHE_RULES_DEFAULT         0x003F
#define CACHE_RULES_FROM_STREAM     (0)
#define CACHE_RULES_STATIC          0x0080
#define CACHE_RULES_EXISTS          0x0400

/* -- Progress codes */
#define CLDSM_PROG_CURR_SERVICE_CACHE_FULL  0
/* + ? */


/*---Enumerations for public use---------------------------------------------*/

/*---Global type defs for public use-----------------------------------------*/


/*
-- **** TIMER EVENT TYPES ***
*/

typedef struct _clDsmTimerRef_struct* clDsmTimerRef_t;

/* -- Timer event status -- */
typedef enum {
    TIMER_TRIGGERED = 0,
    TIMER_ABORTED
} clDsmTimerEventStatus_t, *pclDsmTimerEventStatus_t;


/*
-- **** CAROUSEL TYPES ***
*/

typedef struct s_ObjCarousel* clDsmOCHandle_t;


/*
-- **** OBJECT DATA TYPES ***
*/

typedef struct _clDsmObjectHandle_struct*       clDsmObjHandle_t;

/* -- Object kind -- */
typedef enum {
    ANON_OBJ = 0,
    FILE_OBJ,
    DIRECTORY_OBJ,
    SERVICE_GATEWAY_OBJ,
    STREAM_OBJ,
    STREAM_OBJ_WITH_EVENTS,
    LINK_TO_ALTERNATE_OC_OBJ
} clDsmObjectKind_t, *pclDsmObjectKind_t;


/*
-- Status type for object load
*/
typedef enum {
    /*0*/ OBJ_LOAD_UNINITIATED = 0,
    /*1*/ OBJ_LOAD_IN_PROGRESS,
    /*2*/ OBJ_LOAD_COMPLETED,
    /*3*/ OBJ_LOAD_ABORTED_TIMEOUT,
    /*4*/ OBJ_LOAD_ABORTED_PATH_ERROR,
    /*5*/ OBJ_LOAD_ABORTED_ERROR,
#ifdef DSM_MHP_PROFILE
    /*6*/ OBJ_LOAD_ABORTED_UNLOAD,
    /* -- NOT CURRENTLY IMPLEMENTED */
    /*7*/ OBJ_LOAD_PARENT_DIR_LOADED
#else
    /*6*/ OBJ_LOAD_ABORTED_UNLOAD
#endif
} clDsmObjLoadStatus_t, *pclDsmObjLoadStatus_t;


typedef struct s_ObjUserData *H_ObjUserData;

/*
-- **** STREAM EVENT DATA TYPES ****
*/

typedef struct _clDsmStreamEventHandle_struct*  clDsmStreamEventHandle_t;

/*
 This is the current status of the notification of a Stream Event.
*/
typedef enum
{
   SEN_INITIAL,
   SEN_NOTIFIED,
   SEN_ABORTED_OBJ_LOAD_FAILED,
   SEN_ABORTED_SUBSCRIBE_FAILED,
   SEN_TRIGGERED,
   SEN_ACKNOWLEDGE_UNSUBSCRIBE
} clDsmSENotifyStatus_t;


/* --------------- REQUIRED API - CALLBACK TYPE DEFINITIONS ----------------- */

/*
-- NOTES:
--
-- The calling environment must provide functions that match these callback
-- type definitions (except clDsmProgressFunc_t which is optional). All
-- required callbacks should be non-blocking. The callback addresses are
-- supplied to the DSM-CC instance at instance create/setup.
--
-- The callbacks are not expected to fail except under exception conditions.
--
-- For callbacks with 'int' return values, this should be used to indicate:
--      zero:     Successful execution/registration of call with calling env.
--      non-zero: Failure to execute/register call (eg. due to memory failure)
--
-- The DSMCC library will attempt to take some logical actions in response to a
-- failure of a start/add callback that may enable it to continue.(eg. abandon
-- request and notify client of a load failure due to system error).
--
-- The stop/delete callbacks are not provided with return values since there is
-- no meaningful action the DSM-CC library can take in response to these
-- failing. If it is possible that these callbacks fail to execute the
-- requested action then the internal state of the DSM-CC library will become
-- inconsistent with the calling environment. The calling environment must
-- handle this situatation - eg. by raising an exception and processing it when
-- the DSM-CC API call that triggered it completes. The calling environment
-- should deal with the problem before making any further DSM-CC API calls
-- (except clDsmSysReset or clDsmSysDestroy). It should either ensure that the
-- action requested by the callback is successfully executed or clear the problem
-- and reset/restart the DSM-CC library.
--
*/


/* -- INSTANCE MEMORY CALLBACKS -- */

/*******************************************************************************
* Memory allocate callback function (supplied at setup/clDsmSysCreate)
*
* NOTES:
* This will be called from clDsmSysCreate to allocate the memory for the instance
* 'static' variables (according to the setup parameters supplied by the calling
* environment).
*
* It is mostly called to allocate memory for caching DSM-CC data.
*
* In some extreme circumstances it may be called to allocate some additional
* instance memory for section filtering. This will only happen when/if the number
* of simultaneous section filters required exceeds the pre-allocated number.
* Any additional instance memory will not freed until the instance is destroyed
*
* RETURNS: pointer to start of allocated memory block, Null = FAILURE
*
*******************************************************************************/
typedef void* (*clDsmAllocFunc_t) ( /*I*/ U32BIT sizeInBytes );


/*******************************************************************************
* Memory free/de-allocate callback function (supplied at setup/clDsmSysCreate)
*
* NOTES:
* This will be called one or more times from clDsmSysDestroy to free any
* memory allocated for the instance. It is NOT called from any other API
* function.
*
*******************************************************************************/
typedef void (*clDsmFreeFunc_t) ( /*I*/ void* memory );



/* -- ERROR/PROGRESS CALLBACKS -- */

/*******************************************************************************
* Informs calling environment of errors triggered during stream/section
* processing
*******************************************************************************/
typedef void (*clDsmErrorFunc_t) ( /*I*/ clDsmErr_t err, void* args );


/*******************************************************************************
* Informs calling environment of state changes triggered during
* stream/section processing
*******************************************************************************/
typedef void (*clDsmProgressFunc_t) ( /*I*/ U32BIT prog, void* args );



/* -- TIMER CALLBACKS -- */

/*******************************************************************************
* Starts timer with specified period
*
* Timer trigger/timeout notified via clDsmSysProcessTimerEvent().
*
* When notifying a timeout then the value of clDsmTmrUserData
* supplied to this call MUST also be input to clDsmProcessTimerEvent.
*
* Returning a timerHandle value is optional but it should be set to Null if
* not used/available. This value is input to the stopTimerFunc callback.
*
* If a timerHandle is not available synchronously then it can be also be
* supplied when clDsmSysProcessTimerEvent is called.
*
*******************************************************************************/
typedef clDsmErr_t (*clDsmStartTimerFunc_t) ( H_DsmControl dsmControl,
    /*I*/ U32BIT timePeriod,
          void* clDsmTmrUserData,
    /*O*/ void* *pTimerHandle );


/*******************************************************************************
* Stops timer
*
* Timers will always be explicity stopped via this call, even after they have
* triggered. Both application and component handles/references are supplied for
* flexibility.
*
* NB. If a timer is stopped (aborted) before it has triggered (ie. before a
* timeout has been notified via clDsmSysProcessTimerEvent), timer abort must be
* notified via clDsmSysProcessTimerEvent() instead. The call to
* clDsmSysProcessTimerEvent can be made from within this callback.
*
*******************************************************************************/
typedef void (*clDsmStopTimerFunc_t) ( H_DsmControl dsmControl,
    /*I*/ void* timerHandle );



/* -- SI QUERY CALLBACKS -- */

/*******************************************************************************
* Makes (starts) SI query (eg. database lookup)
*
* Meaning of return values in this context:
*
* CLDSM_OK
* - Query has (synchronously) returned successful result.
*
* CLDSM_PENDING
* - Query is being executed asynchronously - results/events
*                   will be returned via clDsmSysProcessSIQueryEvent()
*
* CLDSM_ERR_SI_QUERY_FAILED
* - Query has (synchronously) failed to determine requested
*                   information (due to error in SI lookup).
*
* If a query result is to be returned asynchronously then the value of
* clDsmSIQueryRef and clDsmSIUserData supplied to this call MUST also be input
* to clDsmProcessSIQueryEvent along with the result.
*
* Returning a queryHandle value in pResult is optional. If not used/available,
* it should be set to Null. This value is input to the stopSIQueryFunc callback.
*
* If a queryHandle is not available synchronously then it can be also be
* supplied when clDsmSysProcessSIQueryEvent is called.
*
* NB. In this case, if the query is stopped for any reason before this event
* then the calling environment will have to identify the correct query to stop
* from the DSM-CC reference (clDsmSIQueryRef).
*
*******************************************************************************/
typedef clDsmErr_t (*clDsmStartSIQueryFunc_t) ( H_SiqInstance siqInstance,
    /*I*/ pclDsmSIQuery_t pQuery, clDsmSIQueryRef_t clDsmSIQueryRef,
          void* clDsmSIUserData,
    /*O*/ clDsmSIQueryResult_t *pResult );


/*******************************************************************************
* Stops an SI query
*
* Any asynchronous SI queries (ie. those that returned a status SIQUERY_PENDING
* to the StartSIQueryFunc call) will be explicity stopped via this call, even
* after they have completed.
*
* Both application and component handles/references are supplied for
* flexibility.
*
* NB. If an SI query is stopped (aborted) before it has completed (ie. before
* a result has been supplied via clDsmSysProcessSIQueryEvent), SI query abort
* must be notified via clDsmSysProcessSIQueryEvent() instead. The call to
* clDsmSysProcessSIQueryEvent can be made from within this callback.
*
*******************************************************************************/
typedef void (*clDsmStopSIQueryFunc_t) ( H_SiqInstance siqInstance,
    /*I*/ void* queryHandle, clDsmSIQueryRef_t clDsmSIQueryRef );



/* -- SI CHANGE REGISTRATION CALLBACKS -- */

/*******************************************************************************
* Register to receive notifications of changes to the SI for the specified
* service (on the current transport stream/multiplex).
*
* When a duplicate subscribe is made (ie. for a service that is already
* subscribed) it should increment the count of subscriptions for that service.
* Matching unsubscribe will be made for each subscribe.
*
* Changes are notified via the clDsmSysProcessSIChangeEvent function in the
* following situations:
*
*   - The subscribed service cannot be located
*   - The service is deleted from the multiplex (eg. PAT updated)
*   - The service info is updated (ie. PMT updated).
*
* If it can be determined immediately (ie. synchronously) that the requested
* service does not exist in the current multiplex (eg. it is not listed in the
* most recent stored copy of the PAT) then the output parameter serviceNotFound
* can be set to TRUE (otherwise set it to FALSE).
*
*******************************************************************************/
typedef clDsmErr_t (*clDsmSubscribeSIChanged_t) ( H_SiqInstance siqInstance,
    /*I*/ U16BIT service_id );


/*******************************************************************************
* Decrement number of subscriptions to the specified service. Only when this
* number reaches zero should this function de-register for notifications of
* changes to the SI for the service.
*
* This will be called to de-register for a previously subscribed service,
* even if the DSM-CC library has been notified that the subscribed service
* cannot be located.
*
*******************************************************************************/
typedef void (*clDsmUnsubscribeSIChanged_t) ( H_SiqInstance siqInstance,
    /*I*/ U16BIT service_id );



/* -- SECTION FILTER CALLBACKS -- */

/*******************************************************************************
* Requests a section filter to be started.
*
* It is assumed that the number of section filters that may be simultaneously
* requested (in use) is unlimited. Typically it is expected that the worst case
* requirement (eg. with full carousel caching and multiple stream events) is
* less than that specified in the setup.
*
* Filtered private sections are returned via clDsmSysProcessPrivateSection().
* The clDsmFilterRef value MUST be stored and also
* returned with any sections that matched the requested filter.
*
* Exact duplicate filters will never be requested simultaneously but filters
* with 'wildcard' (ie. tableIdExtMask) bits set may overlap with other
* requested filters with less or no mask bits set.
*
* If a section aligns with two or more such filters then it should only be
* matched to the 'narrowest' (ie. most exact) filter and that clDsmFilterRef
* value passed with the section data to clDsmSysProcessPrivateSection.
*
* Filters requested with high priority will always be narrower (ie. less mask
* bits set) than any overlapping low priority filters and this rule ensures
* that sections will always be matched to high priority filters in preference
* to low.
*
* NB. The worst case number of exact filters (ie. with no mask bits set)
* requested simultaneously may be large (eg. 100s) but the worst case number of
* simultaneous filters with (one or more) mask bits set is expected to be much
* smaller (eg. ~10).
*
* The filter should always remain in effect with continuous supply of section data,
* until delSectionFilterFunc is called.
*
* If platform requires priority rating in this callback, it can use
* clDsmSectionFilterPriority().
*
* Parameters:
*
* PID              MPEG2 PID
*
* tableId          DSM-CC tableId filter value for sections (byte 0).
*                  NB. Only the tableId values of 0x3B, 0x3C, 0x3D will
*                  be used for DSM-CC section filters.
*
* tableIdExt       DSM-CC tableIdExtension filter value (bytes 3&4)
*
* tableIdExtMask   DSM-CC active filter bits.
*                  NB.'Wildcard' bitmasks will only be set on contiguous
*                  bits starting at LSBit.
*
* Return: void*
* This is the platform filter handle value. It is given as input to the
* delSectionFilterFunc callback. NULL value is considered failure, and any other
* value is considered a successful operation.
*
*******************************************************************************/
typedef void* (*clDsmAddSectionFilterFunc_t) ( H_SfmInstance sfm,
    /*I*/ pclDsmSFilter_t pFilter, clDsmSFRef_t dsmFilterRef );


/*******************************************************************************
* Requests a section filter to be stopped
*
* To give flexibility in identifying the filter to delete, both application
* and component handles/references are supplied. Also a repeat of the section
* filter details are supplied (which are unique for any active filter) .
*
* NB. To avoid problems due to delays in deleting filters or caused by queuing
* sections the clDsmSysProcessPrivateSection function can detect sections being
* supplied from 'stale' (ie. deleted) filters. This will waste CPU time so the
* calling environment should ensure as soon as possible (after this callback
* is made) that sections matching the deleted filter are stopped.
*
*******************************************************************************/
typedef void (*clDsmDelSectionFilterFunc_t) ( H_SfmInstance sfm,
    /*I*/ void* filterHandle, clDsmSFRef_t clDsmFilterRef );


/*******************************************************************************
* Notify a section filter priority changed
*
*******************************************************************************/
typedef void (*clDsmSFPriorityChangedFunc_t) ( H_SfmInstance sfm,
    /*I*/ void* filterHandle, clDsmSFRef_t clDsmFilterRef,
          clDsmSFPriority_t priority );


/* -- LOAD & STREAM EVENT CALLBACKS -- */

/*******************************************************************************
* Notify of a load carousel event.
*
* Called when carousel booted, load completed (ie. SRG module loaded) or load
* aborted before completion (due to errors, timeout or unload). Component
* handle and userData values supplied for flexibility.
*
* If clDsmUnloadCarousel() is called before the carousel load is completed
* (ie. before this callback has been called with status OC_LOAD_COMPLETED)
* then the callback will actually be made from within the clDsmUnloadCarousel
* call with status OC_LOAD_ABORTED_UNLOAD.
*
* Any of the Synchronous or Asynchronous Client API calls (ie. API calls that
* do NOT start with clDsmSys...) can be made from within this callback. When
* doing this, care must be taken to avoid blocking or re-entrancy problems in
* the calling environment. Re-entrancy may occur when unloading objects or
* carousels since this can cause a (re-entrant) call to this callback.
*
*
*******************************************************************************/
typedef void (*clDsmNotifyCarouselLoadEventFunc_t) (
    /*I*/ clDsmOCHandle_t clDsmCarouselHandle, E_OCLoadStatus status,
          U32BIT carouselId );


/*******************************************************************************
* Notify of a load object event.
*
* Called when object load completed or load aborted before completion (due to
* errors, timeout or unload of object or carousel). Component handle and
* userData values supplied for flexibility.
*
* If clDsmUnloadObject() (or clDsmUnloadCarousel) is called before the object
* load is completed (ie. before this callback has been called with status
* OBJ_LOAD_COMPLETED) then the callback will actually be made from within the
* clDsmUnloadObject (or clDsmUnloadCarousel) call with status
* OBJ_LOAD_ABORTED_UNLOAD.
*
* Any of the Synchronous or Asynchronous Client API calls (ie. API calls that
* do NOT start with clDsmSys...) can be made from within this callback. When
* doing this, care must be taken to avoid blocking or re-entrancy problems in
* the calling environment. Re-entrancy may occur when unloading objects or
* carousels since this can cause a (re-entrant) call to this callback.
*
*
*******************************************************************************/
typedef void (*clDsmNotifyObjectLoadEventFunc_t) (
    /*I*/ clDsmObjHandle_t clDsmObjectHandle, clDsmObjLoadStatus_t status,
          H_ObjUserData pCopyOfObjLoadUserData );



typedef void (*clDsmNotifyStreamEventFunc_t)(
   /*I*/ H_DsmEvent eventHandle, clDsmSENotifyStatus_t status,
         void* userData1, void* userData2,
         U8BIT *namePtr, U8BIT* dataPtr, U8BIT namelen, U8BIT dataLen );



typedef void (*clDsmNotifyDeferredServiceFunc_t) (
   /*I*/ void* userData1, void* userData2,
         S_DvbLocator *pDeferredService );


/*
-- Type definitions for object caching rules
--
*/
typedef U32BIT clDsmCachingRules_t;

/*
-- Type definitions for setup variables
--
*/

/*
-- Setup structure for use at initialisation
*/
typedef struct {

    /*
    -- General callback pointers
    --
    -- NOTES:
    -- All callbacks MUST be provided except where indicated
    --
    */
    clDsmAllocFunc_t                      allocFunc;
    clDsmFreeFunc_t                       freeFunc;

    /* -- errorFunc - optional (Null if not used) */
    clDsmErrorFunc_t                      errorFunc;
    /* -- progressFunc - optional (Null if not used) */
    clDsmProgressFunc_t                   progressFunc;

    clDsmAddSectionFilterFunc_t           addSectionFilterFunc;
    clDsmDelSectionFilterFunc_t           delSectionFilterFunc;
    /* -- sfPriorityChangeFunc - optional (Null if not used) */
    clDsmSFPriorityChangedFunc_t          sfPriorityChangeFunc;

    clDsmStartTimerFunc_t                 startTimerFunc;
    clDsmStopTimerFunc_t                  stopTimerFunc;

    clDsmStartSIQueryFunc_t               startSIQueryFunc;
    clDsmStopSIQueryFunc_t                stopSIQueryFunc;

    clDsmSubscribeSIChanged_t             subscribeSIChangeFunc;
    clDsmUnsubscribeSIChanged_t           unsubscribeSIChangeFunc;

    /* -- notifyCarouselLoadEventFunc - optional (Null if not used) */
    clDsmNotifyCarouselLoadEventFunc_t    notifyCarouselLoadEventFunc;
    /* -- notifyObjectLoadEventFunc - optional (Null if not used) */
    clDsmNotifyObjectLoadEventFunc_t      notifyObjectLoadEventFunc;

    /* notifyStreamEventFunc can be Null when Stream Events are not required */
    clDsmNotifyStreamEventFunc_t          notifyStreamEventFunc;

    /* notifyDeferredServiceFunc can be Null when deferred service for Stream Objects are not required */
    clDsmNotifyDeferredServiceFunc_t      notifyDeferredServiceFunc;

   /* -- Control flags */

    H_DsmControl  dsmControl;
    /*
    -- Instance handle for external Service Information Query module
    */
    H_SiqInstance siqInstance;            /* -- Suggested default: Null */

    /*
    -- Instance handle for external Section Filter Manager module
    */
    H_SfmInstance sfmInstance;            /* -- Suggested default: Null */

    /*
    -- Pointer (optional) that can be used by calling environment for
    -- passing setup info to the memory manager (via clDsmMemMgr API) at
    -- memStart time.
    */
    void*   memMgrSetup;            /* -- Suggested default: Null */


    /*
    -- Specifies resolution of time units used on API in _milliseconds_
    -- (can be set to resolution of external timers)
    --
    -- NB. Time values are represented on the API and internally as U32BIT so
    -- timeUnitResolution should be chosen so that overflow problems will not
    -- occur during any likely period of continuous use for a receiver (eg. if
    -- timeUnitResolution = 10mS, wrap-round time = 1.36 years!).
    */
    U32BIT  timeUnitResolution;     /* -- Suggested default: 10 */


    /*
    -- Sets the size of dynamic memory available for DSM-CC to use.
    -- Apart from 100KB approx. the remainder of this memory will be requested
    -- and accessed via the dynamic memory manager API (clDsmMemMgrAPI.h).
    --
    -- NB. In debug builds DSM-CC may allocate slightly (<5%) more than this
    --     specified amount.
    --
    -- If clDsmMemMgrAPI is mapped to a system memory manager then it
    -- has an additional option (when it is opened) to decrease the amount
    -- of (the remainder of this) memory it makes available.
    */
    U32BIT     maxMemorySize;   /* -- Absolute minimum: DSMCC_MINIMUM_CACHE_SIZE */
                                /* -- Recommended min: DSMCC_DEFAULT_CACHE_SIZE  */

    /*
    -- Specifies the maximum number of section filters that are available
    -- in the calling environment (to this instance) for simultaneously
    -- acquiring DSM-CC private sections.
    --
    -- If client requests (or other events) cause the core stack to
    -- simultaneously require more section filters than the number available
    -- it will rotate its requests through the available filters. This may
    -- cause delays in responding to client requests so the larger this
    -- number the better.
    --
    -- The minimum value is NUM_SECTION_FILTERS_MINIMUM.
    -- Setting to zero will be interpreted as no restriction on the
    -- number of section filters available in the calling environment, and
    -- NUM_SECTION_FILTERS_MAXIMUM will be used.
    -- Setting to a value less than this the minimum will be ignored, and
    -- NUM_SECTION_FILTERS_MINIMUM will be used.
    -- Suggested Default: NUM_SECTION_FILTERS_DEFAULT
    */
    U16BIT  maxAvailableSectionFilters;

    /*
    -- Sets whether DSM-CC component maintains an internal record
    -- of SI query results so that it does not need to repeatedly
    -- make the same SI queries (to the calling env). Typically this
    -- will be used for storing association_tag to PID mappings.
    */
    BOOLEAN    storeSIQueryResults;    /* -- Default: FALSE */


    /*
    -- Sets whether DSM-CC component pre-fetches modules into its
    -- internal cache.
    --
    -- NB. This requires a large available memory size and a large number of
    --     available section filters.
    --
    -- Enabling turboCaching also activates full transparent caching (ie.
    -- automatic re-loading of cached modules that have version updates).
    -- This is because turboCaching will not work effectively without this
    -- and also because only when turboCaching is enabled are there
    -- likely to be sufficient section filters available to support
    -- automatic module re-loading.
    */
    BOOLEAN    turboCaching;           /* -- Default: FALSE */

} clDsmSetup_t, *pclDsmSetup_t;



/*---Global variable declarations for public use-----------------------------*/


/******************************************
* EXPORTED (PROVIDED) FUNCTION PROTOTYPES *
*******************************************/

/* ---------------------- SYNCHRONOUS SYSTEM API CALLS ---------------------- */

/*
-- NOTES:
--
-- The following functions must be called synchronously with each other and
-- with the Synchronous Client API calls since they use and modify common
-- instance data. If they need to be called/triggered from different threads
-- the calling environment must ensure synchronous behaviour - eg. by using
-- a mutex semaphore round the call (or queueing and calling from the same
-- thread).
--
-- In some circumstances it is possible to make one Synchronous API call from
-- within another one:
--
-- eg. clDsmSysProcessTimerEvent can be called within the stopTimerFunc
-- callback which itself may have been called from within.
-- clDsmSysProcessPrivateSection
--
-- eg. All Synchronous Client API calls can be called from within the
-- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks which may
-- themselves have been called within clDsmSysProcessPrivateSection.
--
-- These cases are clearly specified in the comments. The calling environment
-- must avoid possible permanent blocks in these circumstances, eg. from trying
-- to get a mutex on a thread that has it already.
--
*/


/*******************************************************************************
* Create DSM-CC Core Layer instance
*
* Only call at startup of an instance (before ANY other DSM-CC Core Layer API
* calls are made for that instance). Allocates all required 'static' memory
* for the instance (via allocFunc). Also stores (copies) data supplied in
* setup structure.
*
* NB. Dynamic (heap) memory used by the instance is allocated/deallocated and
* accessed via the dynamic memory manager API (clDsmMemMgrApi.h).
*
* Returns instance value which is used to reference the unique data used by
* this DSM Core instance. It MUST be stored by the calling environment and
* passed to any clDsm API calls for the instance.
*
* Also returns memContext parameter (obtained when memory manager started).
* If implemented/required, this gives the calling environment independent
* access to the memory manager context used by this DSM Core instance.
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   allocFunc
*   freeFunc - only on error
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_ALLOC_FAILED,
* CLDSM_ERR_MEM_HEAP_FULL
* CLDSM_ERR_ILLEGAL_SETUP
*
*******************************************************************************/
clDsmErr_t clDsmSysCreate(
    /*I*/ pclDsmSetup_t pSetup,
    /*O*/ clDsmInstHandle_t *pInstance, void* *pMemContext );



clDsmErr_t clDsmSysDestroy( clDsmInstHandle_t instance,
                            H_SiqInstance *pSiqInst, H_SfmInstance *pSfmInst );



clDsmErr_t clDsmSysReset( clDsmInstHandle_t instance, E_DsmRstMode mode );



clDsmErr_t clDsmSysSetCurrService( clDsmInstHandle_t instance,
    /*I*/ U16BIT original_network_id, U16BIT transport_stream_id,
          U16BIT service_id );

U16BIT clDsmSysCurrServiceId( clDsmInstHandle_t instance );


clDsmErr_t clDsmSysProcessTimerEvent( clDsmInstHandle_t instance,
    /*I*/ void* clDsmTmrUserData, clDsmTimerEventStatus_t status, void* timerHandle );



clDsmErr_t clDsmSysProcessSIQueryEvent( clDsmInstHandle_t instance,
    /*I*/ clDsmSIQueryRef_t clDsmSIQueryRef, void* clDsmSIUserData,
          pclDsmSIQueryResult_t pResult );



clDsmErr_t clDsmSysProcessSIChangeEvent( clDsmInstHandle_t instance,
    /*I*/ clDsmSIChangeEvent_t event, U16BIT service_id, U32BIT carousel_id );



/*******************************************************************************
* Process DSM-CC private section data
*
* NOTES:
*
* Call each time the Demux provides a private section from one of the
* requested PIDs (main TS data input of DSM-CC Core API).
*
* It is assumed that the calling environment has already CRC checked the
* section (if relevant) and only sections that pass this check will be
* supplied to clDsmSysProcessPrivateSection.
*
* The clDsmFilterRef and clDsmSfUserData inputs MUST be set to the values
* supplied when the filter for this section was requested
* (via addSectionFilterFunc).
*
* If sections have to be queued (or discarded) in the calling environment
* then those matching filters with a high priority MUST always be supplied
* to this function in preference to those matching low priority filters.
*
* NB. Although sections matching low priority filters (or even high priority
* filters) can be discarded if necessary. The order in which they were
* broadcast should always be maintained when they are supplied to this
* function.
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   errorFunc
*   progressFunc
*   addSectionFilterFunc
*   delSectionFilterFunc
*   stopTimerFunc
*   startSIQueryFunc
*   notifyCarouselLoadEventFunc
*   notifyObjectLoadEventFunc
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_INSTANCE
* CLDSM_ERR_ILLEGAL_PARAMETER
* CLDSM_ERR_ABORTED           When dsmFilterRef is not recognised (maybe stale)
*
*******************************************************************************/
clDsmErr_t clDsmSysProcessPrivateSection( clDsmInstHandle_t instance,
    /*I*/ U8BIT* pSection, clDsmSFRef_t dsmFilterRef );


/*******************************************************************************
* Request priority for DSM-CC private section data
*
*******************************************************************************/
clDsmErr_t clDsmSectionFilterPriority( clDsmInstHandle_t instance,
   clDsmSFRef_t dsmFilterRef,
   clDsmSFPriority_t *pPriority );


/* ---------------------- SYNCHRONOUS CLIENT API CALLS ---------------------- */

/*
-- NOTES:
--
-- The following functions must be called synchronously with each other and
-- with the above System API calls. If they need to be called/triggered
-- from different threads the calling environment must ensure synchronous
-- behaviour - eg. by using a mutex semaphore round the call (or queueing and
-- calling from the same thread).
--
-- Any of the Synchronous (or Asynchronous) Client API calls (ie. API
-- calls that do NOT start with clDsmSys...) can be made from within the
-- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks. When doing
-- this, care must be taken to avoid blocking or re-entrancy problems in
-- the calling environment. Re-entrancy may occur when unloading objects or
-- carousels since this can cause a (re-entrant) call to these callbacks.
--
*/


/* -- CAROUSEL LOAD FUNCS -- */

/*******************************************************************************
*
* Loads DSM-CC object carousel specified by carousel_id from indicated service
* (on the current multiplex/transport stream)
*
* If carousel_id is set to INVALID_CAROUSEL_ID, then this function loads the
* initiate boot carousel for the service
*
* NOTES:
*
* The returned clDsmCarouselHandle value must always be supplied by the
* calling environment whenever accessing objects in this carousel.
*
* Initially a section filter will be set up to acquire the DSI message for the
* carousel. Once the DSI message is acquired the calling environment is
* notified via the notifyCarouselLoadEventFunc callback (if supplied at
* setup/create) that the carousel is BOOTED. Open object requests can then be
* made for this carousel.
*
* When the service gateway (SRG) is loaded for this carousel the calling
* environment is notified again via the callback that the carousel is now
* LOADED. Objects in the carousel cannot be accessed (opened) until the
* service gateway for the carousel is loaded.
*
* If timeout occurs before the SRG is loaded a timeout error is returned. If
* an error is encountered while loading the carousel then an aborted error is
* returned.
*
* Using the ocLoadUserData1 and ocLoadUserData2 values is optional. These
* values are returned unchecked into the load event callback. They can be used
* for any purpose (eg. to aid in matching callbacks with corresponding load
* requests and/or clients).
*
* If timeout value is set to zero it means no (ie. infinite) timeout.
*
* If a duplicate request is made to load a boot carousel then an error will be
* generated but the clDsmCarouselHandle will be set to the value of the already
* loaded carousel.
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   startTimerFunc
*   startSIQueryFunc
*   addSectionFilterFunc
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_DUPLICATE_REQUEST
* CLDSM_ERR_MEM_HEAP_FULL
* CLDSM_ERR_NO_CURRENT_SERVICE_SET
* ?
*
*******************************************************************************/
clDsmErr_t clDsmLoadCarousel( clDsmInstHandle_t instance,
    /*I*/ U16BIT service_id, U32BIT carousel_id, U32BIT timeout,
    /*O*/ E_OCLoadStatus *pStatus, clDsmOCHandle_t *pclDsmCarouselHandle );




clDsmErr_t clDsmUnloadCarousel( clDsmInstHandle_t instance,
    /*I*/ clDsmOCHandle_t clDsmCarouselHandle, E_DsmRstMode mode );

clDsmErr_t clDsmGetCarouselId( clDsmInstHandle_t instance,
    /*I*/ clDsmOCHandle_t carouselHandle,
    /*O*/ U32BIT* pCarouselId );

clDsmOCHandle_t clDsmCurrentCarousel( clDsmInstHandle_t instance );

clDsmErr_t clDsmSetCurrentCarousel( clDsmInstHandle_t instance,
 /*I*/ clDsmOCHandle_t carouselHandle );

clDsmErr_t clDsmCarouselLoadFileGroups( clDsmInstHandle_t instance,
    /*I*/ clDsmOCHandle_t clDsmCarouselHandle,
    /*O*/ U16BIT* total, S_CarouselInfoFileGroup** pGroups );

clDsmErr_t clDsmCarouselUnloadFileGroups( clDsmInstHandle_t instance,
    /*I*/ clDsmOCHandle_t clDsmCarouselHandle,
    /*I*/ S_CarouselInfoFileGroup *groups );

/* -- OBJECT LOAD FUNCS -- */

/*******************************************************************************
*
* Load an object with the requested pathname into cache.
*
* Unless the carousel is specifed in the path, this will load an object from
* the 'Current' object carousel. The client may specify another carousel by
* setting the 'Current' object carousel with use of clDsmSetCurrentCarousel().
* If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
* then the function will attempt to load this carousel and make it the new
* 'Current' object carousel.
*
* NOTES:
*
* Currently, an object can only be loaded once the carousel is booted (DSI
* message acquired).
*
* Requested pathname must be a full (absolute) object pathname starting with
* an object in the root (ie. service gateway) directory of the specified
* carousel, eg. dir1/dir2/file3 is treated as DSM:/dir1/dir1/file3. Any
* characters defined in PATH_SEPERATOR_LIST_STRING will be treated as path
* token seperators all other chars are treated as part of a path token. An
* empty pathname U8BIT* (or U8BIT* containing only path token seperators)
* will open the service gateway directory itself.
*
* **** NB. SRG (& directory) ACCESS NOT YET IMPLEMENTED ****
*
* Returns an clDsmObjectHandle which the client uses to access the requested
* object. If the object is already cached then the status parameter will be
* set to OBJ_LOAD_COMPLETED. In this case the objectRef value can be used to
* access (eg. open for reading) the object/file data immediately.
*
* If the object is not in the cache then a fetch from the input stream is
* initiated and the status parameter set to OBJ_LOAD_IN_PROGRESS. When the
* object is loaded into the cache the calling environment is notified via the
* notifyObjectlLoadEventFunc callback (if supplied at setup/create).
*
* Using the objLoadUserData1 and objLoadUserData2 values is optional. These
* values are returned unchecked into the load event callback. They can be used
* for any purpose (eg. to aid in matching callbacks with corresponding load
* requests and/or clients).
*
* If multiple load requests are made for the same object before it is
* available each request will initiate a new (parallel) fetch from the input
* stream and a callback will be generated for each request when the object is
* loaded.
*
* While an object is LOADED it's contents are guaranteed to remain available
* and constant in cache memory (ie. it will not be updated from the input
* stream or deleted to create space in the cache).
*
* Any load request for an object (that is not already loaded) will only get
* completed by a call to clDsmysProcessPrivateSection. This will either have
* delivered the last part of the module containing the object or delivered a
* module containing a previously missing higher level directory in the object
* path that results in the requested object now being accessible in the cache.
*
* If a load proceeds part way down a path and then encounters an error, the
* load is aborted and the appropriate status returned via the callback. The
* clDsmObjectHandle cannot be used to access object/file DATA until/unless
* it is successfully loaded.
*
* **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED ****
* If caching rules are specified they are applied as below. If pCachingRules
* is set to Null the object will be given the default caching rules.
*
* If the object is not in the cache then the caching rules only have an
* effect on the subsequent caching of the object/module once the object load
* is completed and the object is actually unloaded (via clDsmUnloadObject),
* ie. when it is made available for caching.
*
* If the same object is requested multiple times in parallel, then once the
* object load is completed the highest priority caching rules are selected
* (fromStream overrides any other settings). These are applied only when
* the last of the object load instances is unloaded.
*
* If the requested object is already in the cache and the caching rules have
* fromStream set, then the object/module is immediately deleted from the cache
* and a new fetch from the input stream is initiated.
*
* If the same object is loaded multiple times in parallel then the caching
* rules specified at each load call will only replace the currently set
* caching rules for this object if they specify a higher caching priority
* (fromStream overrides any priority setting). If fromStream is set on any
* load then it will cause a re-fetch of the object for that load instance.
* The data for any previous load instances will only get physically deleted
* when they are 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.
*
* **** NOT YET IMPLEMENTED ****
* If timeout value is set to zero it means no (ie. infinite) timeout. If a
* timeout is specified and the object has not been loaded in the specified
* time (for any reason) then the load request is aborted and the client
* notified. Timeout is expressed in periods of timerResolution (specified at
* setup/create).
*
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   addSectionFilterFunc
*   startTimerFunc
*   startSIQueryFunc
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_MEM_HEAP_FULL
* CLDSM_ERR_INVALID_CAROUSEL_HANDLE
* CLDSM_ERR_INVALID_CACHING_RULES
* CLDSM_ERR_CAROUSEL_NOT_BOOTED
*
* CLDSM_ERR_INVALID_PATHNAME    - Null pointer or path too long
*
* CLDSM_ERR_LOAD_FAILURE        - Failed to load requested file (because
*                                 some part of path could not be located)
* +?
*
*******************************************************************************/
clDsmErr_t clDsmLoadObject( clDsmInstHandle_t instance,
    /*I*/ U8BIT* pathname, U32BIT timeout, clDsmCachingRules_t cachingRules,
          H_ObjUserData pUserData, U32BIT sizeOfUserData,
    /*O*/ clDsmObjLoadStatus_t *pStatus, clDsmObjHandle_t *pclDsmObjectHandle );



clDsmErr_t clDsmUnloadObject( clDsmInstHandle_t instance,
    /*I*/ clDsmObjHandle_t clDsmObjectHandle, E_DsmRstMode mode );


clDsmErr_t clDsmOpenObject(
    /*I*/ clDsmInstHandle_t  instance,
    /*I*/ clDsmObjHandle_t clDsmObjectHandle,
    /*O*/ clDsmObjectKind_t *pKind );




/*******************************************************************************
* Close a loaded object
*
* NOTES:
*
* Closes the loaded object data. If an object is open this must be called
* before it can be unloaded (via clDsmUnloadObject).
*
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   none
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* ?
*
*******************************************************************************/
clDsmErr_t clDsmCloseObject( clDsmInstHandle_t instance,
    /*I*/ clDsmObjHandle_t clDsmObjectHandle );


/*******************************************************************************
* **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED ****
*
* Set caching rules for any (cached) object.
*
* Unless the carousel is specifed in the path, this will load an object from
* the 'Current' object carousel. The client may specify another carousel by
* setting the 'Current' object carousel with use of clDsmSetCurrentCarousel().
* If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
* then the function will attempt to load this carousel and make it the new
* 'Current' object carousel.
*
* NOTES:
*
* If the object (OR ANY DIRECTORY ON THE PATH TO THE OBJECT) is not found in
* the cache this command is ignored. Object load failure problems detected at
* call time are not indicated.
*
* If the object is located in the cache the new caching rules are applied
* immediately. If fromStream is set the object is deleted from the cache.
*
* If the object is found in the cache but it is currently loaded the current
* caching rules for this object are set to the specified values (whatever they
* were previously). If fromStream is set, the current object load instance is
* marked for deletion, ie. it is no longer available to subsequent loads
* (although the data is only physically deleted when the object is unloaded
* via clDsmUnloadObject).
*
* Other caching rules are only applied when the object is unloaded.
* If the same object is loaded multiple times in parallel, then these caching
* rules are applied when the last of the object load instances is unloaded.
* Any caching rules set by this call may get overriden if a subsequent parallel
* load of the object that specifies higher priority caching rules is made.
*
* 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.
*
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   delSectionFilterFunc
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_PATHNAME
* CLDSM_ERR_INVALID_CACHING_RULES
* CLDSM_ERR_INVALID_CAROUSEL_HANDLE
* CLDSM_ERR_CAROUSEL_NOT_BOOTED
* CLDSM_ERR_CAROUSEL_LOAD_FAILED
* ?
*
*******************************************************************************/
clDsmErr_t clDsmSetObjectCachingRules( clDsmInstHandle_t instance,
    /*I*/ U8BIT* pathname, clDsmCachingRules_t cachingRules );



/*******************************************************************************
*
* Request pre-fetch into cache of the specified object.
*
* Unless the carousel is specifed in the path, this will load an object from
* the 'Current' object carousel. The client may specify another carousel by
* setting the 'Current' object carousel with use of clDsmSetCurrentCarousel().
* If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
* then the function will attempt to load this carousel and make it the new
* 'Current' object carousel.
*
* NOTES:
*
* The pre-fetch is always 'silent', ie. no notification is given when (or
* whether) the object has been pre-fetched into the cache (ie. object load
* failure errors detected at start time are also not indicated). If the object
* is already in the cache then the pre-fetch request is ignored.
*
* Pre-fetches work like load requests (ie. they are always performed) but
* if necessary, load requests (clDsmLoadObject) have priority on section filter
* resources.
*
* If the object has to be fetched into the cache then it is given the default
* caching rules (nb. fromStream is not set!).
*
* **** NOT YET IMPLEMENTED ****
* If timeout value is set to zero it means no (ie. infinite) timeout. If a
* timeout is specified and the object has not been pre-fetched in the specified
* time (for any reason) then the pre-fetch request is abandoned (silently).
* Timeout is expressed in periods of timerResolution (specified at
* setup/create).
*
*
* CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
*   addSectionFilterFunc
*   startTimerFunc
*   startSIQueryFunc
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_MEM_HEAP_FULL
* CLDSM_ERR_INVALID_PATHNAME
* CLDSM_ERR_INVALID_CAROUSEL_HANDLE
* CLDSM_ERR_CAROUSEL_NOT_BOOTED
* CLDSM_ERR_CAROUSEL_LOAD_FAILED
* ?
*
*******************************************************************************/
clDsmErr_t clDsmPrefetchObject( clDsmInstHandle_t instance,
    /*I*/ U8BIT* pathname, U32BIT timeout );



clDsmErr_t clDsmStreamEventSubscribe(
   /*I*/ clDsmInstHandle_t  dsmccInstance,
   /*I*/ clDsmObjHandle_t   streamObject,
   /*I*/ U8BIT*             eventName,
   /*I*/ void*              userData1,
   /*I*/ void*              userData2,
   /*O*/ H_DsmEvent*        pEventHandle );


clDsmErr_t clDsmStreamEventUnsubscribe(
   /*I*/ clDsmInstHandle_t dsmccInstance,
   /*I*/ H_DsmEvent        eventHandle );


clDsmErr_t clDsmSpecialEventSubscribe(
   /*I*/ clDsmInstHandle_t  dsmccInstance,
   /*I*/ U16BIT             associationTag,
   /*I*/ U16BIT             eventId,
   /*I*/ void*              userData1,
   /*I*/ void*              userData2,
   /*O*/ H_DsmEvent*        pEventHandle );


clDsmErr_t clDsmSpecialEventUnsubscribe(
   /*I*/ clDsmInstHandle_t dsmccInstance,
   /*I*/ H_DsmEvent        eventHandle );



/* ---------------------- ASYNCHRONOUS CLIENT API CALLS --------------------- */

/*
-- NOTES:
--
-- These functions can always be called asynchronously (ie. from a different
-- task/thread) since they can only access an individual object/file data area
-- which must have first been opened (& locked) by a previous synchronous API
-- call.
--
*/


/*******************************************************************************
* Get specified object kind (also returned by clDsmOpenObject)
*
* The object (clDsmObjectHandle) must be LOADED.
*
* NB. This can also be called to poll for when an object is loaded.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_OBJECT_NOT_LOADED
*
*******************************************************************************/
clDsmErr_t dsmObjectGetKind(
    /*I*/ clDsmObjHandle_t clDsmObjectHandle,
    /*O*/ clDsmObjectKind_t *pKind );



/*******************************************************************************
* Get specified object carousel handle.
*
* The object (clDsmObjectHandle) must be LOADED.
*
* NB. This can also be called to poll for when an object is loaded.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
*
*******************************************************************************/
clDsmErr_t dsmObjectGetCarouselHandle(
    /*I*/ clDsmObjHandle_t clDsmObjectHandle,
    /*O*/ void* *hCarouselHandle );



/* -- SERVICE GATEWAY ACCESS FUNCS -- */



clDsmErr_t dsmGetObjectServiceContext(
    /*I*/ clDsmObjHandle_t clDsmObjectHandle,
    /*I*/ U32BIT           serviceId,
    /*O*/ U8BIT**          pSrvCtxtData,
    /*O*/ U32BIT*          pSrvCtxtLen);


/* -- FILE OBJECT ACCESS FUNCS -- */

/*******************************************************************************
* Get length of specified file data
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* ?
*
*******************************************************************************/
clDsmErr_t dsmFileGetSize(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle,
    /*O*/ U32BIT *pSize );



/*******************************************************************************
* Read specified number of bytes of data from (opened) file into
* destination address, starting at the current 'cursor' ('file' ptr) position.
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The
* destination memory area MUST be large enough to hold the numBytes requested.
*
* If call attempts to read past end of the file data it will read as many
* bytes as possible and returns error code: CLDSM_ERR_END_OF_DATA
*
* Number of bytes read is stored in pNumBytesActual and 'cursor' position is
* incremented by numBytesActual.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* CLDSM_ERR_END_OF_DATA
* ?
*
*******************************************************************************/
clDsmErr_t clDsmFileRead(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, U32BIT numBytes,
    /*O*/ U8BIT *pDest, U32BIT *pNumBytesActual );

/*******************************************************************************
* Returns pointer to file data and number of bytes in the file.
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The
* destination memory area MUST be large enough to hold the numBytes requested.
*
* Number of bytes read is stored in pNumBytesActual.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_OBJECT_NOT_LOADED
*
*******************************************************************************/
clDsmErr_t clDsmFileDirect(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle,
    /*O*/ U8BIT **ppDest, U32BIT *pNumBytesActual );


/*******************************************************************************
* Read single byte of data from (opened) file at current 'cursor' position
* into destination and increment 'cursor' position.
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
*
* If call attempts to read past end of the object data, returns error code:
* CLDSM_ERR_END_OF_DATA
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* CLDSM_ERR_END_OF_DATA
* ?
*
*******************************************************************************/
clDsmErr_t dsmFileReadByte(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle,
    /*O*/ U8BIT *pDest );



/*******************************************************************************
* Set absolute file data 'cursor' position
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
*
* Cursor can point to any byte in file data AND to notional 'position'
* immediately after last byte of data but setting to anywhere else will return
* error code: CLDSM_ERR_END_OF_DATA
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* CLDSM_ERR_END_OF_DATA
* ?
*
*******************************************************************************/
clDsmErr_t dsmFileSetPosAbs(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, U32BIT absPosition );



/*******************************************************************************
* Set file data 'cursor' position relative to current position
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
*
* Cursor can point to any byte in file data AND to notional 'position'
* immediately after last byte of data but setting to anywhere else will return
* error code: CLDSM_ERR_END_OF_DATA
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* CLDSM_ERR_END_OF_DATA
* ?
*
*******************************************************************************/
clDsmErr_t dsmFileSetPosRel(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, S32BIT relPosition );



/*******************************************************************************
* Read (absolute) file data 'cursor' position
*
* The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
*
* Value returned in 'position' is the offset (in bytes) from the start (zero
* position) of the file data to the current cursor position.
*
* If the current cursor position points to past the end of the file data, then
* the position returned is equal to the file data size. Note that it is not
* legal to _read_ data from this cursor position/offset.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* ?
*
*******************************************************************************/
clDsmErr_t dsmFileGetPos(
    /*I*/ clDsmObjHandle_t clDsmFileObjectHandle,
    /*O*/ U32BIT *pPosition );


/* -- DIRECTORY ACCESS FUNCS -- */

/*******************************************************************************
*
* The directory object (dirObj) must be LOADED and OPEN.
*
* Retrieves the total number of directory entries and the total length of all
* entry names.
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
*
*******************************************************************************/
clDsmErr_t dsmDirEntrySizes(
   /*I*/ clDsmObjHandle_t dirObj,
   /*O*/ U16BIT *nameCount,
   /*O*/ U16BIT *totalNameLength );

/*******************************************************************************
*
* The directory object must be LOADED and OPEN.
*
* Retrieve the first entry handle
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INVALID_OBJECT_HANDLE
* CLDSM_ERR_INVALID_OBJECT_TYPE
* CLDSM_ERR_OBJECT_NOT_LOADED
* CLDSM_ERR_OBJECT_NOT_OPEN
* CLDSM_ERR_END_OF_DATA
*
*******************************************************************************/
clDsmErr_t dsmDirEntryFirst(
   /*I*/ clDsmObjHandle_t dirObj,
   /*O*/ void** pFirstEntry );

/*******************************************************************************
*
* Directory entry handle (entryHandle) is return by dsmDirEntryFirst or
* dsmDirEntryNext.
*
* Retrieve the next entry handle
*
* RETURNS:
* CLDSM_OK (0)
* CLDSM_ERR_INTERNAL
*
*******************************************************************************/
clDsmErr_t dsmDirEntryNext(
    /*I*/ void* entryHandle,
    /*O*/ void** pNextEntry );

/*******************************************************************************
*
* The directory entry handle is return by dsmDirEntryFirst or
* dsmDirEntryNext.
*
* Retrieve name length
*
* RETURNS:
* Length of name copied
*
*******************************************************************************/
U16BIT dsmDirEntryNameLength(
    /*I*/ void* entryHandle );

/*******************************************************************************
*
* The directory entry handle is return by dsmDirEntryFirst or
* dsmDirEntryNext.
*
* Copy name for entry to supplied memory location (pName)
* Caller should ensure there is enough space in location
*
* RETURNS:
* Length of name copied
*
*******************************************************************************/
U16BIT dsmDirEntryNameCopy(
    /*I*/ void* entryHandle,
    /*O*/ U8BIT *pName );


/* -- STREAM OBJECT ACCESS FUNCS -- */

clDsmErr_t dsmStreamGetProgramAssocTag(
    /*I*/ clDsmObjHandle_t streamObjectHandle,
    /*O*/ U16BIT*          pAssociation_tag);


clDsmErr_t clDsmStreamGetDeferredService(  clDsmInstHandle_t instance,
    /*I*/ clDsmObjHandle_t streamObject, void* userData1, void* userData2,
    /*O*/ S_DvbLocator **ppDeferredService );

/* -- STREAM EVENT ACCESS FUNCS -- */

clDsmErr_t clDsmStreamEventNameList(
   /*I*/ clDsmInstHandle_t  dsmccInstance,
   /*I*/ clDsmObjHandle_t   streamObject,
   /*O*/ U8BIT **pNamesPtr, U16BIT *pNamesLen );


/*----------------------------------------------------------------------------*/

#ifdef __cplusplus
}
#endif
#endif /* _DSMCC_H_ */