DSMCC
15.3.1
|
00001 /******************************************************************************* 00002 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org) 00003 * Copyright © 2004 Ocean Blue Software Ltd 00004 * Copyright © 2000 Koninklijke Philips Electronics N.V 00005 * 00006 * This file is part of a DTVKit Software Component 00007 * You are permitted to copy, modify or distribute this file subject to the terms 00008 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org 00009 * 00010 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, 00011 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES 00012 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. 00013 * 00014 * If you or your organisation is not a member of DTVKit then you have access 00015 * to this source code outside of the terms of the licence agreement 00016 * and you are expected to delete this and any associated files immediately. 00017 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org 00018 *******************************************************************************/ 00027 /* 00028 * DVB DSM-CC Object Carousel Core Layer API 00029 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 00030 * 00031 * OVERVIEW: 00032 * 00033 * This API has been specified in standard ANSI C and is designed as a completely 00034 * OS and Platform (ie. HW and SW driver) independent interface to the core 00035 * DSM-CC layer. 00036 * 00037 * To avoid confusion over the sizes of standard C types on different platforms, it 00038 * assumes that a standard set of unambiguous type names have been defined to 00039 * platform specific types in the file clDsmPlatformAPI.h (also standard 00040 * definitions for TRUE/FALSE/Null). NB. This currently matches the recommended DVP 00041 * coding standards. 00042 * 00043 * 00044 * DSM-CC code conforming to this API should be readily portable to any platform 00045 * and OS environment. It assumes that this environment (designated 'the 00046 * calling environment') can provide the following: 00047 * 00048 * - Filtering of MPEG2 private sections from a single transport stream on multiple 00049 * simultaneous PID values and section filter values. 00050 * 00051 * - Acquisition and parsing of PMT(s) for specified program stream, query/lookup 00052 * of specific information from the SI data 00053 * 00054 * - Basic block memory allocation and de-allocation (at startup and shutdown) 00055 * 00056 * - Semaphore or queuing mechanisms for synchronising API calls initiated by 00057 * asynchronously running tasks or threads 00058 * 00059 * - Queuing mechanisms, eg. for notifying clients of asynchronous object loads 00060 * 00061 * - Multiple timers (eg. 10mS resolution) 00062 * 00063 * - Dynamic (heap) memory management that conforms to the API specified in 00064 * clDsmMemMgrApi.h 00065 * 00066 * NB. A non-fragmenting linked-block based memory manager that conforms to this 00067 * API is supplied along with the DSM-CC core stack (clDsmMemMgrBlock.c). 00068 * 00069 * 00070 * It is intended that all platform (and DSM-CC profile) specific functions 00071 * including handling of multiple clients/apps (if required) are implemented in 00072 * wrapper layers that call into this API. Only these layers should need to 00073 * be modified when porting to a new platform (or DSM-CC profile). 00074 * 00075 * 00076 * BASIC DATA FLOW AND LAYERS: 00077 * 00078 * +-----------+ +-----load/unload-----------------+ 00079 * | DEMUX & | DSM-CC | carousel | 00080 * TS-->| section |---private------+ | | 00081 * | filters | sections | | +--subscribe/unsubscribe--+ | 00082 * +-----------+ | | | for stream event | | 00083 * A | | | | | 00084 * | | | | load/unload +---------------+ 00085 * +---add/delete-----+ | | | +-open/close--| CLIENT(s) | 00086 * section filter | | | | | object +---------------+ 00087 * | | | | | A A A 00088 * +---SI Query--+ | | | | | | | | 00089 * | result | | V V V V | | | 00090 * +----------------+ | +------------------------+ | | | 00091 * SI->| SI (PAT/PMT) | +->| | object/ | | | 00092 * | database | | |--carousel-+ | | 00093 * +----------------+ +---| | loaded | | 00094 * A | | | | | 00095 * | | | Platform & Profile |--stream event--+ | 00096 * +--SI Query--+ | (eg.MHEG/MHP) specific | | 00097 * | 'porting' layer(s) | +-object data/info-+ 00098 * +--Trigger-->| | | 00099 * +----------+ | | | | 00100 * | Timers |--+ +-----| | | 00101 * +----------+ | |------synchronous-------+-asynchronous-+ 00102 * A | |==============(clDsmAPI)===============| 00103 * | | | | 00104 * +---start/stop--+ | | 00105 * | DSM-CC | 00106 * | CORE (IP) LAYER | 00107 * | | 00108 * | | 00109 * | | 00110 * +-------------------/\------------------+ 00111 * +--------\/--------+ 00112 * | DSMCC DATA CACHE | 00113 * +------------------+ 00114 * 00115 * 00116 * -------------------------------------------------------------------------------- 00117 */ 00118 #ifndef _DSMCC_H_ 00119 #define _DSMCC_H_ 00120 00121 /*---includes for this file--------------------------------------------------*/ 00122 #include "cldsmtypes.h" 00123 00124 #ifdef __cplusplus 00125 extern "C" { 00126 #endif 00127 00128 00129 /*---Constant and macro definitions for public use---------------------------*/ 00130 00131 #define NUM_OPEN_DSM_OBJECTS_MAX 128 00132 00133 #define DSMCC_MINIMUM_CACHE_SIZE (1024 * 1024 * 1) 00134 #define DSMCC_DEFAULT_CACHE_SIZE (1024 * 1024 * 6) 00135 00136 /* -- caching priority rules */ 00137 #define CACHE_RULES_DEFAULT 0x003F 00138 #define CACHE_RULES_FROM_STREAM (0) 00139 #define CACHE_RULES_STATIC 0x0080 00140 #define CACHE_RULES_EXISTS 0x0400 00141 00142 /* -- Progress codes */ 00143 #define CLDSM_PROG_CURR_SERVICE_CACHE_FULL 0 00144 /* + ? */ 00145 00146 00147 /*---Enumerations for public use---------------------------------------------*/ 00148 00149 /*---Global type defs for public use-----------------------------------------*/ 00150 00151 00152 /* 00153 -- **** TIMER EVENT TYPES *** 00154 */ 00155 00156 typedef struct _clDsmTimerRef_struct* clDsmTimerRef_t; 00157 00158 /* -- Timer event status -- */ 00159 typedef enum { 00160 TIMER_TRIGGERED = 0, 00161 TIMER_ABORTED 00162 } clDsmTimerEventStatus_t, *pclDsmTimerEventStatus_t; 00163 00164 00165 /* 00166 -- **** CAROUSEL TYPES *** 00167 */ 00168 00169 typedef struct s_ObjCarousel* clDsmOCHandle_t; 00170 00171 00172 /* 00173 -- **** OBJECT DATA TYPES *** 00174 */ 00175 00176 typedef struct _clDsmObjectHandle_struct* clDsmObjHandle_t; 00177 00178 /* -- Object kind -- */ 00179 typedef enum { 00180 ANON_OBJ = 0, 00181 FILE_OBJ, 00182 DIRECTORY_OBJ, 00183 SERVICE_GATEWAY_OBJ, 00184 STREAM_OBJ, 00185 STREAM_OBJ_WITH_EVENTS, 00186 LINK_TO_ALTERNATE_OC_OBJ 00187 } clDsmObjectKind_t, *pclDsmObjectKind_t; 00188 00189 00190 /* 00191 -- Status type for object load 00192 */ 00193 typedef enum { 00194 /*0*/ OBJ_LOAD_UNINITIATED = 0, 00195 /*1*/ OBJ_LOAD_IN_PROGRESS, 00196 /*2*/ OBJ_LOAD_COMPLETED, 00197 /*3*/ OBJ_LOAD_ABORTED_TIMEOUT, 00198 /*4*/ OBJ_LOAD_ABORTED_PATH_ERROR, 00199 /*5*/ OBJ_LOAD_ABORTED_ERROR, 00200 #ifdef DSM_MHP_PROFILE 00201 /*6*/ OBJ_LOAD_ABORTED_UNLOAD, 00202 /* -- NOT CURRENTLY IMPLEMENTED */ 00203 /*7*/ OBJ_LOAD_PARENT_DIR_LOADED 00204 #else 00205 /*6*/ OBJ_LOAD_ABORTED_UNLOAD 00206 #endif 00207 } clDsmObjLoadStatus_t, *pclDsmObjLoadStatus_t; 00208 00209 00210 typedef struct s_ObjUserData *H_ObjUserData; 00211 00212 /* 00213 -- **** STREAM EVENT DATA TYPES **** 00214 */ 00215 00216 typedef struct _clDsmStreamEventHandle_struct* clDsmStreamEventHandle_t; 00217 00218 /* 00219 This is the current status of the notification of a Stream Event. 00220 */ 00221 typedef enum 00222 { 00223 SEN_INITIAL, 00224 SEN_NOTIFIED, 00225 SEN_ABORTED_OBJ_LOAD_FAILED, 00226 SEN_ABORTED_SUBSCRIBE_FAILED, 00227 SEN_TRIGGERED, 00228 SEN_ACKNOWLEDGE_UNSUBSCRIBE 00229 } clDsmSENotifyStatus_t; 00230 00231 00232 /* --------------- REQUIRED API - CALLBACK TYPE DEFINITIONS ----------------- */ 00233 00234 /* 00235 -- NOTES: 00236 -- 00237 -- The calling environment must provide functions that match these callback 00238 -- type definitions (except clDsmProgressFunc_t which is optional). All 00239 -- required callbacks should be non-blocking. The callback addresses are 00240 -- supplied to the DSM-CC instance at instance create/setup. 00241 -- 00242 -- The callbacks are not expected to fail except under exception conditions. 00243 -- 00244 -- For callbacks with 'int' return values, this should be used to indicate: 00245 -- zero: Successful execution/registration of call with calling env. 00246 -- non-zero: Failure to execute/register call (eg. due to memory failure) 00247 -- 00248 -- The DSMCC library will attempt to take some logical actions in response to a 00249 -- failure of a start/add callback that may enable it to continue.(eg. abandon 00250 -- request and notify client of a load failure due to system error). 00251 -- 00252 -- The stop/delete callbacks are not provided with return values since there is 00253 -- no meaningful action the DSM-CC library can take in response to these 00254 -- failing. If it is possible that these callbacks fail to execute the 00255 -- requested action then the internal state of the DSM-CC library will become 00256 -- inconsistent with the calling environment. The calling environment must 00257 -- handle this situatation - eg. by raising an exception and processing it when 00258 -- the DSM-CC API call that triggered it completes. The calling environment 00259 -- should deal with the problem before making any further DSM-CC API calls 00260 -- (except clDsmSysReset or clDsmSysDestroy). It should either ensure that the 00261 -- action requested by the callback is successfully executed or clear the problem 00262 -- and reset/restart the DSM-CC library. 00263 -- 00264 */ 00265 00266 00267 /* -- INSTANCE MEMORY CALLBACKS -- */ 00268 00269 /******************************************************************************* 00270 * Memory allocate callback function (supplied at setup/clDsmSysCreate) 00271 * 00272 * NOTES: 00273 * This will be called from clDsmSysCreate to allocate the memory for the instance 00274 * 'static' variables (according to the setup parameters supplied by the calling 00275 * environment). 00276 * 00277 * It is mostly called to allocate memory for caching DSM-CC data. 00278 * 00279 * In some extreme circumstances it may be called to allocate some additional 00280 * instance memory for section filtering. This will only happen when/if the number 00281 * of simultaneous section filters required exceeds the pre-allocated number. 00282 * Any additional instance memory will not freed until the instance is destroyed 00283 * 00284 * RETURNS: pointer to start of allocated memory block, Null = FAILURE 00285 * 00286 *******************************************************************************/ 00287 typedef void* (*clDsmAllocFunc_t) ( /*I*/ U32BIT sizeInBytes ); 00288 00289 00290 /******************************************************************************* 00291 * Memory free/de-allocate callback function (supplied at setup/clDsmSysCreate) 00292 * 00293 * NOTES: 00294 * This will be called one or more times from clDsmSysDestroy to free any 00295 * memory allocated for the instance. It is NOT called from any other API 00296 * function. 00297 * 00298 *******************************************************************************/ 00299 typedef void (*clDsmFreeFunc_t) ( /*I*/ void* memory ); 00300 00301 00302 00303 /* -- ERROR/PROGRESS CALLBACKS -- */ 00304 00305 /******************************************************************************* 00306 * Informs calling environment of errors triggered during stream/section 00307 * processing 00308 *******************************************************************************/ 00309 typedef void (*clDsmErrorFunc_t) ( /*I*/ clDsmErr_t err, void* args ); 00310 00311 00312 /******************************************************************************* 00313 * Informs calling environment of state changes triggered during 00314 * stream/section processing 00315 *******************************************************************************/ 00316 typedef void (*clDsmProgressFunc_t) ( /*I*/ U32BIT prog, void* args ); 00317 00318 00319 00320 /* -- TIMER CALLBACKS -- */ 00321 00322 /******************************************************************************* 00323 * Starts timer with specified period 00324 * 00325 * Timer trigger/timeout notified via clDsmSysProcessTimerEvent(). 00326 * 00327 * When notifying a timeout then the value of clDsmTmrUserData 00328 * supplied to this call MUST also be input to clDsmProcessTimerEvent. 00329 * 00330 * Returning a timerHandle value is optional but it should be set to Null if 00331 * not used/available. This value is input to the stopTimerFunc callback. 00332 * 00333 * If a timerHandle is not available synchronously then it can be also be 00334 * supplied when clDsmSysProcessTimerEvent is called. 00335 * 00336 *******************************************************************************/ 00337 typedef clDsmErr_t (*clDsmStartTimerFunc_t) ( H_DsmControl dsmControl, 00338 /*I*/ U32BIT timePeriod, 00339 void* clDsmTmrUserData, 00340 /*O*/ void* *pTimerHandle ); 00341 00342 00343 /******************************************************************************* 00344 * Stops timer 00345 * 00346 * Timers will always be explicity stopped via this call, even after they have 00347 * triggered. Both application and component handles/references are supplied for 00348 * flexibility. 00349 * 00350 * NB. If a timer is stopped (aborted) before it has triggered (ie. before a 00351 * timeout has been notified via clDsmSysProcessTimerEvent), timer abort must be 00352 * notified via clDsmSysProcessTimerEvent() instead. The call to 00353 * clDsmSysProcessTimerEvent can be made from within this callback. 00354 * 00355 *******************************************************************************/ 00356 typedef void (*clDsmStopTimerFunc_t) ( H_DsmControl dsmControl, 00357 /*I*/ void* timerHandle ); 00358 00359 00360 00361 /* -- SI QUERY CALLBACKS -- */ 00362 00363 /******************************************************************************* 00364 * Makes (starts) SI query (eg. database lookup) 00365 * 00366 * Meaning of return values in this context: 00367 * 00368 * CLDSM_OK 00369 * - Query has (synchronously) returned successful result. 00370 * 00371 * CLDSM_PENDING 00372 * - Query is being executed asynchronously - results/events 00373 * will be returned via clDsmSysProcessSIQueryEvent() 00374 * 00375 * CLDSM_ERR_SI_QUERY_FAILED 00376 * - Query has (synchronously) failed to determine requested 00377 * information (due to error in SI lookup). 00378 * 00379 * If a query result is to be returned asynchronously then the value of 00380 * clDsmSIQueryRef and clDsmSIUserData supplied to this call MUST also be input 00381 * to clDsmProcessSIQueryEvent along with the result. 00382 * 00383 * Returning a queryHandle value in pResult is optional. If not used/available, 00384 * it should be set to Null. This value is input to the stopSIQueryFunc callback. 00385 * 00386 * If a queryHandle is not available synchronously then it can be also be 00387 * supplied when clDsmSysProcessSIQueryEvent is called. 00388 * 00389 * NB. In this case, if the query is stopped for any reason before this event 00390 * then the calling environment will have to identify the correct query to stop 00391 * from the DSM-CC reference (clDsmSIQueryRef). 00392 * 00393 *******************************************************************************/ 00394 typedef clDsmErr_t (*clDsmStartSIQueryFunc_t) ( H_SiqInstance siqInstance, 00395 /*I*/ pclDsmSIQuery_t pQuery, clDsmSIQueryRef_t clDsmSIQueryRef, 00396 void* clDsmSIUserData, 00397 /*O*/ clDsmSIQueryResult_t *pResult ); 00398 00399 00400 /******************************************************************************* 00401 * Stops an SI query 00402 * 00403 * Any asynchronous SI queries (ie. those that returned a status SIQUERY_PENDING 00404 * to the StartSIQueryFunc call) will be explicity stopped via this call, even 00405 * after they have completed. 00406 * 00407 * Both application and component handles/references are supplied for 00408 * flexibility. 00409 * 00410 * NB. If an SI query is stopped (aborted) before it has completed (ie. before 00411 * a result has been supplied via clDsmSysProcessSIQueryEvent), SI query abort 00412 * must be notified via clDsmSysProcessSIQueryEvent() instead. The call to 00413 * clDsmSysProcessSIQueryEvent can be made from within this callback. 00414 * 00415 *******************************************************************************/ 00416 typedef void (*clDsmStopSIQueryFunc_t) ( H_SiqInstance siqInstance, 00417 /*I*/ void* queryHandle, clDsmSIQueryRef_t clDsmSIQueryRef ); 00418 00419 00420 00421 /* -- SI CHANGE REGISTRATION CALLBACKS -- */ 00422 00423 /******************************************************************************* 00424 * Register to receive notifications of changes to the SI for the specified 00425 * service (on the current transport stream/multiplex). 00426 * 00427 * When a duplicate subscribe is made (ie. for a service that is already 00428 * subscribed) it should increment the count of subscriptions for that service. 00429 * Matching unsubscribe will be made for each subscribe. 00430 * 00431 * Changes are notified via the clDsmSysProcessSIChangeEvent function in the 00432 * following situations: 00433 * 00434 * - The subscribed service cannot be located 00435 * - The service is deleted from the multiplex (eg. PAT updated) 00436 * - The service info is updated (ie. PMT updated). 00437 * 00438 * If it can be determined immediately (ie. synchronously) that the requested 00439 * service does not exist in the current multiplex (eg. it is not listed in the 00440 * most recent stored copy of the PAT) then the output parameter serviceNotFound 00441 * can be set to TRUE (otherwise set it to FALSE). 00442 * 00443 *******************************************************************************/ 00444 typedef clDsmErr_t (*clDsmSubscribeSIChanged_t) ( H_SiqInstance siqInstance, 00445 /*I*/ U16BIT service_id ); 00446 00447 00448 /******************************************************************************* 00449 * Decrement number of subscriptions to the specified service. Only when this 00450 * number reaches zero should this function de-register for notifications of 00451 * changes to the SI for the service. 00452 * 00453 * This will be called to de-register for a previously subscribed service, 00454 * even if the DSM-CC library has been notified that the subscribed service 00455 * cannot be located. 00456 * 00457 *******************************************************************************/ 00458 typedef void (*clDsmUnsubscribeSIChanged_t) ( H_SiqInstance siqInstance, 00459 /*I*/ U16BIT service_id ); 00460 00461 00462 00463 /* -- SECTION FILTER CALLBACKS -- */ 00464 00465 /******************************************************************************* 00466 * Requests a section filter to be started. 00467 * 00468 * It is assumed that the number of section filters that may be simultaneously 00469 * requested (in use) is unlimited. Typically it is expected that the worst case 00470 * requirement (eg. with full carousel caching and multiple stream events) is 00471 * less than that specified in the setup. 00472 * 00473 * Filtered private sections are returned via clDsmSysProcessPrivateSection(). 00474 * The clDsmFilterRef value MUST be stored and also 00475 * returned with any sections that matched the requested filter. 00476 * 00477 * Exact duplicate filters will never be requested simultaneously but filters 00478 * with 'wildcard' (ie. tableIdExtMask) bits set may overlap with other 00479 * requested filters with less or no mask bits set. 00480 * 00481 * If a section aligns with two or more such filters then it should only be 00482 * matched to the 'narrowest' (ie. most exact) filter and that clDsmFilterRef 00483 * value passed with the section data to clDsmSysProcessPrivateSection. 00484 * 00485 * Filters requested with high priority will always be narrower (ie. less mask 00486 * bits set) than any overlapping low priority filters and this rule ensures 00487 * that sections will always be matched to high priority filters in preference 00488 * to low. 00489 * 00490 * NB. The worst case number of exact filters (ie. with no mask bits set) 00491 * requested simultaneously may be large (eg. 100s) but the worst case number of 00492 * simultaneous filters with (one or more) mask bits set is expected to be much 00493 * smaller (eg. ~10). 00494 * 00495 * The filter should always remain in effect with continuous supply of section data, 00496 * until delSectionFilterFunc is called. 00497 * 00498 * If platform requires priority rating in this callback, it can use 00499 * clDsmSectionFilterPriority(). 00500 * 00501 * Parameters: 00502 * 00503 * PID MPEG2 PID 00504 * 00505 * tableId DSM-CC tableId filter value for sections (byte 0). 00506 * NB. Only the tableId values of 0x3B, 0x3C, 0x3D will 00507 * be used for DSM-CC section filters. 00508 * 00509 * tableIdExt DSM-CC tableIdExtension filter value (bytes 3&4) 00510 * 00511 * tableIdExtMask DSM-CC active filter bits. 00512 * NB.'Wildcard' bitmasks will only be set on contiguous 00513 * bits starting at LSBit. 00514 * 00515 * Return: void* 00516 * This is the platform filter handle value. It is given as input to the 00517 * delSectionFilterFunc callback. NULL value is considered failure, and any other 00518 * value is considered a successful operation. 00519 * 00520 *******************************************************************************/ 00521 typedef void* (*clDsmAddSectionFilterFunc_t) ( H_SfmInstance sfm, 00522 /*I*/ pclDsmSFilter_t pFilter, clDsmSFRef_t dsmFilterRef ); 00523 00524 00525 /******************************************************************************* 00526 * Requests a section filter to be stopped 00527 * 00528 * To give flexibility in identifying the filter to delete, both application 00529 * and component handles/references are supplied. Also a repeat of the section 00530 * filter details are supplied (which are unique for any active filter) . 00531 * 00532 * NB. To avoid problems due to delays in deleting filters or caused by queuing 00533 * sections the clDsmSysProcessPrivateSection function can detect sections being 00534 * supplied from 'stale' (ie. deleted) filters. This will waste CPU time so the 00535 * calling environment should ensure as soon as possible (after this callback 00536 * is made) that sections matching the deleted filter are stopped. 00537 * 00538 *******************************************************************************/ 00539 typedef void (*clDsmDelSectionFilterFunc_t) ( H_SfmInstance sfm, 00540 /*I*/ void* filterHandle, clDsmSFRef_t clDsmFilterRef ); 00541 00542 00543 /******************************************************************************* 00544 * Notify a section filter priority changed 00545 * 00546 *******************************************************************************/ 00547 typedef void (*clDsmSFPriorityChangedFunc_t) ( H_SfmInstance sfm, 00548 /*I*/ void* filterHandle, clDsmSFRef_t clDsmFilterRef, 00549 clDsmSFPriority_t priority ); 00550 00551 00552 /* -- LOAD & STREAM EVENT CALLBACKS -- */ 00553 00554 /******************************************************************************* 00555 * Notify of a load carousel event. 00556 * 00557 * Called when carousel booted, load completed (ie. SRG module loaded) or load 00558 * aborted before completion (due to errors, timeout or unload). Component 00559 * handle and userData values supplied for flexibility. 00560 * 00561 * If clDsmUnloadCarousel() is called before the carousel load is completed 00562 * (ie. before this callback has been called with status OC_LOAD_COMPLETED) 00563 * then the callback will actually be made from within the clDsmUnloadCarousel 00564 * call with status OC_LOAD_ABORTED_UNLOAD. 00565 * 00566 * Any of the Synchronous or Asynchronous Client API calls (ie. API calls that 00567 * do NOT start with clDsmSys...) can be made from within this callback. When 00568 * doing this, care must be taken to avoid blocking or re-entrancy problems in 00569 * the calling environment. Re-entrancy may occur when unloading objects or 00570 * carousels since this can cause a (re-entrant) call to this callback. 00571 * 00572 * 00573 *******************************************************************************/ 00574 typedef void (*clDsmNotifyCarouselLoadEventFunc_t) ( 00575 /*I*/ clDsmOCHandle_t clDsmCarouselHandle, E_OCLoadStatus status, 00576 U32BIT carouselId ); 00577 00578 00579 /******************************************************************************* 00580 * Notify of a load object event. 00581 * 00582 * Called when object load completed or load aborted before completion (due to 00583 * errors, timeout or unload of object or carousel). Component handle and 00584 * userData values supplied for flexibility. 00585 * 00586 * If clDsmUnloadObject() (or clDsmUnloadCarousel) is called before the object 00587 * load is completed (ie. before this callback has been called with status 00588 * OBJ_LOAD_COMPLETED) then the callback will actually be made from within the 00589 * clDsmUnloadObject (or clDsmUnloadCarousel) call with status 00590 * OBJ_LOAD_ABORTED_UNLOAD. 00591 * 00592 * Any of the Synchronous or Asynchronous Client API calls (ie. API calls that 00593 * do NOT start with clDsmSys...) can be made from within this callback. When 00594 * doing this, care must be taken to avoid blocking or re-entrancy problems in 00595 * the calling environment. Re-entrancy may occur when unloading objects or 00596 * carousels since this can cause a (re-entrant) call to this callback. 00597 * 00598 * 00599 *******************************************************************************/ 00600 typedef void (*clDsmNotifyObjectLoadEventFunc_t) ( 00601 /*I*/ clDsmObjHandle_t clDsmObjectHandle, clDsmObjLoadStatus_t status, 00602 H_ObjUserData pCopyOfObjLoadUserData ); 00603 00604 00605 00641 typedef void (*clDsmNotifyStreamEventFunc_t)( 00642 /*I*/ H_DsmEvent eventHandle, clDsmSENotifyStatus_t status, 00643 void* userData1, void* userData2, 00644 U8BIT *namePtr, U8BIT* dataPtr, U8BIT namelen, U8BIT dataLen ); 00645 00646 00647 00662 typedef void (*clDsmNotifyDeferredServiceFunc_t) ( 00663 /*I*/ void* userData1, void* userData2, 00664 S_DvbLocator *pDeferredService ); 00665 00666 00667 /* 00668 -- Type definitions for object caching rules 00669 -- 00670 */ 00671 typedef U32BIT clDsmCachingRules_t; 00672 00673 /* 00674 -- Type definitions for setup variables 00675 -- 00676 */ 00677 00678 /* 00679 -- Setup structure for use at initialisation 00680 */ 00681 typedef struct { 00682 00683 /* 00684 -- General callback pointers 00685 -- 00686 -- NOTES: 00687 -- All callbacks MUST be provided except where indicated 00688 -- 00689 */ 00690 clDsmAllocFunc_t allocFunc; 00691 clDsmFreeFunc_t freeFunc; 00692 00693 /* -- errorFunc - optional (Null if not used) */ 00694 clDsmErrorFunc_t errorFunc; 00695 /* -- progressFunc - optional (Null if not used) */ 00696 clDsmProgressFunc_t progressFunc; 00697 00698 clDsmAddSectionFilterFunc_t addSectionFilterFunc; 00699 clDsmDelSectionFilterFunc_t delSectionFilterFunc; 00700 /* -- sfPriorityChangeFunc - optional (Null if not used) */ 00701 clDsmSFPriorityChangedFunc_t sfPriorityChangeFunc; 00702 00703 clDsmStartTimerFunc_t startTimerFunc; 00704 clDsmStopTimerFunc_t stopTimerFunc; 00705 00706 clDsmStartSIQueryFunc_t startSIQueryFunc; 00707 clDsmStopSIQueryFunc_t stopSIQueryFunc; 00708 00709 clDsmSubscribeSIChanged_t subscribeSIChangeFunc; 00710 clDsmUnsubscribeSIChanged_t unsubscribeSIChangeFunc; 00711 00712 /* -- notifyCarouselLoadEventFunc - optional (Null if not used) */ 00713 clDsmNotifyCarouselLoadEventFunc_t notifyCarouselLoadEventFunc; 00714 /* -- notifyObjectLoadEventFunc - optional (Null if not used) */ 00715 clDsmNotifyObjectLoadEventFunc_t notifyObjectLoadEventFunc; 00716 00717 /* notifyStreamEventFunc can be Null when Stream Events are not required */ 00718 clDsmNotifyStreamEventFunc_t notifyStreamEventFunc; 00719 00720 /* notifyDeferredServiceFunc can be Null when deferred service for Stream Objects are not required */ 00721 clDsmNotifyDeferredServiceFunc_t notifyDeferredServiceFunc; 00722 00723 /* -- Control flags */ 00724 00725 H_DsmControl dsmControl; 00726 /* 00727 -- Instance handle for external Service Information Query module 00728 */ 00729 H_SiqInstance siqInstance; /* -- Suggested default: Null */ 00730 00731 /* 00732 -- Instance handle for external Section Filter Manager module 00733 */ 00734 H_SfmInstance sfmInstance; /* -- Suggested default: Null */ 00735 00736 /* 00737 -- Pointer (optional) that can be used by calling environment for 00738 -- passing setup info to the memory manager (via clDsmMemMgr API) at 00739 -- memStart time. 00740 */ 00741 void* memMgrSetup; /* -- Suggested default: Null */ 00742 00743 00744 /* 00745 -- Specifies resolution of time units used on API in _milliseconds_ 00746 -- (can be set to resolution of external timers) 00747 -- 00748 -- NB. Time values are represented on the API and internally as U32BIT so 00749 -- timeUnitResolution should be chosen so that overflow problems will not 00750 -- occur during any likely period of continuous use for a receiver (eg. if 00751 -- timeUnitResolution = 10mS, wrap-round time = 1.36 years!). 00752 */ 00753 U32BIT timeUnitResolution; /* -- Suggested default: 10 */ 00754 00755 00756 /* 00757 -- Sets the size of dynamic memory available for DSM-CC to use. 00758 -- Apart from 100KB approx. the remainder of this memory will be requested 00759 -- and accessed via the dynamic memory manager API (clDsmMemMgrAPI.h). 00760 -- 00761 -- NB. In debug builds DSM-CC may allocate slightly (<5%) more than this 00762 -- specified amount. 00763 -- 00764 -- If clDsmMemMgrAPI is mapped to a system memory manager then it 00765 -- has an additional option (when it is opened) to decrease the amount 00766 -- of (the remainder of this) memory it makes available. 00767 */ 00768 U32BIT maxMemorySize; /* -- Absolute minimum: DSMCC_MINIMUM_CACHE_SIZE */ 00769 /* -- Recommended min: DSMCC_DEFAULT_CACHE_SIZE */ 00770 00771 /* 00772 -- Specifies the maximum number of section filters that are available 00773 -- in the calling environment (to this instance) for simultaneously 00774 -- acquiring DSM-CC private sections. 00775 -- 00776 -- If client requests (or other events) cause the core stack to 00777 -- simultaneously require more section filters than the number available 00778 -- it will rotate its requests through the available filters. This may 00779 -- cause delays in responding to client requests so the larger this 00780 -- number the better. 00781 -- 00782 -- The minimum value is NUM_SECTION_FILTERS_MINIMUM. 00783 -- Setting to zero will be interpreted as no restriction on the 00784 -- number of section filters available in the calling environment, and 00785 -- NUM_SECTION_FILTERS_MAXIMUM will be used. 00786 -- Setting to a value less than this the minimum will be ignored, and 00787 -- NUM_SECTION_FILTERS_MINIMUM will be used. 00788 -- Suggested Default: NUM_SECTION_FILTERS_DEFAULT 00789 */ 00790 U16BIT maxAvailableSectionFilters; 00791 00792 /* 00793 -- Sets whether DSM-CC component maintains an internal record 00794 -- of SI query results so that it does not need to repeatedly 00795 -- make the same SI queries (to the calling env). Typically this 00796 -- will be used for storing association_tag to PID mappings. 00797 */ 00798 BOOLEAN storeSIQueryResults; /* -- Default: FALSE */ 00799 00800 00801 /* 00802 -- Sets whether DSM-CC component pre-fetches modules into its 00803 -- internal cache. 00804 -- 00805 -- NB. This requires a large available memory size and a large number of 00806 -- available section filters. 00807 -- 00808 -- Enabling turboCaching also activates full transparent caching (ie. 00809 -- automatic re-loading of cached modules that have version updates). 00810 -- This is because turboCaching will not work effectively without this 00811 -- and also because only when turboCaching is enabled are there 00812 -- likely to be sufficient section filters available to support 00813 -- automatic module re-loading. 00814 */ 00815 BOOLEAN turboCaching; /* -- Default: FALSE */ 00816 00817 } clDsmSetup_t, *pclDsmSetup_t; 00818 00819 00820 00821 /*---Global variable declarations for public use-----------------------------*/ 00822 00823 00824 /****************************************** 00825 * EXPORTED (PROVIDED) FUNCTION PROTOTYPES * 00826 *******************************************/ 00827 00828 /* ---------------------- SYNCHRONOUS SYSTEM API CALLS ---------------------- */ 00829 00830 /* 00831 -- NOTES: 00832 -- 00833 -- The following functions must be called synchronously with each other and 00834 -- with the Synchronous Client API calls since they use and modify common 00835 -- instance data. If they need to be called/triggered from different threads 00836 -- the calling environment must ensure synchronous behaviour - eg. by using 00837 -- a mutex semaphore round the call (or queueing and calling from the same 00838 -- thread). 00839 -- 00840 -- In some circumstances it is possible to make one Synchronous API call from 00841 -- within another one: 00842 -- 00843 -- eg. clDsmSysProcessTimerEvent can be called within the stopTimerFunc 00844 -- callback which itself may have been called from within. 00845 -- clDsmSysProcessPrivateSection 00846 -- 00847 -- eg. All Synchronous Client API calls can be called from within the 00848 -- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks which may 00849 -- themselves have been called within clDsmSysProcessPrivateSection. 00850 -- 00851 -- These cases are clearly specified in the comments. The calling environment 00852 -- must avoid possible permanent blocks in these circumstances, eg. from trying 00853 -- to get a mutex on a thread that has it already. 00854 -- 00855 */ 00856 00857 00858 /******************************************************************************* 00859 * Create DSM-CC Core Layer instance 00860 * 00861 * Only call at startup of an instance (before ANY other DSM-CC Core Layer API 00862 * calls are made for that instance). Allocates all required 'static' memory 00863 * for the instance (via allocFunc). Also stores (copies) data supplied in 00864 * setup structure. 00865 * 00866 * NB. Dynamic (heap) memory used by the instance is allocated/deallocated and 00867 * accessed via the dynamic memory manager API (clDsmMemMgrApi.h). 00868 * 00869 * Returns instance value which is used to reference the unique data used by 00870 * this DSM Core instance. It MUST be stored by the calling environment and 00871 * passed to any clDsm API calls for the instance. 00872 * 00873 * Also returns memContext parameter (obtained when memory manager started). 00874 * If implemented/required, this gives the calling environment independent 00875 * access to the memory manager context used by this DSM Core instance. 00876 * 00877 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 00878 * allocFunc 00879 * freeFunc - only on error 00880 * 00881 * RETURNS: 00882 * CLDSM_OK (0) 00883 * CLDSM_ERR_ALLOC_FAILED, 00884 * CLDSM_ERR_MEM_HEAP_FULL 00885 * CLDSM_ERR_ILLEGAL_SETUP 00886 * 00887 *******************************************************************************/ 00888 clDsmErr_t clDsmSysCreate( 00889 /*I*/ pclDsmSetup_t pSetup, 00890 /*O*/ clDsmInstHandle_t *pInstance, void* *pMemContext ); 00891 00892 00893 00924 clDsmErr_t clDsmSysDestroy( clDsmInstHandle_t instance, 00925 H_SiqInstance *pSiqInst, H_SfmInstance *pSfmInst ); 00926 00927 00933 H_DsmControl clDsmSysGetControl( clDsmInstHandle_t instance ); 00934 00935 00973 clDsmErr_t clDsmSysReset( clDsmInstHandle_t instance, E_DsmRstMode mode ); 00974 00980 void clDsmSysSetMemoryMax( clDsmInstHandle_t instance, U32BIT maxMemory ); 00981 01013 clDsmErr_t clDsmSysSetCurrService( clDsmInstHandle_t instance, 01014 /*I*/ U16BIT original_network_id, U16BIT transport_stream_id, 01015 U16BIT service_id ); 01016 01017 U16BIT clDsmSysCurrServiceId( clDsmInstHandle_t instance ); 01018 01019 01045 clDsmErr_t clDsmSysProcessTimerEvent( clDsmInstHandle_t instance, 01046 /*I*/ void* clDsmTmrUserData, clDsmTimerEventStatus_t status, void* timerHandle ); 01047 01048 01049 01090 clDsmErr_t clDsmSysProcessSIQueryEvent( clDsmInstHandle_t instance, 01091 /*I*/ clDsmSIQueryRef_t clDsmSIQueryRef, void* clDsmSIUserData, 01092 pclDsmSIQueryResult_t pResult ); 01093 01094 01095 01131 clDsmErr_t clDsmSysProcessSIChangeEvent( clDsmInstHandle_t instance, 01132 /*I*/ clDsmSIChangeEvent_t event, U16BIT service_id, U32BIT carousel_id ); 01133 01134 01135 01136 /******************************************************************************* 01137 * Process DSM-CC private section data 01138 * 01139 * NOTES: 01140 * 01141 * Call each time the Demux provides a private section from one of the 01142 * requested PIDs (main TS data input of DSM-CC Core API). 01143 * 01144 * It is assumed that the calling environment has already CRC checked the 01145 * section (if relevant) and only sections that pass this check will be 01146 * supplied to clDsmSysProcessPrivateSection. 01147 * 01148 * The clDsmFilterRef and clDsmSfUserData inputs MUST be set to the values 01149 * supplied when the filter for this section was requested 01150 * (via addSectionFilterFunc). 01151 * 01152 * If sections have to be queued (or discarded) in the calling environment 01153 * then those matching filters with a high priority MUST always be supplied 01154 * to this function in preference to those matching low priority filters. 01155 * 01156 * NB. Although sections matching low priority filters (or even high priority 01157 * filters) can be discarded if necessary. The order in which they were 01158 * broadcast should always be maintained when they are supplied to this 01159 * function. 01160 * 01161 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01162 * errorFunc 01163 * progressFunc 01164 * addSectionFilterFunc 01165 * delSectionFilterFunc 01166 * stopTimerFunc 01167 * startSIQueryFunc 01168 * notifyCarouselLoadEventFunc 01169 * notifyObjectLoadEventFunc 01170 * 01171 * RETURNS: 01172 * CLDSM_OK (0) 01173 * CLDSM_ERR_INVALID_INSTANCE 01174 * CLDSM_ERR_ILLEGAL_PARAMETER 01175 * CLDSM_ERR_ABORTED When dsmFilterRef is not recognised (maybe stale) 01176 * 01177 *******************************************************************************/ 01178 clDsmErr_t clDsmSysProcessPrivateSection( clDsmInstHandle_t instance, 01179 /*I*/ U8BIT* pSection, clDsmSFRef_t dsmFilterRef ); 01180 01181 01182 /******************************************************************************* 01183 * Request priority for DSM-CC private section data 01184 * 01185 *******************************************************************************/ 01186 clDsmErr_t clDsmSectionFilterPriority( clDsmInstHandle_t instance, 01187 clDsmSFRef_t dsmFilterRef, 01188 clDsmSFPriority_t *pPriority ); 01189 01190 01191 /* ---------------------- SYNCHRONOUS CLIENT API CALLS ---------------------- */ 01192 01193 /* 01194 -- NOTES: 01195 -- 01196 -- The following functions must be called synchronously with each other and 01197 -- with the above System API calls. If they need to be called/triggered 01198 -- from different threads the calling environment must ensure synchronous 01199 -- behaviour - eg. by using a mutex semaphore round the call (or queueing and 01200 -- calling from the same thread). 01201 -- 01202 -- Any of the Synchronous (or Asynchronous) Client API calls (ie. API 01203 -- calls that do NOT start with clDsmSys...) can be made from within the 01204 -- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks. When doing 01205 -- this, care must be taken to avoid blocking or re-entrancy problems in 01206 -- the calling environment. Re-entrancy may occur when unloading objects or 01207 -- carousels since this can cause a (re-entrant) call to these callbacks. 01208 -- 01209 */ 01210 01211 01212 /* -- CAROUSEL LOAD FUNCS -- */ 01213 01214 /******************************************************************************* 01215 * 01216 * Loads DSM-CC object carousel specified by carousel_id from indicated service 01217 * (on the current multiplex/transport stream) 01218 * 01219 * If carousel_id is set to INVALID_CAROUSEL_ID, then this function loads the 01220 * initiate boot carousel for the service 01221 * 01222 * NOTES: 01223 * 01224 * The returned clDsmCarouselHandle value must always be supplied by the 01225 * calling environment whenever accessing objects in this carousel. 01226 * 01227 * Initially a section filter will be set up to acquire the DSI message for the 01228 * carousel. Once the DSI message is acquired the calling environment is 01229 * notified via the notifyCarouselLoadEventFunc callback (if supplied at 01230 * setup/create) that the carousel is BOOTED. Open object requests can then be 01231 * made for this carousel. 01232 * 01233 * When the service gateway (SRG) is loaded for this carousel the calling 01234 * environment is notified again via the callback that the carousel is now 01235 * LOADED. Objects in the carousel cannot be accessed (opened) until the 01236 * service gateway for the carousel is loaded. 01237 * 01238 * If timeout occurs before the SRG is loaded a timeout error is returned. If 01239 * an error is encountered while loading the carousel then an aborted error is 01240 * returned. 01241 * 01242 * Using the ocLoadUserData1 and ocLoadUserData2 values is optional. These 01243 * values are returned unchecked into the load event callback. They can be used 01244 * for any purpose (eg. to aid in matching callbacks with corresponding load 01245 * requests and/or clients). 01246 * 01247 * If timeout value is set to zero it means no (ie. infinite) timeout. 01248 * 01249 * If a duplicate request is made to load a boot carousel then an error will be 01250 * generated but the clDsmCarouselHandle will be set to the value of the already 01251 * loaded carousel. 01252 * 01253 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01254 * startTimerFunc 01255 * startSIQueryFunc 01256 * addSectionFilterFunc 01257 * 01258 * RETURNS: 01259 * CLDSM_OK (0) 01260 * CLDSM_DUPLICATE_REQUEST 01261 * CLDSM_ERR_MEM_HEAP_FULL 01262 * CLDSM_ERR_NO_CURRENT_SERVICE_SET 01263 * ? 01264 * 01265 *******************************************************************************/ 01266 clDsmErr_t clDsmLoadCarousel( clDsmInstHandle_t instance, 01267 /*I*/ U16BIT service_id, U32BIT carousel_id, U32BIT timeout, 01268 /*O*/ E_OCLoadStatus *pStatus, clDsmOCHandle_t *pclDsmCarouselHandle ); 01269 01270 01271 01272 01313 clDsmErr_t clDsmUnloadCarousel( clDsmInstHandle_t instance, 01314 /*I*/ clDsmOCHandle_t clDsmCarouselHandle, E_DsmRstMode mode ); 01315 01325 clDsmErr_t clDsmGetCarouselId( clDsmInstHandle_t instance, 01326 /*I*/ clDsmOCHandle_t carouselHandle, 01327 /*O*/ U32BIT* pCarouselId ); 01328 01334 clDsmOCHandle_t clDsmCurrentCarousel( clDsmInstHandle_t instance ); 01335 01344 clDsmErr_t clDsmSetCurrentCarousel( clDsmInstHandle_t instance, 01345 /*I*/ clDsmOCHandle_t carouselHandle ); 01346 01358 clDsmErr_t clDsmCarouselLoadFileGroups( clDsmInstHandle_t instance, 01359 /*I*/ clDsmOCHandle_t clDsmCarouselHandle, 01360 /*O*/ U16BIT* total, S_CarouselInfoFileGroup** pGroups ); 01361 01374 clDsmErr_t clDsmCarouselUnloadFileGroups( clDsmInstHandle_t instance, 01375 /*I*/ clDsmOCHandle_t clDsmCarouselHandle, 01376 /*I*/ S_CarouselInfoFileGroup *groups ); 01377 01378 /* -- OBJECT LOAD FUNCS -- */ 01379 01380 /******************************************************************************* 01381 * 01382 * Load an object with the requested pathname into cache. 01383 * 01384 * Unless the carousel is specifed in the path, this will load an object from 01385 * the 'Current' object carousel. The client may specify another carousel by 01386 * setting the 'Current' object carousel with use of clDsmSetCurrentCarousel(). 01387 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"), 01388 * then the function will attempt to load this carousel and make it the new 01389 * 'Current' object carousel. 01390 * 01391 * NOTES: 01392 * 01393 * Currently, an object can only be loaded once the carousel is booted (DSI 01394 * message acquired). 01395 * 01396 * Requested pathname must be a full (absolute) object pathname starting with 01397 * an object in the root (ie. service gateway) directory of the specified 01398 * carousel, eg. dir1/dir2/file3 is treated as DSM:/dir1/dir1/file3. Any 01399 * characters defined in PATH_SEPERATOR_LIST_STRING will be treated as path 01400 * token seperators all other chars are treated as part of a path token. An 01401 * empty pathname U8BIT* (or U8BIT* containing only path token seperators) 01402 * will open the service gateway directory itself. 01403 * 01404 * **** NB. SRG (& directory) ACCESS NOT YET IMPLEMENTED **** 01405 * 01406 * Returns an clDsmObjectHandle which the client uses to access the requested 01407 * object. If the object is already cached then the status parameter will be 01408 * set to OBJ_LOAD_COMPLETED. In this case the objectRef value can be used to 01409 * access (eg. open for reading) the object/file data immediately. 01410 * 01411 * If the object is not in the cache then a fetch from the input stream is 01412 * initiated and the status parameter set to OBJ_LOAD_IN_PROGRESS. When the 01413 * object is loaded into the cache the calling environment is notified via the 01414 * notifyObjectlLoadEventFunc callback (if supplied at setup/create). 01415 * 01416 * Using the objLoadUserData1 and objLoadUserData2 values is optional. These 01417 * values are returned unchecked into the load event callback. They can be used 01418 * for any purpose (eg. to aid in matching callbacks with corresponding load 01419 * requests and/or clients). 01420 * 01421 * If multiple load requests are made for the same object before it is 01422 * available each request will initiate a new (parallel) fetch from the input 01423 * stream and a callback will be generated for each request when the object is 01424 * loaded. 01425 * 01426 * While an object is LOADED it's contents are guaranteed to remain available 01427 * and constant in cache memory (ie. it will not be updated from the input 01428 * stream or deleted to create space in the cache). 01429 * 01430 * Any load request for an object (that is not already loaded) will only get 01431 * completed by a call to clDsmysProcessPrivateSection. This will either have 01432 * delivered the last part of the module containing the object or delivered a 01433 * module containing a previously missing higher level directory in the object 01434 * path that results in the requested object now being accessible in the cache. 01435 * 01436 * If a load proceeds part way down a path and then encounters an error, the 01437 * load is aborted and the appropriate status returned via the callback. The 01438 * clDsmObjectHandle cannot be used to access object/file DATA until/unless 01439 * it is successfully loaded. 01440 * 01441 * **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED **** 01442 * If caching rules are specified they are applied as below. If pCachingRules 01443 * is set to Null the object will be given the default caching rules. 01444 * 01445 * If the object is not in the cache then the caching rules only have an 01446 * effect on the subsequent caching of the object/module once the object load 01447 * is completed and the object is actually unloaded (via clDsmUnloadObject), 01448 * ie. when it is made available for caching. 01449 * 01450 * If the same object is requested multiple times in parallel, then once the 01451 * object load is completed the highest priority caching rules are selected 01452 * (fromStream overrides any other settings). These are applied only when 01453 * the last of the object load instances is unloaded. 01454 * 01455 * If the requested object is already in the cache and the caching rules have 01456 * fromStream set, then the object/module is immediately deleted from the cache 01457 * and a new fetch from the input stream is initiated. 01458 * 01459 * If the same object is loaded multiple times in parallel then the caching 01460 * rules specified at each load call will only replace the currently set 01461 * caching rules for this object if they specify a higher caching priority 01462 * (fromStream overrides any priority setting). If fromStream is set on any 01463 * load then it will cause a re-fetch of the object for that load instance. 01464 * The data for any previous load instances will only get physically deleted 01465 * when they are unloaded. 01466 * 01467 * NB. For module based caching (as currently implemented) the whole module 01468 * inherits the caching rules MOST RECENTLY SPECIFIED for any object in that 01469 * module. 01470 * 01471 * The rules for when multiple objects from the same module are requested (or 01472 * loaded) in parallel are applied to a module on the same basis as described 01473 * for multiple instances of the same object. 01474 * 01475 * **** NOT YET IMPLEMENTED **** 01476 * If timeout value is set to zero it means no (ie. infinite) timeout. If a 01477 * timeout is specified and the object has not been loaded in the specified 01478 * time (for any reason) then the load request is aborted and the client 01479 * notified. Timeout is expressed in periods of timerResolution (specified at 01480 * setup/create). 01481 * 01482 * 01483 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01484 * addSectionFilterFunc 01485 * startTimerFunc 01486 * startSIQueryFunc 01487 * 01488 * RETURNS: 01489 * CLDSM_OK (0) 01490 * CLDSM_ERR_MEM_HEAP_FULL 01491 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE 01492 * CLDSM_ERR_INVALID_CACHING_RULES 01493 * CLDSM_ERR_CAROUSEL_NOT_BOOTED 01494 * 01495 * CLDSM_ERR_INVALID_PATHNAME - Null pointer or path too long 01496 * 01497 * CLDSM_ERR_LOAD_FAILURE - Failed to load requested file (because 01498 * some part of path could not be located) 01499 * +? 01500 * 01501 *******************************************************************************/ 01502 clDsmErr_t clDsmLoadObject( clDsmInstHandle_t instance, 01503 /*I*/ U8BIT* pathname, U32BIT timeout, clDsmCachingRules_t cachingRules, 01504 H_ObjUserData pUserData, U32BIT sizeOfUserData, 01505 /*O*/ clDsmObjLoadStatus_t *pStatus, clDsmObjHandle_t *pclDsmObjectHandle ); 01506 01507 01508 01567 clDsmErr_t clDsmUnloadObject( clDsmInstHandle_t instance, 01568 /*I*/ clDsmObjHandle_t clDsmObjectHandle, E_DsmRstMode mode ); 01569 01570 01597 clDsmErr_t clDsmOpenObject( 01598 /*I*/ clDsmInstHandle_t instance, 01599 /*I*/ clDsmObjHandle_t clDsmObjectHandle, 01600 /*O*/ clDsmObjectKind_t *pKind ); 01601 01602 01603 01604 01605 /******************************************************************************* 01606 * Close a loaded object 01607 * 01608 * NOTES: 01609 * 01610 * Closes the loaded object data. If an object is open this must be called 01611 * before it can be unloaded (via clDsmUnloadObject). 01612 * 01613 * 01614 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01615 * none 01616 * 01617 * RETURNS: 01618 * CLDSM_OK (0) 01619 * CLDSM_ERR_INVALID_OBJECT_HANDLE 01620 * CLDSM_ERR_OBJECT_NOT_LOADED 01621 * CLDSM_ERR_OBJECT_NOT_OPEN 01622 * ? 01623 * 01624 *******************************************************************************/ 01625 clDsmErr_t clDsmCloseObject( clDsmInstHandle_t instance, 01626 /*I*/ clDsmObjHandle_t clDsmObjectHandle ); 01627 01628 01634 clDsmInstHandle_t clDsmObjectGetInstance(clDsmObjHandle_t clDsmObjectHandle); 01635 01636 01637 /******************************************************************************* 01638 * **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED **** 01639 * 01640 * Set caching rules for any (cached) object. 01641 * 01642 * Unless the carousel is specifed in the path, this will load an object from 01643 * the 'Current' object carousel. The client may specify another carousel by 01644 * setting the 'Current' object carousel with use of clDsmSetCurrentCarousel(). 01645 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"), 01646 * then the function will attempt to load this carousel and make it the new 01647 * 'Current' object carousel. 01648 * 01649 * NOTES: 01650 * 01651 * If the object (OR ANY DIRECTORY ON THE PATH TO THE OBJECT) is not found in 01652 * the cache this command is ignored. Object load failure problems detected at 01653 * call time are not indicated. 01654 * 01655 * If the object is located in the cache the new caching rules are applied 01656 * immediately. If fromStream is set the object is deleted from the cache. 01657 * 01658 * If the object is found in the cache but it is currently loaded the current 01659 * caching rules for this object are set to the specified values (whatever they 01660 * were previously). If fromStream is set, the current object load instance is 01661 * marked for deletion, ie. it is no longer available to subsequent loads 01662 * (although the data is only physically deleted when the object is unloaded 01663 * via clDsmUnloadObject). 01664 * 01665 * Other caching rules are only applied when the object is unloaded. 01666 * If the same object is loaded multiple times in parallel, then these caching 01667 * rules are applied when the last of the object load instances is unloaded. 01668 * Any caching rules set by this call may get overriden if a subsequent parallel 01669 * load of the object that specifies higher priority caching rules is made. 01670 * 01671 * NB. For module based caching (as currently implemented) the whole module 01672 * inherits the caching rules MOST RECENTLY SPECIFIED for any object in that 01673 * module. 01674 * 01675 * The rules for when multiple objects from the same module are requested (or 01676 * loaded) in parallel are applied to a module on the same basis as described 01677 * for multiple instances of the same object. 01678 * 01679 * 01680 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01681 * delSectionFilterFunc 01682 * 01683 * RETURNS: 01684 * CLDSM_OK (0) 01685 * CLDSM_ERR_INVALID_PATHNAME 01686 * CLDSM_ERR_INVALID_CACHING_RULES 01687 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE 01688 * CLDSM_ERR_CAROUSEL_NOT_BOOTED 01689 * CLDSM_ERR_CAROUSEL_LOAD_FAILED 01690 * ? 01691 * 01692 *******************************************************************************/ 01693 clDsmErr_t clDsmSetObjectCachingRules( clDsmInstHandle_t instance, 01694 /*I*/ U8BIT* pathname, clDsmCachingRules_t cachingRules ); 01695 01696 01697 01698 /******************************************************************************* 01699 * 01700 * Request pre-fetch into cache of the specified object. 01701 * 01702 * Unless the carousel is specifed in the path, this will load an object from 01703 * the 'Current' object carousel. The client may specify another carousel by 01704 * setting the 'Current' object carousel with use of clDsmSetCurrentCarousel(). 01705 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"), 01706 * then the function will attempt to load this carousel and make it the new 01707 * 'Current' object carousel. 01708 * 01709 * NOTES: 01710 * 01711 * The pre-fetch is always 'silent', ie. no notification is given when (or 01712 * whether) the object has been pre-fetched into the cache (ie. object load 01713 * failure errors detected at start time are also not indicated). If the object 01714 * is already in the cache then the pre-fetch request is ignored. 01715 * 01716 * Pre-fetches work like load requests (ie. they are always performed) but 01717 * if necessary, load requests (clDsmLoadObject) have priority on section filter 01718 * resources. 01719 * 01720 * If the object has to be fetched into the cache then it is given the default 01721 * caching rules (nb. fromStream is not set!). 01722 * 01723 * **** NOT YET IMPLEMENTED **** 01724 * If timeout value is set to zero it means no (ie. infinite) timeout. If a 01725 * timeout is specified and the object has not been pre-fetched in the specified 01726 * time (for any reason) then the pre-fetch request is abandoned (silently). 01727 * Timeout is expressed in periods of timerResolution (specified at 01728 * setup/create). 01729 * 01730 * 01731 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: 01732 * addSectionFilterFunc 01733 * startTimerFunc 01734 * startSIQueryFunc 01735 * 01736 * RETURNS: 01737 * CLDSM_OK (0) 01738 * CLDSM_ERR_MEM_HEAP_FULL 01739 * CLDSM_ERR_INVALID_PATHNAME 01740 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE 01741 * CLDSM_ERR_CAROUSEL_NOT_BOOTED 01742 * CLDSM_ERR_CAROUSEL_LOAD_FAILED 01743 * ? 01744 * 01745 *******************************************************************************/ 01746 clDsmErr_t clDsmPrefetchObject( clDsmInstHandle_t instance, 01747 /*I*/ U8BIT* pathname, U32BIT timeout ); 01748 01749 01750 01796 clDsmErr_t clDsmStreamEventSubscribe( 01797 /*I*/ clDsmInstHandle_t dsmccInstance, 01798 /*I*/ clDsmObjHandle_t streamObject, 01799 /*I*/ U8BIT* eventName, 01800 /*I*/ void* userData1, 01801 /*I*/ void* userData2, 01802 /*O*/ H_DsmEvent* pEventHandle ); 01803 01804 01820 clDsmErr_t clDsmStreamEventUnsubscribe( 01821 /*I*/ clDsmInstHandle_t dsmccInstance, 01822 /*I*/ H_DsmEvent eventHandle ); 01823 01824 01861 clDsmErr_t clDsmSpecialEventSubscribe( 01862 /*I*/ clDsmInstHandle_t dsmccInstance, 01863 /*I*/ U16BIT associationTag, 01864 /*I*/ U16BIT eventId, 01865 /*I*/ void* userData1, 01866 /*I*/ void* userData2, 01867 /*O*/ H_DsmEvent* pEventHandle ); 01868 01869 01882 clDsmErr_t clDsmSpecialEventUnsubscribe( 01883 /*I*/ clDsmInstHandle_t dsmccInstance, 01884 /*I*/ H_DsmEvent eventHandle ); 01885 01886 01887 01888 /* ---------------------- ASYNCHRONOUS CLIENT API CALLS --------------------- */ 01889 01890 /* 01891 -- NOTES: 01892 -- 01893 -- These functions can always be called asynchronously (ie. from a different 01894 -- task/thread) since they can only access an individual object/file data area 01895 -- which must have first been opened (& locked) by a previous synchronous API 01896 -- call. 01897 -- 01898 */ 01899 01900 01901 /******************************************************************************* 01902 * Get specified object kind (also returned by clDsmOpenObject) 01903 * 01904 * The object (clDsmObjectHandle) must be LOADED. 01905 * 01906 * NB. This can also be called to poll for when an object is loaded. 01907 * 01908 * RETURNS: 01909 * CLDSM_OK (0) 01910 * CLDSM_ERR_INVALID_OBJECT_HANDLE 01911 * CLDSM_ERR_OBJECT_NOT_LOADED 01912 * 01913 *******************************************************************************/ 01914 clDsmErr_t dsmObjectGetKind( 01915 /*I*/ clDsmObjHandle_t clDsmObjectHandle, 01916 /*O*/ clDsmObjectKind_t *pKind ); 01917 01918 01919 01920 /******************************************************************************* 01921 * Get specified object carousel handle. 01922 * 01923 * The object (clDsmObjectHandle) must be LOADED. 01924 * 01925 * NB. This can also be called to poll for when an object is loaded. 01926 * 01927 * RETURNS: 01928 * CLDSM_OK (0) 01929 * CLDSM_ERR_INVALID_OBJECT_HANDLE 01930 * CLDSM_ERR_INVALID_OBJECT_TYPE 01931 * CLDSM_ERR_OBJECT_NOT_LOADED 01932 * 01933 *******************************************************************************/ 01934 clDsmErr_t dsmObjectGetCarouselHandle( 01935 /*I*/ clDsmObjHandle_t clDsmObjectHandle, 01936 /*O*/ void* *hCarouselHandle ); 01937 01938 01939 01940 /* -- SERVICE GATEWAY ACCESS FUNCS -- */ 01941 01942 01943 01977 clDsmErr_t dsmGetObjectServiceContext( 01978 /*I*/ clDsmObjHandle_t clDsmObjectHandle, 01979 /*I*/ U32BIT serviceId, 01980 /*O*/ U8BIT** pSrvCtxtData, 01981 /*O*/ U32BIT* pSrvCtxtLen); 01982 01983 01984 /* -- FILE OBJECT ACCESS FUNCS -- */ 01985 01986 /******************************************************************************* 01987 * Get length of specified file data 01988 * 01989 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. 01990 * 01991 * RETURNS: 01992 * CLDSM_OK (0) 01993 * CLDSM_ERR_INVALID_OBJECT_HANDLE 01994 * CLDSM_ERR_INVALID_OBJECT_TYPE 01995 * CLDSM_ERR_OBJECT_NOT_LOADED 01996 * CLDSM_ERR_OBJECT_NOT_OPEN 01997 * ? 01998 * 01999 *******************************************************************************/ 02000 clDsmErr_t dsmFileGetSize( 02001 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, 02002 /*O*/ U32BIT *pSize ); 02003 02004 02005 02006 /******************************************************************************* 02007 * Read specified number of bytes of data from (opened) file into 02008 * destination address, starting at the current 'cursor' ('file' ptr) position. 02009 * 02010 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The 02011 * destination memory area MUST be large enough to hold the numBytes requested. 02012 * 02013 * If call attempts to read past end of the file data it will read as many 02014 * bytes as possible and returns error code: CLDSM_ERR_END_OF_DATA 02015 * 02016 * Number of bytes read is stored in pNumBytesActual and 'cursor' position is 02017 * incremented by numBytesActual. 02018 * 02019 * RETURNS: 02020 * CLDSM_OK (0) 02021 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02022 * CLDSM_ERR_INVALID_OBJECT_TYPE 02023 * CLDSM_ERR_OBJECT_NOT_LOADED 02024 * CLDSM_ERR_OBJECT_NOT_OPEN 02025 * CLDSM_ERR_END_OF_DATA 02026 * ? 02027 * 02028 *******************************************************************************/ 02029 clDsmErr_t clDsmFileRead( 02030 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, U32BIT numBytes, 02031 /*O*/ U8BIT *pDest, U32BIT *pNumBytesActual ); 02032 02033 /******************************************************************************* 02034 * Returns pointer to file data and number of bytes in the file. 02035 * 02036 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The 02037 * destination memory area MUST be large enough to hold the numBytes requested. 02038 * 02039 * Number of bytes read is stored in pNumBytesActual. 02040 * 02041 * RETURNS: 02042 * CLDSM_OK (0) 02043 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02044 * CLDSM_ERR_OBJECT_NOT_LOADED 02045 * 02046 *******************************************************************************/ 02047 clDsmErr_t clDsmFileDirect( 02048 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, 02049 /*O*/ U8BIT **ppDest, U32BIT *pNumBytesActual ); 02050 02051 02052 /******************************************************************************* 02053 * Read single byte of data from (opened) file at current 'cursor' position 02054 * into destination and increment 'cursor' position. 02055 * 02056 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. 02057 * 02058 * If call attempts to read past end of the object data, returns error code: 02059 * CLDSM_ERR_END_OF_DATA 02060 * 02061 * RETURNS: 02062 * CLDSM_OK (0) 02063 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02064 * CLDSM_ERR_INVALID_OBJECT_TYPE 02065 * CLDSM_ERR_OBJECT_NOT_LOADED 02066 * CLDSM_ERR_OBJECT_NOT_OPEN 02067 * CLDSM_ERR_END_OF_DATA 02068 * ? 02069 * 02070 *******************************************************************************/ 02071 clDsmErr_t dsmFileReadByte( 02072 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, 02073 /*O*/ U8BIT *pDest ); 02074 02075 02076 02077 /******************************************************************************* 02078 * Set absolute file data 'cursor' position 02079 * 02080 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. 02081 * 02082 * Cursor can point to any byte in file data AND to notional 'position' 02083 * immediately after last byte of data but setting to anywhere else will return 02084 * error code: CLDSM_ERR_END_OF_DATA 02085 * 02086 * RETURNS: 02087 * CLDSM_OK (0) 02088 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02089 * CLDSM_ERR_INVALID_OBJECT_TYPE 02090 * CLDSM_ERR_OBJECT_NOT_LOADED 02091 * CLDSM_ERR_OBJECT_NOT_OPEN 02092 * CLDSM_ERR_END_OF_DATA 02093 * ? 02094 * 02095 *******************************************************************************/ 02096 clDsmErr_t dsmFileSetPosAbs( 02097 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, U32BIT absPosition ); 02098 02099 02100 02101 /******************************************************************************* 02102 * Set file data 'cursor' position relative to current position 02103 * 02104 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. 02105 * 02106 * Cursor can point to any byte in file data AND to notional 'position' 02107 * immediately after last byte of data but setting to anywhere else will return 02108 * error code: CLDSM_ERR_END_OF_DATA 02109 * 02110 * RETURNS: 02111 * CLDSM_OK (0) 02112 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02113 * CLDSM_ERR_INVALID_OBJECT_TYPE 02114 * CLDSM_ERR_OBJECT_NOT_LOADED 02115 * CLDSM_ERR_OBJECT_NOT_OPEN 02116 * CLDSM_ERR_END_OF_DATA 02117 * ? 02118 * 02119 *******************************************************************************/ 02120 clDsmErr_t dsmFileSetPosRel( 02121 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, S32BIT relPosition ); 02122 02123 02124 02125 /******************************************************************************* 02126 * Read (absolute) file data 'cursor' position 02127 * 02128 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. 02129 * 02130 * Value returned in 'position' is the offset (in bytes) from the start (zero 02131 * position) of the file data to the current cursor position. 02132 * 02133 * If the current cursor position points to past the end of the file data, then 02134 * the position returned is equal to the file data size. Note that it is not 02135 * legal to _read_ data from this cursor position/offset. 02136 * 02137 * RETURNS: 02138 * CLDSM_OK (0) 02139 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02140 * CLDSM_ERR_INVALID_OBJECT_TYPE 02141 * CLDSM_ERR_OBJECT_NOT_LOADED 02142 * CLDSM_ERR_OBJECT_NOT_OPEN 02143 * ? 02144 * 02145 *******************************************************************************/ 02146 clDsmErr_t dsmFileGetPos( 02147 /*I*/ clDsmObjHandle_t clDsmFileObjectHandle, 02148 /*O*/ U32BIT *pPosition ); 02149 02150 02151 /* -- DIRECTORY ACCESS FUNCS -- */ 02152 02153 /******************************************************************************* 02154 * 02155 * The directory object (dirObj) must be LOADED and OPEN. 02156 * 02157 * Retrieves the total number of directory entries and the total length of all 02158 * entry names. 02159 * 02160 * RETURNS: 02161 * CLDSM_OK (0) 02162 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02163 * CLDSM_ERR_INVALID_OBJECT_TYPE 02164 * CLDSM_ERR_OBJECT_NOT_LOADED 02165 * CLDSM_ERR_OBJECT_NOT_OPEN 02166 * 02167 *******************************************************************************/ 02168 clDsmErr_t dsmDirEntrySizes( 02169 /*I*/ clDsmObjHandle_t dirObj, 02170 /*O*/ U16BIT *nameCount, 02171 /*O*/ U16BIT *totalNameLength ); 02172 02173 /******************************************************************************* 02174 * 02175 * The directory object must be LOADED and OPEN. 02176 * 02177 * Retrieve the first entry handle 02178 * 02179 * RETURNS: 02180 * CLDSM_OK (0) 02181 * CLDSM_ERR_INVALID_OBJECT_HANDLE 02182 * CLDSM_ERR_INVALID_OBJECT_TYPE 02183 * CLDSM_ERR_OBJECT_NOT_LOADED 02184 * CLDSM_ERR_OBJECT_NOT_OPEN 02185 * CLDSM_ERR_END_OF_DATA 02186 * 02187 *******************************************************************************/ 02188 clDsmErr_t dsmDirEntryFirst( 02189 /*I*/ clDsmObjHandle_t dirObj, 02190 /*O*/ void** pFirstEntry ); 02191 02192 /******************************************************************************* 02193 * 02194 * Directory entry handle (entryHandle) is return by dsmDirEntryFirst or 02195 * dsmDirEntryNext. 02196 * 02197 * Retrieve the next entry handle 02198 * 02199 * RETURNS: 02200 * CLDSM_OK (0) 02201 * CLDSM_ERR_INTERNAL 02202 * 02203 *******************************************************************************/ 02204 clDsmErr_t dsmDirEntryNext( 02205 /*I*/ void* entryHandle, 02206 /*O*/ void** pNextEntry ); 02207 02208 /******************************************************************************* 02209 * 02210 * The directory entry handle is return by dsmDirEntryFirst or 02211 * dsmDirEntryNext. 02212 * 02213 * Retrieve name length 02214 * 02215 * RETURNS: 02216 * Length of name copied 02217 * 02218 *******************************************************************************/ 02219 U16BIT dsmDirEntryNameLength( 02220 /*I*/ void* entryHandle ); 02221 02222 /******************************************************************************* 02223 * 02224 * The directory entry handle is return by dsmDirEntryFirst or 02225 * dsmDirEntryNext. 02226 * 02227 * Copy name for entry to supplied memory location (pName) 02228 * Caller should ensure there is enough space in location 02229 * 02230 * RETURNS: 02231 * Length of name copied 02232 * 02233 *******************************************************************************/ 02234 U16BIT dsmDirEntryNameCopy( 02235 /*I*/ void* entryHandle, 02236 /*O*/ U8BIT *pName ); 02237 02238 /******************************************************************************* 02239 * 02240 * Get the kind of entry this is 02241 * 02242 * RETURNS: 02243 * clDsmObjectKind_t 02244 * 02245 *******************************************************************************/ 02246 clDsmObjectKind_t dsmDirEntryKind( void* entryHandle ); 02247 02248 02249 /* -- STREAM OBJECT ACCESS FUNCS -- */ 02250 02276 clDsmErr_t dsmStreamGetProgramAssocTag( 02277 /*I*/ clDsmObjHandle_t streamObjectHandle, 02278 /*O*/ U16BIT* pAssociation_tag); 02279 02280 02311 clDsmErr_t clDsmStreamGetDeferredService( clDsmInstHandle_t instance, 02312 /*I*/ clDsmObjHandle_t streamObject, void* userData1, void* userData2, 02313 /*O*/ S_DvbLocator **ppDeferredService ); 02314 02315 /* -- STREAM EVENT ACCESS FUNCS -- */ 02316 02343 clDsmErr_t clDsmStreamEventNameList( 02344 /*I*/ clDsmInstHandle_t dsmccInstance, 02345 /*I*/ clDsmObjHandle_t streamObject, 02346 /*O*/ U8BIT **pNamesPtr, U16BIT *pNamesLen ); 02347 02348 02349 /*----------------------------------------------------------------------------*/ 02350 02351 #ifdef __cplusplus 02352 } 02353 #endif 02354 #endif /* _DSMCC_H_ */ 02355