DSMCC  22.11.0
cldsmcc.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
3  * Copyright © 2004 Ocean Blue Software Ltd
4  * Copyright © 2000 Koninklijke Philips Electronics N.V
5  *
6  * This file is part of a DTVKit Software Component
7  * You are permitted to copy, modify or distribute this file subject to the terms
8  * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
9  *
10  * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
11  * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
12  * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
13  *
14  * If you or your organisation is not a member of DTVKit then you have access
15  * to this source code outside of the terms of the licence agreement
16  * and you are expected to delete this and any associated files immediately.
17  * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
18  *******************************************************************************/
27 /*
28  * DVB DSM-CC Object Carousel Core Layer API
29  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30  *
31  * OVERVIEW:
32  *
33  * This API has been specified in standard ANSI C and is designed as a completely
34  * OS and Platform (ie. HW and SW driver) independent interface to the core
35  * DSM-CC layer.
36  *
37  * To avoid confusion over the sizes of standard C types on different platforms, it
38  * assumes that a standard set of unambiguous type names have been defined to
39  * platform specific types in the file clDsmPlatformAPI.h (also standard
40  * definitions for TRUE/FALSE/Null). NB. This currently matches the recommended DVP
41  * coding standards.
42  *
43  *
44  * DSM-CC code conforming to this API should be readily portable to any platform
45  * and OS environment. It assumes that this environment (designated 'the
46  * calling environment') can provide the following:
47  *
48  * - Filtering of MPEG2 private sections from a single transport stream on multiple
49  * simultaneous PID values and section filter values.
50  *
51  * - Acquisition and parsing of PMT(s) for specified program stream, query/lookup
52  * of specific information from the SI data
53  *
54  * - Basic block memory allocation and de-allocation (at startup and shutdown)
55  *
56  * - Semaphore or queuing mechanisms for synchronising API calls initiated by
57  * asynchronously running tasks or threads
58  *
59  * - Queuing mechanisms, eg. for notifying clients of asynchronous object loads
60  *
61  * - Multiple timers (eg. 10mS resolution)
62  *
63  * - Dynamic (heap) memory management that conforms to the API specified in
64  * clDsmMemMgrApi.h
65  *
66  * NB. A non-fragmenting linked-block based memory manager that conforms to this
67  * API is supplied along with the DSM-CC core stack (clDsmMemMgrBlock.c).
68  *
69  *
70  * It is intended that all platform (and DSM-CC profile) specific functions
71  * including handling of multiple clients/apps (if required) are implemented in
72  * wrapper layers that call into this API. Only these layers should need to
73  * be modified when porting to a new platform (or DSM-CC profile).
74  *
75  *
76  * BASIC DATA FLOW AND LAYERS:
77  *
78  * +-----------+ +-----load/unload-----------------+
79  * | DEMUX & | DSM-CC | carousel |
80  * TS-->| section |---private------+ | |
81  * | filters | sections | | +--subscribe/unsubscribe--+ |
82  * +-----------+ | | | for stream event | |
83  * A | | | | |
84  * | | | | load/unload +---------------+
85  * +---add/delete-----+ | | | +-open/close--| CLIENT(s) |
86  * section filter | | | | | object +---------------+
87  * | | | | | A A A
88  * +---SI Query--+ | | | | | | | |
89  * | result | | V V V V | | |
90  * +----------------+ | +------------------------+ | | |
91  * SI->| SI (PAT/PMT) | +->| | object/ | | |
92  * | database | | |--carousel-+ | |
93  * +----------------+ +---| | loaded | |
94  * A | | | | |
95  * | | | Platform & Profile |--stream event--+ |
96  * +--SI Query--+ | (eg.MHEG/MHP) specific | |
97  * | 'porting' layer(s) | +-object data/info-+
98  * +--Trigger-->| | |
99  * +----------+ | | | |
100  * | Timers |--+ +-----| | |
101  * +----------+ | |------synchronous-------+-asynchronous-+
102  * A | |==============(clDsmAPI)===============|
103  * | | | |
104  * +---start/stop--+ | |
105  * | DSM-CC |
106  * | CORE (IP) LAYER |
107  * | |
108  * | |
109  * | |
110  * +-------------------/\------------------+
111  * +--------\/--------+
112  * | DSMCC DATA CACHE |
113  * +------------------+
114  *
115  *
116  * --------------------------------------------------------------------------------
117  */
118 #ifndef _DSMCC_H_
119 #define _DSMCC_H_
120 
121 /*---includes for this file--------------------------------------------------*/
122 #include "cldsmtypes.h"
123 #include "stdfuncs.h"
124 #include "fs_types.h"
125 
126 #ifdef __cplusplus
127 extern "C" {
128 #endif
129 
130 
131 /*---Constant and macro definitions for public use---------------------------*/
132 
133 #define NUM_OPEN_DSM_OBJECTS_MAX 128
134 
135 #define DSMCC_MINIMUM_CACHE_SIZE (1024 * 1024 * 1)
136 #define DSMCC_DEFAULT_CACHE_SIZE (1024 * 1024 * 6)
137 
138 /* -- caching priority rules */
139 #define CACHE_RULES_DEFAULT 0x3F
140 #define CACHE_RULES_FROM_STREAM 0x00
141 #define CACHE_RULES_STATIC 0x80
142 
143 /* -- Progress codes */
144 #define CLDSM_PROG_CURR_SERVICE_CACHE_FULL 0
145 /* + ? */
146 
147 
148 /*---Enumerations for public use---------------------------------------------*/
149 
150 /* E_CacheRules is like, and could be, an enum, with 8-bit values defined above */
151 typedef U8BIT E_CacheRules;
152 
153 /*
154 -- **** TIMER EVENT TYPES ***
155 */
156 
157 /* -- Timer event status -- */
158 typedef enum
159 {
160  TIMER_TRIGGERED = 0,
161  TIMER_ABORTED
162 } E_TimerStatus;
163 
164 
165 /*
166 -- **** OBJECT DATA TYPES ***
167 */
168 
169 typedef struct s_DsmObject *H_DsmObject;
170 
171 /* -- Object kind -- */
172 typedef enum
173 {
174  ANON_OBJ = 0,
175  FILE_OBJ,
176  DIRECTORY_OBJ,
177  SERVICE_GATEWAY_OBJ,
178  STREAM_OBJ,
179  STREAM_OBJ_WITH_EVENTS,
180  LINK_TO_ALTERNATE_OC_OBJ
181 } E_DsmObjectKind;
182 
183 
184 /*
185 -- Status type for object load
186 */
187 typedef enum
188 {
189  /*0*/ OBJ_LOAD_UNINITIATED = 0,
190  /*1*/ OBJ_LOAD_IN_PROGRESS,
191  /*2*/ OBJ_LOAD_COMPLETED,
192  /*3*/ OBJ_LOAD_ABORTED_TIMEOUT,
193  /*4*/ OBJ_LOAD_ABORTED_PATH_ERROR,
194  /*5*/ OBJ_LOAD_ABORTED_ERROR,
195 #ifdef DSM_MHP_PROFILE
196  /*6*/ OBJ_LOAD_ABORTED_UNLOAD,
197  /* -- NOT CURRENTLY IMPLEMENTED */
198  /*7*/ OBJ_LOAD_PARENT_DIR_LOADED
199 #else
200  /*6*/ OBJ_LOAD_ABORTED_UNLOAD
201 #endif
202 } E_ObjLoadStatus;
203 
204 /*---Global type defs for public use-----------------------------------------*/
205 
206 typedef struct s_ObjUserData *H_ObjUserData;
207 
208 typedef struct s_UserInfo
209 {
210  U32BIT kind;
211  void *uFunc;
212  U_PARAM uData;
213 } S_UserInfo;
214 
215 /* --------------- REQUIRED API - CALLBACK TYPE DEFINITIONS ----------------- */
216 
217 /*
218 -- NOTES:
219 --
220 -- The calling environment must provide functions that match these callback
221 -- type definitions (except F_Progress which is optional). All
222 -- required callbacks should be non-blocking. The callback addresses are
223 -- supplied to the DSM-CC instance at instance create/setup.
224 --
225 -- The callbacks are not expected to fail except under exception conditions.
226 --
227 -- For callbacks with 'int' return values, this should be used to indicate:
228 -- zero: Successful execution/registration of call with calling env.
229 -- non-zero: Failure to execute/register call (eg. due to memory failure)
230 --
231 -- The DSMCC library will attempt to take some logical actions in response to a
232 -- failure of a start/add callback that may enable it to continue.(eg. abandon
233 -- request and notify client of a load failure due to system error).
234 --
235 -- The stop/delete callbacks are not provided with return values since there is
236 -- no meaningful action the DSM-CC library can take in response to these
237 -- failing. If it is possible that these callbacks fail to execute the
238 -- requested action then the internal state of the DSM-CC library will become
239 -- inconsistent with the calling environment. The calling environment must
240 -- handle this situatation - eg. by raising an exception and processing it when
241 -- the DSM-CC API call that triggered it completes. The calling environment
242 -- should deal with the problem before making any further DSM-CC API calls
243 -- (except clDsmSysReset or clDsmSysDestroy). It should either ensure that the
244 -- action requested by the callback is successfully executed or clear the problem
245 -- and reset/restart the DSM-CC library.
246 --
247 */
248 
249 
250 /* -- ERROR/PROGRESS CALLBACKS -- */
251 
252 /*******************************************************************************
253 * Informs calling environment of errors triggered during stream/section
254 * processing
255 *******************************************************************************/
256 typedef void (*F_Error) ( /*I*/ E_DscError err, void *args );
257 
258 
259 /*******************************************************************************
260 * Informs calling environment of state changes triggered during
261 * stream/section processing
262 *******************************************************************************/
263 typedef void (*F_Progress) ( /*I*/ U32BIT prog, void *args );
264 
265 
266 
267 /* -- TIMER CALLBACKS -- */
268 
269 /*******************************************************************************
270 * Starts timer with specified period
271 *
272 * Timer trigger/timeout notified via CDSM_SysProcessTimerEvent().
273 *
274 * When notifying a timeout then the value of clDsmTmrUserData
275 * supplied to this call MUST also be input to clDsmProcessTimerEvent.
276 *
277 * Returning a timerHandle value is optional but it should be set to Null if
278 * not used/available. This value is input to the stopTimerFunc callback.
279 *
280 * If a timerHandle is not available synchronously then it can be also be
281 * supplied when clDsmSysProcessTimerEvent is called.
282 *
283 *******************************************************************************/
284 typedef E_DscError (*F_StartTimer) ( H_DsmControl dsmControl,
285  /*I*/ U32BIT timePeriod,
286  void *clDsmTmrUserData,
287  /*O*/ void **pTimerHandle );
288 
289 
290 /*******************************************************************************
291 * Stops timer
292 *
293 * Timers will always be explicity stopped via this call, even after they have
294 * triggered. Both application and component handles/references are supplied for
295 * flexibility.
296 *
297 * NB. If a timer is stopped (aborted) before it has triggered (ie. before a
298 * timeout has been notified via clDsmSysProcessTimerEvent), timer abort must be
299 * notified via CDSM_SysProcessTimerEvent() instead. The call to
300 * clDsmSysProcessTimerEvent can be made from within this callback.
301 *
302 *******************************************************************************/
303 typedef void (*F_StopTimer) ( H_DsmControl dsmControl,
304  /*I*/ void *timerHandle );
305 
306 
307 
308 /* -- SI QUERY CALLBACKS -- */
309 
310 /*******************************************************************************
311 * Makes (starts) SI query (eg. database lookup)
312 *
313 * Meaning of return values in this context:
314 *
315 * CLDSM_OK
316 * - Query has (synchronously) returned successful result.
317 *
318 * CLDSM_PENDING
319 * - Query is being executed asynchronously - results/events
320 * will be returned via CDSM_SysProcessSIQueryEvent()
321 *
322 * CLDSM_ERR_SI_QUERY_FAILED
323 * - Query has (synchronously) failed to determine requested
324 * information (due to error in SI lookup).
325 *
326 * If a query result is to be returned asynchronously then the value of
327 * clDsmSIQueryRef and clDsmSIUserData supplied to this call MUST also be input
328 * to clDsmProcessSIQueryEvent along with the result.
329 *
330 * Returning a queryHandle value in pResult is optional. If not used/available,
331 * it should be set to Null. This value is input to the stopSIQueryFunc callback.
332 *
333 * If a queryHandle is not available synchronously then it can be also be
334 * supplied when clDsmSysProcessSIQueryEvent is called.
335 *
336 * NB. In this case, if the query is stopped for any reason before this event
337 * then the calling environment will have to identify the correct query to stop
338 * from the DSM-CC reference (clDsmSIQueryRef).
339 *
340 *******************************************************************************/
341 typedef E_DscError (*F_StartSIQuery) ( H_SiqInstance siqInstance,
342  P_SIQueryRequest pQuery, H_SIQueryRef clDsmSIQueryRef,
343  void* clDsmSIUserData,
344  P_SIQueryResult pResult );
345 
346 
347 /*******************************************************************************
348 * Stops an SI query
349 *
350 * Any asynchronous SI queries (ie. those that returned a status SIQUERY_PENDING
351 * to the StartSIQueryFunc call) will be explicity stopped via this call, even
352 * after they have completed.
353 *
354 * Both application and component handles/references are supplied for
355 * flexibility.
356 *
357 * NB. If an SI query is stopped (aborted) before it has completed (ie. before
358 * a result has been supplied via clDsmSysProcessSIQueryEvent), SI query abort
359 * must be notified via CDSM_SysProcessSIQueryEvent() instead. The call to
360 * clDsmSysProcessSIQueryEvent can be made from within this callback.
361 *
362 *******************************************************************************/
363 typedef void (*F_StopSIQuery) ( H_SiqInstance siqInstance,
364  /*I*/ void *queryHandle, H_SIQueryRef clDsmSIQueryRef );
365 
366 
367 
368 /* -- SI CHANGE REGISTRATION CALLBACKS -- */
369 
370 /*******************************************************************************
371 * Register to receive notifications of changes to the SI for the specified
372 * service (on the current transport stream/multiplex).
373 *
374 * When a duplicate subscribe is made (ie. for a service that is already
375 * subscribed) it should increment the count of subscriptions for that service.
376 * Matching unsubscribe will be made for each subscribe.
377 *
378 * Changes are notified via the clDsmSysProcessSIChangeEvent function in the
379 * following situations:
380 *
381 * - The subscribed service cannot be located
382 * - The service is deleted from the multiplex (eg. PAT updated)
383 * - The service info is updated (ie. PMT updated).
384 *
385 * If it can be determined immediately (ie. synchronously) that the requested
386 * service does not exist in the current multiplex (eg. it is not listed in the
387 * most recent stored copy of the PAT) then the output parameter serviceNotFound
388 * can be set to TRUE (otherwise set it to FALSE).
389 *
390 *******************************************************************************/
391 typedef E_DscError (*F_SubscribeSIChanged) ( H_SiqInstance siqInstance,
392  /*I*/ U16BIT service_id );
393 
394 
395 /*******************************************************************************
396 * Decrement number of subscriptions to the specified service. Only when this
397 * number reaches zero should this function de-register for notifications of
398 * changes to the SI for the service.
399 *
400 * This will be called to de-register for a previously subscribed service,
401 * even if the DSM-CC library has been notified that the subscribed service
402 * cannot be located.
403 *
404 *******************************************************************************/
405 typedef void (*F_UnsubscribeSIChanged) ( H_SiqInstance siqInstance,
406  /*I*/ U16BIT service_id );
407 
408 
409 
410 /* -- SECTION FILTER CALLBACKS -- */
411 
412 /*******************************************************************************
413 * Requests a section filter to be started.
414 *
415 * It is assumed that the number of section filters that may be simultaneously
416 * requested (in use) is unlimited. Typically it is expected that the worst case
417 * requirement (eg. with full carousel caching and multiple stream events) is
418 * less than that specified in the setup.
419 *
420 * Filtered private sections are returned via CDSM_SysProcessPrivateSection().
421 * The clDsmFilterRef value MUST be stored and also
422 * returned with any sections that matched the requested filter.
423 *
424 * Exact duplicate filters will never be requested simultaneously but filters
425 * with 'wildcard' (ie. tableIdExtMask) bits set may overlap with other
426 * requested filters with less or no mask bits set.
427 *
428 * If a section aligns with two or more such filters then it should only be
429 * matched to the 'narrowest' (ie. most exact) filter and that clDsmFilterRef
430 * value passed with the section data to clDsmSysProcessPrivateSection.
431 *
432 * Filters requested with high priority will always be narrower (ie. less mask
433 * bits set) than any overlapping low priority filters and this rule ensures
434 * that sections will always be matched to high priority filters in preference
435 * to low.
436 *
437 * NB. The worst case number of exact filters (ie. with no mask bits set)
438 * requested simultaneously may be large (eg. 100s) but the worst case number of
439 * simultaneous filters with (one or more) mask bits set is expected to be much
440 * smaller (eg. ~10).
441 *
442 * The filter should always remain in effect with continuous supply of section data,
443 * until delSectionFilterFunc is called.
444 *
445 * If platform requires priority rating in this callback, it can use
446 * CDSM_SectionFilterPriority().
447 *
448 * Parameters:
449 *
450 * PID MPEG2 PID
451 *
452 * tableId DSM-CC tableId filter value for sections (byte 0).
453 * NB. Only the tableId values of 0x3B, 0x3C, 0x3D will
454 * be used for DSM-CC section filters.
455 *
456 * tableIdExt DSM-CC tableIdExtension filter value (bytes 3&4)
457 *
458 * tableIdExtMask DSM-CC active filter bits.
459 * NB.'Wildcard' bitmasks will only be set on contiguous
460 * bits starting at LSBit.
461 *
462 * Return: void*
463 * This is the platform filter handle value. It is given as input to the
464 * delSectionFilterFunc callback. NULL value is considered failure, and any other
465 * value is considered a successful operation.
466 *
467 *******************************************************************************/
468 typedef void * (*F_AddSectionFilter) ( H_SfmInstance sfm,
469  /*I*/ P_SecFilter pFilter, H_DscSFRef dsmFilterRef );
470 
471 
472 /*******************************************************************************
473 * Requests a section filter to be stopped
474 *
475 * To give flexibility in identifying the filter to delete, both application
476 * and component handles/references are supplied. Also a repeat of the section
477 * filter details are supplied (which are unique for any active filter) .
478 *
479 * NB. To avoid problems due to delays in deleting filters or caused by queuing
480 * sections the clDsmSysProcessPrivateSection function can detect sections being
481 * supplied from 'stale' (ie. deleted) filters. This will waste CPU time so the
482 * calling environment should ensure as soon as possible (after this callback
483 * is made) that sections matching the deleted filter are stopped.
484 *
485 *******************************************************************************/
486 typedef void (*F_DelSectionFilter) ( H_SfmInstance sfm,
487  /*I*/ void *filterHandle, H_DscSFRef clDsmFilterRef );
488 
489 
490 /*******************************************************************************
491 * Notify a section filter priority changed
492 *
493 *******************************************************************************/
494 typedef void (*F_SFPriorityChanged) ( H_SfmInstance sfm,
495  /*I*/ void *filterHandle, H_DscSFRef clDsmFilterRef,
496  E_SFPriority priority );
497 
498 
499 /* -- LOAD & STREAM EVENT CALLBACKS -- */
500 
501 /*******************************************************************************
502 * Notify of a load carousel event.
503 *
504 * Called when carousel booted, load completed (ie. SRG module loaded) or load
505 * aborted before completion (due to errors, timeout or unload). Component
506 * handle and userData values supplied for flexibility.
507 *
508 * If CDSM_UnloadCarousel() is called before the carousel load is completed
509 * (ie. before this callback has been called with status OC_LOAD_COMPLETED)
510 * then the callback will actually be made from within the clDsmUnloadCarousel
511 * call with status OC_LOAD_ABORTED_UNLOAD.
512 *
513 * Any of the Synchronous or Asynchronous Client API calls (ie. API calls that
514 * do NOT start with clDsmSys...) can be made from within this callback. When
515 * doing this, care must be taken to avoid blocking or re-entrancy problems in
516 * the calling environment. Re-entrancy may occur when unloading objects or
517 * carousels since this can cause a (re-entrant) call to this callback.
518 *
519 *
520 *******************************************************************************/
521 typedef void (*F_NotifyCarouselLoadEvent) (
522  /*I*/ H_DsmCarousel clDsmCarouselHandle, E_OCLoadStatus status,
523  U32BIT carouselId );
524 
525 
526 /*******************************************************************************
527 * Notify of a load object event.
528 *
529 * Called when object load completed or load aborted before completion (due to
530 * errors, timeout or unload of object or carousel). Component handle and
531 * userData values supplied for flexibility.
532 *
533 * If CDSM_UnloadObject() (or clDsmUnloadCarousel) is called before the object
534 * load is completed (ie. before this callback has been called with status
535 * OBJ_LOAD_COMPLETED) then the callback will actually be made from within the
536 * CDSM_UnloadObject(or clDsmUnloadCarousel) call with status
537 * OBJ_LOAD_ABORTED_UNLOAD.
538 *
539 * Any of the Synchronous or Asynchronous Client API calls (ie. API calls that
540 * do NOT start with clDsmSys...) can be made from within this callback. When
541 * doing this, care must be taken to avoid blocking or re-entrancy problems in
542 * the calling environment. Re-entrancy may occur when unloading objects or
543 * carousels since this can cause a (re-entrant) call to this callback.
544 *
545 *
546 *******************************************************************************/
547 typedef void (*F_NotifyObjectLoadEvent) (
548  /*I*/ H_DsmObject clDsmObjectHandle, E_ObjLoadStatus status,
549  H_ObjUserData pCopyOfObjLoadUserData );
550 
551 
584 typedef void (*F_NotifyStreamEvent)(
585  /*I*/ H_DsmEvent eventHandle, E_StreamEventStatus status, S_UserInfo userInfo,
586  U8BIT *namePtr, U8BIT *dataPtr, U8BIT namelen, U8BIT dataLen );
587 
588 
589 
604 typedef void (*F_NotifyDeferredService) (
605  /*I*/ void *userData1, void *userData2,
606  S_DvbLocator *pDeferredService );
607 
608 
609 typedef BOOLEAN (*F_IsUserDataMatch) (H_ObjUserData pUserData1, H_ObjUserData pUserData2);
610 
611 
612 /*
613 -- Type definitions for setup variables
614 --
615 */
616 
617 /*
618 -- Setup structure for use at initialisation
619 */
620 typedef struct
621 {
622  /*
623  -- General callback pointers
624  --
625  -- NOTES:
626  -- All callbacks MUST be provided except where indicated
627  --
628  */
629  F_MemAlloc allocFunc;
630  F_MemFree freeFunc;
631 
632  /* -- errorFunc - optional (Null if not used) */
633  F_Error errorFunc;
634  /* -- progressFunc - optional (Null if not used) */
635  F_Progress progressFunc;
636 
637  F_AddSectionFilter addSectionFilterFunc;
638  F_DelSectionFilter delSectionFilterFunc;
639  /* -- sfPriorityChangeFunc - optional (Null if not used) */
640  F_SFPriorityChanged sfPriorityChangeFunc;
641 
642  F_StartTimer startTimerFunc;
643  F_StopTimer stopTimerFunc;
644 
645  F_StartSIQuery startSIQueryFunc;
646  F_StopSIQuery stopSIQueryFunc;
647 
648  F_SubscribeSIChanged subscribeSIChangeFunc;
649  F_UnsubscribeSIChanged unsubscribeSIChangeFunc;
650 
651  /* -- notifyCarouselLoadEventFunc - optional (Null if not used) */
652  F_NotifyCarouselLoadEvent notifyCarouselLoadEventFunc;
653  /* -- notifyObjectLoadEventFunc - optional (Null if not used) */
654  F_NotifyObjectLoadEvent notifyObjectLoadEventFunc;
655 
656  /* notifyStreamEventFunc can be Null when Stream Events are not required */
657  F_NotifyStreamEvent notifyStreamEventFunc;
658 
659  /* notifyDeferredServiceFunc can be Null when deferred service for Stream Objects are not required */
660  F_NotifyDeferredService notifyDeferredServiceFunc;
661 
662  S_SsuConfig ssuFuncs;
663 
664  /* -- Control flags */
665 
666  H_DsmControl dsmControl;
667  /*
668  -- Instance handle for external Service Information Query module
669  */
670  H_SiqInstance siqInstance; /* -- Suggested default: Null */
671 
672  /*
673  -- Instance handle for external Section Filter Manager module
674  */
675  H_SfmInstance sfmInstance; /* -- Suggested default: Null */
676 
677  /*
678  -- Pointer (optional) that can be used by calling environment for
679  -- passing setup info to the memory manager (via clDsmMemMgr API) at
680  -- memStart time.
681  */
682  void *memMgrSetup; /* -- Suggested default: Null */
683 
684 
685  /*
686  -- Specifies resolution of time units used on API in _milliseconds_
687  -- (can be set to resolution of external timers)
688  --
689  -- NB. Time values are represented on the API and internally as U32BIT so
690  -- timeUnitResolution should be chosen so that overflow problems will not
691  -- occur during any likely period of continuous use for a receiver (eg. if
692  -- timeUnitResolution = 10mS, wrap-round time = 1.36 years!).
693  */
694  U32BIT timeUnitResolution; /* -- Suggested default: 10 */
695 
696 
697  /*
698  -- Sets the size of dynamic memory available for DSM-CC to use.
699  -- Apart from 100KB approx. the remainder of this memory will be requested
700  -- and accessed via the dynamic memory manager API (clDsmMemMgrAPI.h).
701  --
702  -- NB. In debug builds DSM-CC may allocate slightly (<5%) more than this
703  -- specified amount.
704  --
705  -- If clDsmMemMgrAPI is mapped to a system memory manager then it
706  -- has an additional option (when it is opened) to decrease the amount
707  -- of (the remainder of this) memory it makes available.
708  */
709  U32BIT maxMemorySize; /* -- Absolute minimum: DSMCC_MINIMUM_CACHE_SIZE */
710  /* -- Recommended min: DSMCC_DEFAULT_CACHE_SIZE */
711 
712  /*
713  -- Specifies the maximum number of section filters that are available
714  -- in the calling environment (to this instance) for simultaneously
715  -- acquiring DSM-CC private sections.
716  --
717  -- If client requests (or other events) cause the core stack to
718  -- simultaneously require more section filters than the number available
719  -- it will rotate its requests through the available filters. This may
720  -- cause delays in responding to client requests so the larger this
721  -- number the better.
722  --
723  -- The minimum value is NUM_SECTION_FILTERS_MINIMUM.
724  -- Setting to zero will be interpreted as no restriction on the
725  -- number of section filters available in the calling environment, and
726  -- NUM_SECTION_FILTERS_MAXIMUM will be used.
727  -- Setting to a value less than this the minimum will be ignored, and
728  -- NUM_SECTION_FILTERS_MINIMUM will be used.
729  -- Suggested Default: NUM_SECTION_FILTERS_DEFAULT
730  */
731  U16BIT maxAvailableSectionFilters;
732 
733  /*
734  -- Sets whether DSM-CC component maintains an internal record
735  -- of SI query results so that it does not need to repeatedly
736  -- make the same SI queries (to the calling env). Typically this
737  -- will be used for storing association_tag to PID mappings.
738  */
739  BOOLEAN storeSIQueryResults; /* -- Default: FALSE */
740 
741 
742  /*
743  -- Sets whether DSM-CC component pre-fetches modules into its
744  -- internal cache.
745  --
746  -- NB. This requires a large available memory size and a large number of
747  -- available section filters.
748  --
749  -- Enabling turboCaching also activates full transparent caching (ie.
750  -- automatic re-loading of cached modules that have version updates).
751  -- This is because turboCaching will not work effectively without this
752  -- and also because only when turboCaching is enabled are there
753  -- likely to be sufficient section filters available to support
754  -- automatic module re-loading.
755  */
756  BOOLEAN turboCaching; /* -- Default: FALSE */
757 
758  /*
759  */
760  BOOLEAN multipleSsuDownloads;
762 
763 
764 
765 /*---Global variable declarations for public use-----------------------------*/
766 
767 
768 /******************************************
769 * EXPORTED (PROVIDED) FUNCTION PROTOTYPES *
770 *******************************************/
771 
772 /* ---------------------- SYNCHRONOUS SYSTEM API CALLS ---------------------- */
773 
774 /*
775 -- NOTES:
776 --
777 -- The following functions must be called synchronously with each other and
778 -- with the Synchronous Client API calls since they use and modify common
779 -- instance data. If they need to be called/triggered from different threads
780 -- the calling environment must ensure synchronous behaviour - eg. by using
781 -- a mutex semaphore round the call (or queueing and calling from the same
782 -- thread).
783 --
784 -- In some circumstances it is possible to make one Synchronous API call from
785 -- within another one:
786 --
787 -- eg. clDsmSysProcessTimerEvent can be called within the stopTimerFunc
788 -- callback which itself may have been called from within.
789 -- clDsmSysProcessPrivateSection
790 --
791 -- eg. All Synchronous Client API calls can be called from within the
792 -- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks which may
793 -- themselves have been called within clDsmSysProcessPrivateSection.
794 --
795 -- These cases are clearly specified in the comments. The calling environment
796 -- must avoid possible permanent blocks in these circumstances, eg. from trying
797 -- to get a mutex on a thread that has it already.
798 --
799 */
800 
801 
802 /*******************************************************************************
803 * Create DSM-CC Core Layer instance
804 *
805 * Only call at startup of an instance (before ANY other DSM-CC Core Layer API
806 * calls are made for that instance). Allocates all required 'static' memory
807 * for the instance (via allocFunc). Also stores (copies) data supplied in
808 * setup structure.
809 *
810 * NB. Dynamic (heap) memory used by the instance is allocated/deallocated and
811 * accessed via the dynamic memory manager API (clDsmMemMgrApi.h).
812 *
813 * Returns instance value which is used to reference the unique data used by
814 * this DSM Core instance. It MUST be stored by the calling environment and
815 * passed to any clDsm API calls for the instance.
816 *
817 * Also returns memContext parameter (obtained when memory manager started).
818 * If implemented/required, this gives the calling environment independent
819 * access to the memory manager context used by this DSM Core instance.
820 *
821 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
822 * allocFunc
823 * freeFunc - only on error
824 *
825 * RETURNS:
826 * CLDSM_OK (0)
827 * CLDSM_ERR_ALLOC_FAILED,
828 * CLDSM_ERR_MEM_HEAP_FULL
829 * CLDSM_ERR_ILLEGAL_SETUP
830 *
831 *******************************************************************************/
832 E_DscError CDSM_SysCreate(
833  /*I*/ P_DsmSetup pSetup,
834  /*O*/ H_DsmCoreInst *pInstance, void **pMemContext );
835 
836 
837 
868 E_DscError CDSM_SysDestroy( H_DsmCoreInst instance,
869  H_SiqInstance *pSiqInst, H_SfmInstance *pSfmInst );
870 
871 
878 
879 
917 E_DscError CDSM_SysReset( H_DsmCoreInst instance, E_DsmRstMode mode );
918 
924 void CDSM_SysSetMemoryMax( H_DsmCoreInst instance, U32BIT maxMemory );
925 
957 E_DscError CDSM_SysSetCurrService( H_DsmCoreInst instance,
958  /*I*/ U16BIT original_network_id, U16BIT transport_stream_id,
959  U16BIT service_id );
960 
961 U16BIT CDSM_SysCurrServiceId( H_DsmCoreInst instance );
962 
963 
989 E_DscError CDSM_SysProcessTimerEvent( H_DsmCoreInst instance,
990  /*I*/ void *clDsmTmrUserData, E_TimerStatus status, void *timerHandle );
991 
992 
993 
1034 E_DscError CDSM_SysProcessSIQueryEvent( H_DsmCoreInst instance,
1035  /*I*/ H_SIQueryRef clDsmSIQueryRef, void *clDsmSIUserData,
1036  P_SIQueryResult pResult );
1037 
1038 
1039 
1075 E_DscError CDSM_SysProcessSIChangeEvent( H_DsmCoreInst instance,
1076  E_SIChangeEvent evnt, U16BIT service_id, U32BIT carousel_id );
1077 
1078 
1079 
1080 /*******************************************************************************
1081 * Process DSM-CC private section data
1082 *
1083 * NOTES:
1084 *
1085 * Call each time the Demux provides a private section from one of the
1086 * requested PIDs (main TS data input of DSM-CC Core API).
1087 *
1088 * It is assumed that the calling environment has already CRC checked the
1089 * section (if relevant) and only sections that pass this check will be
1090 * supplied to clDsmSysProcessPrivateSection.
1091 *
1092 * The clDsmFilterRef and clDsmSfUserData inputs MUST be set to the values
1093 * supplied when the filter for this section was requested
1094 * (via addSectionFilterFunc).
1095 *
1096 * If sections have to be queued (or discarded) in the calling environment
1097 * then those matching filters with a high priority MUST always be supplied
1098 * to this function in preference to those matching low priority filters.
1099 *
1100 * NB. Although sections matching low priority filters (or even high priority
1101 * filters) can be discarded if necessary. The order in which they were
1102 * broadcast should always be maintained when they are supplied to this
1103 * function.
1104 *
1105 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1106 * errorFunc
1107 * progressFunc
1108 * addSectionFilterFunc
1109 * delSectionFilterFunc
1110 * stopTimerFunc
1111 * startSIQueryFunc
1112 * notifyCarouselLoadEventFunc
1113 * notifyObjectLoadEventFunc
1114 *
1115 * RETURNS:
1116 * CLDSM_OK (0)
1117 * CLDSM_ERR_INVALID_INSTANCE
1118 * CLDSM_ERR_ILLEGAL_PARAMETER
1119 * CLDSM_ERR_ABORTED When dsmFilterRef is not recognised (maybe stale)
1120 *
1121 *******************************************************************************/
1122 E_DscError CDSM_SysProcessPrivateSection( H_DsmCoreInst instance,
1123  /*I*/ U8BIT *pSection, H_DscSFRef dsmFilterRef );
1124 
1125 
1126 /*******************************************************************************
1127 * Request priority for DSM-CC private section data
1128 *
1129 *******************************************************************************/
1130 E_DscError CDSM_SectionFilterPriority( H_DsmCoreInst instance,
1131  H_DscSFRef dsmFilterRef,
1132  E_SFPriority *pPriority );
1133 
1134 
1135 /* ---------------------- SYNCHRONOUS CLIENT API CALLS ---------------------- */
1136 
1137 /*
1138 -- NOTES:
1139 --
1140 -- The following functions must be called synchronously with each other and
1141 -- with the above System API calls. If they need to be called/triggered
1142 -- from different threads the calling environment must ensure synchronous
1143 -- behaviour - eg. by using a mutex semaphore round the call (or queueing and
1144 -- calling from the same thread).
1145 --
1146 -- Any of the Synchronous (or Asynchronous) Client API calls (ie. API
1147 -- calls that do NOT start with clDsmSys...) can be made from within the
1148 -- notifyCarouselLoadEvent or notifyObjectLoadEvent callbacks. When doing
1149 -- this, care must be taken to avoid blocking or re-entrancy problems in
1150 -- the calling environment. Re-entrancy may occur when unloading objects or
1151 -- carousels since this can cause a (re-entrant) call to these callbacks.
1152 --
1153 */
1154 
1155 
1156 /* -- CAROUSEL LOAD FUNCS -- */
1157 
1158 /*******************************************************************************
1159 *
1160 * Loads DSM-CC object carousel specified by carousel_id from indicated service
1161 * (on the current multiplex/transport stream)
1162 *
1163 * If carousel_id is set to INVALID_CAROUSEL_ID, then this function loads the
1164 * initiate boot carousel for the service
1165 *
1166 * NOTES:
1167 *
1168 * The returned clDsmCarouselHandle value must always be supplied by the
1169 * calling environment whenever accessing objects in this carousel.
1170 *
1171 * Initially a section filter will be set up to acquire the DSI message for the
1172 * carousel. Once the DSI message is acquired the calling environment is
1173 * notified via the notifyCarouselLoadEventFunc callback (if supplied at
1174 * setup/create) that the carousel is BOOTED. Open object requests can then be
1175 * made for this carousel.
1176 *
1177 * When the service gateway (SRG) is loaded for this carousel the calling
1178 * environment is notified again via the callback that the carousel is now
1179 * LOADED. Objects in the carousel cannot be accessed (opened) until the
1180 * service gateway for the carousel is loaded.
1181 *
1182 * If timeout occurs before the SRG is loaded a timeout error is returned. If
1183 * an error is encountered while loading the carousel then an aborted error is
1184 * returned.
1185 *
1186 * Using the ocLoadUserData1 and ocLoadUserData2 values is optional. These
1187 * values are returned unchecked into the load event callback. They can be used
1188 * for any purpose (eg. to aid in matching callbacks with corresponding load
1189 * requests and/or clients).
1190 *
1191 * If timeout value is set to zero it means no (ie. infinite) timeout.
1192 *
1193 * If a duplicate request is made to load a boot carousel then an error will be
1194 * generated but the clDsmCarouselHandle will be set to the value of the already
1195 * loaded carousel.
1196 *
1197 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1198 * startTimerFunc
1199 * startSIQueryFunc
1200 * addSectionFilterFunc
1201 *
1202 * RETURNS:
1203 * CLDSM_OK (0)
1204 * CLDSM_DUPLICATE_REQUEST
1205 * CLDSM_ERR_MEM_HEAP_FULL
1206 * CLDSM_ERR_NO_CURRENT_SERVICE_SET
1207 * ?
1208 *
1209 *******************************************************************************/
1210 E_DscError CDSM_LoadCarousel( H_DsmCoreInst instance,
1211  U16BIT service_id, U32BIT carousel_id, E_SIQueryKind kind,
1212  H_DsmCarousel *pclDsmCarouselHandle );
1213 
1214 
1215 
1216 
1257 E_DscError CDSM_UnloadCarousel( H_DsmCoreInst instance,
1258  /*I*/ H_DsmCarousel clDsmCarouselHandle, E_DsmRstMode mode );
1259 
1268 E_DscError CDSM_UnloadModule( H_DsmCoreInst idp, H_DsmCarousel hCarousel,
1269  U32BIT moduleRef );
1270 
1280 E_DscError CDSM_GetCarouselId( H_DsmCoreInst instance,
1281  /*I*/ H_DsmCarousel carouselHandle,
1282  /*O*/ U32BIT *pCarouselId );
1283 
1289 H_DsmCarousel CDSM_CurrentCarousel( H_DsmCoreInst instance );
1290 
1299 E_DscError CDSM_SetCurrentCarousel( H_DsmCoreInst instance,
1300  /*I*/ H_DsmCarousel carouselHandle );
1301 
1313 E_DscError CDSM_CarouselLoadFileGroups( H_DsmCoreInst instance,
1314  /*I*/ H_DsmCarousel clDsmCarouselHandle,
1315  /*O*/ U16BIT *total, S_CarouselInfoFileGroup **pGroups );
1316 
1329 E_DscError CDSM_CarouselUnloadFileGroups( H_DsmCoreInst instance,
1330  /*I*/ H_DsmCarousel clDsmCarouselHandle,
1331  /*I*/ S_CarouselInfoFileGroup *groups );
1332 
1333 /* -- OBJECT LOAD FUNCS -- */
1334 
1335 /*******************************************************************************
1336 *
1337 * Load an object with the requested pathname into cache.
1338 *
1339 * Unless the carousel is specifed in the path, this will load an object from
1340 * the 'Current' object carousel. The client may specify another carousel by
1341 * setting the 'Current' object carousel with use of CDSM_SetCurrentCarousel().
1342 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
1343 * then the function will attempt to load this carousel and make it the new
1344 * 'Current' object carousel.
1345 *
1346 * NOTES:
1347 *
1348 * Currently, an object can only be loaded once the carousel is booted (DSI
1349 * message acquired).
1350 *
1351 * Requested pathname must be a full (absolute) object pathname starting with
1352 * an object in the root (ie. service gateway) directory of the specified
1353 * carousel, eg. dir1/dir2/file3 is treated as DSM:/dir1/dir1/file3. Any
1354 * characters defined in PATH_SEPERATOR_LIST_STRING will be treated as path
1355 * token seperators all other chars are treated as part of a path token. An
1356 * empty pathname U8BIT* (or U8BIT* containing only path token seperators)
1357 * will open the service gateway directory itself.
1358 *
1359 * **** NB. SRG (& directory) ACCESS NOT YET IMPLEMENTED ****
1360 *
1361 * Returns an clDsmObjectHandle which the client uses to access the requested
1362 * object. If the object is already cached then the status parameter will be
1363 * set to OBJ_LOAD_COMPLETED. In this case the objectRef value can be used to
1364 * access (eg. open for reading) the object/file data immediately.
1365 *
1366 * If the object is not in the cache then a fetch from the input stream is
1367 * initiated and the status parameter set to OBJ_LOAD_IN_PROGRESS. When the
1368 * object is loaded into the cache the calling environment is notified via the
1369 * notifyObjectlLoadEventFunc callback (if supplied at setup/create).
1370 *
1371 * Using the objLoadUserData1 and objLoadUserData2 values is optional. These
1372 * values are returned unchecked into the load event callback. They can be used
1373 * for any purpose (eg. to aid in matching callbacks with corresponding load
1374 * requests and/or clients).
1375 *
1376 * If multiple load requests are made for the same object before it is
1377 * available each request will initiate a new (parallel) fetch from the input
1378 * stream and a callback will be generated for each request when the object is
1379 * loaded.
1380 *
1381 * While an object is LOADED it's contents are guaranteed to remain available
1382 * and constant in cache memory (ie. it will not be updated from the input
1383 * stream or deleted to create space in the cache).
1384 *
1385 * Any load request for an object (that is not already loaded) will only get
1386 * completed by a call to clDsmysProcessPrivateSection. This will either have
1387 * delivered the last part of the module containing the object or delivered a
1388 * module containing a previously missing higher level directory in the object
1389 * path that results in the requested object now being accessible in the cache.
1390 *
1391 * If a load proceeds part way down a path and then encounters an error, the
1392 * load is aborted and the appropriate status returned via the callback. The
1393 * clDsmObjectHandle cannot be used to access object/file DATA until/unless
1394 * it is successfully loaded.
1395 *
1396 * **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED ****
1397 * If caching rules are specified they are applied as below. If pCachingRules
1398 * is set to Null the object will be given the default caching rules.
1399 *
1400 * If the object is not in the cache then the caching rules only have an
1401 * effect on the subsequent caching of the object/module once the object load
1402 * is completed and the object is actually unloaded (via clDsmUnloadObject),
1403 * ie. when it is made available for caching.
1404 *
1405 * If the same object is requested multiple times in parallel, then once the
1406 * object load is completed the highest priority caching rules are selected
1407 * (fromStream overrides any other settings). These are applied only when
1408 * the last of the object load instances is unloaded.
1409 *
1410 * If the requested object is already in the cache and the caching rules have
1411 * fromStream set, then the object/module is immediately deleted from the cache
1412 * and a new fetch from the input stream is initiated.
1413 *
1414 * If the same object is loaded multiple times in parallel then the caching
1415 * rules specified at each load call will only replace the currently set
1416 * caching rules for this object if they specify a higher caching priority
1417 * (fromStream overrides any priority setting). If fromStream is set on any
1418 * load then it will cause a re-fetch of the object for that load instance.
1419 * The data for any previous load instances will only get physically deleted
1420 * when they are unloaded.
1421 *
1422 * NB. For module based caching (as currently implemented) the whole module
1423 * inherits the caching rules MOST RECENTLY SPECIFIED for any object in that
1424 * module.
1425 *
1426 * The rules for when multiple objects from the same module are requested (or
1427 * loaded) in parallel are applied to a module on the same basis as described
1428 * for multiple instances of the same object.
1429 *
1430 * **** NOT YET IMPLEMENTED ****
1431 * If timeout value is set to zero it means no (ie. infinite) timeout. If a
1432 * timeout is specified and the object has not been loaded in the specified
1433 * time (for any reason) then the load request is aborted and the client
1434 * notified. Timeout is expressed in periods of timerResolution (specified at
1435 * setup/create).
1436 *
1437 *
1438 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1439 * addSectionFilterFunc
1440 * startTimerFunc
1441 * startSIQueryFunc
1442 *
1443 * RETURNS:
1444 * CLDSM_OK (0)
1445 * CLDSM_ERR_MEM_HEAP_FULL
1446 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE
1447 * CLDSM_ERR_INVALID_CACHING_RULES
1448 * CLDSM_ERR_CAROUSEL_NOT_BOOTED
1449 *
1450 * CLDSM_ERR_INVALID_PATHNAME - Null pointer or path too long
1451 *
1452 * CLDSM_ERR_LOAD_FAILURE - Failed to load requested file (because
1453 * some part of path could not be located)
1454 * +?
1455 *
1456 *******************************************************************************/
1457 E_DscError CDSM_LoadObject( H_DsmCoreInst instance,
1458  /*I*/ U8BIT *pathname, U32BIT timeout, E_CacheRules cachingRules,
1459  H_ObjUserData pUserData, U32BIT sizeOfUserData,
1460  /*O*/ E_ObjLoadStatus *pStatus, H_DsmObject *pclDsmObjectHandle );
1461 
1462 
1463 
1522 E_DscError CDSM_UnloadObject( H_DsmCoreInst instance,
1523  /*I*/ H_DsmObject clDsmObjectHandle, E_DsmRstMode mode );
1524 
1525 E_DscError CDSM_UnloadMatchingObject( H_DsmCoreInst instance,
1526  F_IsUserDataMatch matchFunc, H_ObjUserData pUserData, E_DsmRstMode mode );
1527 
1554 E_DscError CDSM_OpenObject(
1555  /*I*/ H_DsmCoreInst instance,
1556  /*I*/ H_DsmObject clDsmObjectHandle,
1557  /*O*/ E_DsmObjectKind *pKind );
1558 
1559 
1560 
1561 
1562 /*******************************************************************************
1563 * Close a loaded object
1564 *
1565 * NOTES:
1566 *
1567 * Closes the loaded object data. If an object is open this must be called
1568 * before it can be unloaded (via clDsmUnloadObject).
1569 *
1570 *
1571 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1572 * none
1573 *
1574 * RETURNS:
1575 * CLDSM_OK (0)
1576 * CLDSM_ERR_INVALID_OBJECT_HANDLE
1577 * CLDSM_ERR_OBJECT_NOT_LOADED
1578 * CLDSM_ERR_OBJECT_NOT_OPEN
1579 * ?
1580 *
1581 *******************************************************************************/
1582 E_DscError CDSM_CloseObject( H_DsmCoreInst instance,
1583  /*I*/ H_DsmObject clDsmObjectHandle );
1584 
1585 
1591 H_DsmCoreInst CDSM_ObjectGetInstance(H_DsmObject clDsmObjectHandle);
1592 
1593 
1594 /*******************************************************************************
1595 * **** NB. ONLY CACHING RULE 'fromStream' CURRENTLY IMPLEMENTED ****
1596 *
1597 * Set caching rules for any (cached) object.
1598 *
1599 * Unless the carousel is specifed in the path, this will load an object from
1600 * the 'Current' object carousel. The client may specify another carousel by
1601 * setting the 'Current' object carousel with use of CDSM_SetCurrentCarousel().
1602 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
1603 * then the function will attempt to load this carousel and make it the new
1604 * 'Current' object carousel.
1605 *
1606 * NOTES:
1607 *
1608 * If the object (OR ANY DIRECTORY ON THE PATH TO THE OBJECT) is not found in
1609 * the cache this command is ignored. Object load failure problems detected at
1610 * call time are not indicated.
1611 *
1612 * If the object is located in the cache the new caching rules are applied
1613 * immediately. If fromStream is set the object is deleted from the cache.
1614 *
1615 * If the object is found in the cache but it is currently loaded the current
1616 * caching rules for this object are set to the specified values (whatever they
1617 * were previously). If fromStream is set, the current object load instance is
1618 * marked for deletion, ie. it is no longer available to subsequent loads
1619 * (although the data is only physically deleted when the object is unloaded
1620 * via clDsmUnloadObject).
1621 *
1622 * Other caching rules are only applied when the object is unloaded.
1623 * If the same object is loaded multiple times in parallel, then these caching
1624 * rules are applied when the last of the object load instances is unloaded.
1625 * Any caching rules set by this call may get overriden if a subsequent parallel
1626 * load of the object that specifies higher priority caching rules is made.
1627 *
1628 * NB. For module based caching (as currently implemented) the whole module
1629 * inherits the caching rules MOST RECENTLY SPECIFIED for any object in that
1630 * module.
1631 *
1632 * The rules for when multiple objects from the same module are requested (or
1633 * loaded) in parallel are applied to a module on the same basis as described
1634 * for multiple instances of the same object.
1635 *
1636 *
1637 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1638 * delSectionFilterFunc
1639 *
1640 * RETURNS:
1641 * CLDSM_OK (0)
1642 * CLDSM_ERR_INVALID_PATHNAME
1643 * CLDSM_ERR_INVALID_CACHING_RULES
1644 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE
1645 * CLDSM_ERR_CAROUSEL_NOT_BOOTED
1646 * CLDSM_ERR_CAROUSEL_LOAD_FAILED
1647 * ?
1648 *
1649 *******************************************************************************/
1650 E_DscError CDSM_SetObjectCachingRules( H_DsmCoreInst instance,
1651  /*I*/ U8BIT *pathname, E_CacheRules cachingRules );
1652 
1653 
1654 
1655 /*******************************************************************************
1656 *
1657 * Request pre-fetch into cache of the specified object.
1658 *
1659 * Unless the carousel is specifed in the path, this will load an object from
1660 * the 'Current' object carousel. The client may specify another carousel by
1661 * setting the 'Current' object carousel with use of CDSM_SetCurrentCarousel().
1662 * If the path does specify a new carousel (as defined by "ETSI TS 102 851"),
1663 * then the function will attempt to load this carousel and make it the new
1664 * 'Current' object carousel.
1665 *
1666 * NOTES:
1667 *
1668 * The pre-fetch is always 'silent', ie. no notification is given when (or
1669 * whether) the object has been pre-fetched into the cache (ie. object load
1670 * failure errors detected at start time are also not indicated). If the object
1671 * is already in the cache then the pre-fetch request is ignored.
1672 *
1673 * Pre-fetches work like load requests (ie. they are always performed) but
1674 * if necessary, load requests (clDsmLoadObject) have priority on section filter
1675 * resources.
1676 *
1677 * If the object has to be fetched into the cache then it is given the default
1678 * caching rules (nb. fromStream is not set!).
1679 *
1680 * **** NOT YET IMPLEMENTED ****
1681 * If timeout value is set to zero it means no (ie. infinite) timeout. If a
1682 * timeout is specified and the object has not been pre-fetched in the specified
1683 * time (for any reason) then the pre-fetch request is abandoned (silently).
1684 * Timeout is expressed in periods of timerResolution (specified at
1685 * setup/create).
1686 *
1687 *
1688 * CALLBACKS THAT MAY BE INITIATED DURING THIS CALL:
1689 * addSectionFilterFunc
1690 * startTimerFunc
1691 * startSIQueryFunc
1692 *
1693 * RETURNS:
1694 * CLDSM_OK (0)
1695 * CLDSM_ERR_MEM_HEAP_FULL
1696 * CLDSM_ERR_INVALID_PATHNAME
1697 * CLDSM_ERR_INVALID_CAROUSEL_HANDLE
1698 * CLDSM_ERR_CAROUSEL_NOT_BOOTED
1699 * CLDSM_ERR_CAROUSEL_LOAD_FAILED
1700 * ?
1701 *
1702 *******************************************************************************/
1703 E_DscError CDSM_PrefetchObject( H_DsmCoreInst instance,
1704  /*I*/ U8BIT *pathname, U32BIT timeout );
1705 
1706 
1707 
1750 E_DscError CDSM_StreamEventSubscribe(
1751  /*I*/ H_DsmCoreInst dsmccInstance,
1752  /*I*/ H_DsmObject streamObject,
1753  /*I*/ U8BIT *eventName,
1754  /*I*/ S_UserInfo *pUserInfo,
1755  /*O*/ H_DsmEvent *pEventHandle );
1756 
1757 
1773 E_DscError CDSM_StreamEventUnsubscribe(
1774  /*I*/ H_DsmCoreInst dsmccInstance,
1775  /*I*/ H_DsmEvent eventHandle );
1776 
1777 
1812 E_DscError CDSM_SpecialEventSubscribe(
1813  /*I*/ H_DsmCoreInst dsmccInstance,
1814  /*I*/ U8BIT *name,
1815  /*I*/ U16BIT associationTag,
1816  /*I*/ U16BIT eventId,
1817  /*I*/ S_UserInfo *pUserInfo,
1818  /*O*/ H_DsmEvent *pEventHandle );
1819 
1820 
1833 E_DscError CDSM_SpecialEventUnsubscribe(
1834  /*I*/ H_DsmCoreInst dsmccInstance,
1835  /*I*/ H_DsmEvent eventHandle );
1836 
1852 E_DscError CDSM_StreamUnsubscribeEvent(
1853  /*I*/ H_DsmCoreInst idp,
1854  /*I*/ S_UserInfo *pUserInfo);
1855 
1856 
1867  /*I*/ H_DsmCoreInst idp,
1868  /*I*/ U32BIT carouselId);
1869 
1870 /* ---------------------- ASYNCHRONOUS CLIENT API CALLS --------------------- */
1871 
1872 /*
1873 -- NOTES:
1874 --
1875 -- These functions can always be called asynchronously (ie. from a different
1876 -- task/thread) since they can only access an individual object/file data area
1877 -- which must have first been opened (& locked) by a previous synchronous API
1878 -- call.
1879 --
1880 */
1881 
1882 
1883 /*******************************************************************************
1884 * Get specified object kind (also returned by clDsmOpenObject)
1885 *
1886 * The object (clDsmObjectHandle) must be LOADED.
1887 *
1888 * NB. This can also be called to poll for when an object is loaded.
1889 *
1890 * RETURNS:
1891 * CLDSM_OK (0)
1892 * CLDSM_ERR_INVALID_OBJECT_HANDLE
1893 * CLDSM_ERR_OBJECT_NOT_LOADED
1894 *
1895 *******************************************************************************/
1896 E_DscError CDSM_ObjectGetKind(
1897  /*I*/ H_DsmObject clDsmObjectHandle,
1898  /*O*/ E_DsmObjectKind *pKind );
1899 
1900 
1901 
1902 /*******************************************************************************
1903 * Get specified object carousel handle.
1904 *
1905 * The object (clDsmObjectHandle) must be LOADED.
1906 *
1907 * NB. This can also be called to poll for when an object is loaded.
1908 *
1909 * RETURNS:
1910 * CLDSM_OK (0)
1911 * CLDSM_ERR_INVALID_OBJECT_HANDLE
1912 * CLDSM_ERR_INVALID_OBJECT_TYPE
1913 * CLDSM_ERR_OBJECT_NOT_LOADED
1914 *
1915 *******************************************************************************/
1916 E_DscError CDSM_ObjectGetCarouselHandle(
1917  /*I*/ H_DsmObject clDsmObjectHandle,
1918  /*O*/ void **hCarouselHandle );
1919 
1920 
1921 
1922 /* -- SERVICE GATEWAY ACCESS FUNCS -- */
1923 
1924 
1925 
1959 E_DscError CDSM_ObjectGetServiceContext(
1960  /*I*/ H_DsmObject clDsmObjectHandle,
1961  /*I*/ U32BIT serviceId,
1962  /*O*/ U8BIT **pSrvCtxtData,
1963  /*O*/ U32BIT *pSrvCtxtLen);
1964 
1965 
1966 /* -- FILE OBJECT ACCESS FUNCS -- */
1967 
1968 /*******************************************************************************
1969 * Get length of specified file data
1970 *
1971 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
1972 *
1973 * RETURNS:
1974 * CLDSM_OK (0)
1975 * CLDSM_ERR_INVALID_OBJECT_HANDLE
1976 * CLDSM_ERR_INVALID_OBJECT_TYPE
1977 * CLDSM_ERR_OBJECT_NOT_LOADED
1978 * CLDSM_ERR_OBJECT_NOT_OPEN
1979 * ?
1980 *
1981 *******************************************************************************/
1982 E_DscError CDSM_FileGetSize(
1983  /*I*/ H_DsmObject clDsmFileObjectHandle,
1984  /*O*/ U32BIT *pSize );
1985 
1986 
1987 
1988 /*******************************************************************************
1989 * Read specified number of bytes of data from (opened) file into
1990 * destination address, starting at the current 'cursor' ('file' ptr) position.
1991 *
1992 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The
1993 * destination memory area MUST be large enough to hold the numBytes requested.
1994 *
1995 * If call attempts to read past end of the file data it will read as many
1996 * bytes as possible and returns error code: CLDSM_ERR_END_OF_DATA
1997 *
1998 * Number of bytes read is stored in pNumBytesActual and 'cursor' position is
1999 * incremented by numBytesActual.
2000 *
2001 * RETURNS:
2002 * CLDSM_OK (0)
2003 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2004 * CLDSM_ERR_INVALID_OBJECT_TYPE
2005 * CLDSM_ERR_OBJECT_NOT_LOADED
2006 * CLDSM_ERR_OBJECT_NOT_OPEN
2007 * CLDSM_ERR_END_OF_DATA
2008 * ?
2009 *
2010 *******************************************************************************/
2011 E_DscError CDSM_FileRead(
2012  /*I*/ H_DsmObject clDsmFileObjectHandle, U32BIT numBytes,
2013  /*O*/ U8BIT *pDest, U32BIT *pNumBytesActual );
2014 
2015 /*******************************************************************************
2016 * Returns pointer to file data and number of bytes in the file.
2017 *
2018 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN. The
2019 * destination memory area MUST be large enough to hold the numBytes requested.
2020 *
2021 * Number of bytes read is stored in pNumBytesActual.
2022 *
2023 * RETURNS:
2024 * CLDSM_OK (0)
2025 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2026 * CLDSM_ERR_OBJECT_NOT_LOADED
2027 *
2028 *******************************************************************************/
2029 E_DscError CDSM_FileDirect(
2030  /*I*/ H_DsmObject clDsmFileObjectHandle,
2031  /*O*/ U8BIT **ppDest, U32BIT *pNumBytesActual );
2032 
2033 
2034 /*******************************************************************************
2035 * Read single byte of data from (opened) file at current 'cursor' position
2036 * into destination and increment 'cursor' position.
2037 *
2038 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
2039 *
2040 * If call attempts to read past end of the object data, returns error code:
2041 * CLDSM_ERR_END_OF_DATA
2042 *
2043 * RETURNS:
2044 * CLDSM_OK (0)
2045 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2046 * CLDSM_ERR_INVALID_OBJECT_TYPE
2047 * CLDSM_ERR_OBJECT_NOT_LOADED
2048 * CLDSM_ERR_OBJECT_NOT_OPEN
2049 * CLDSM_ERR_END_OF_DATA
2050 * ?
2051 *
2052 *******************************************************************************/
2053 E_DscError CDSM_FileReadByte(
2054  /*I*/ H_DsmObject clDsmFileObjectHandle,
2055  /*O*/ U8BIT *pDest );
2056 
2057 
2058 
2059 /*******************************************************************************
2060 * Set absolute file data 'cursor' position
2061 *
2062 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
2063 *
2064 * Cursor can point to any byte in file data AND to notional 'position'
2065 * immediately after last byte of data but setting to anywhere else will return
2066 * error code: CLDSM_ERR_END_OF_DATA
2067 *
2068 * RETURNS:
2069 * CLDSM_OK (0)
2070 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2071 * CLDSM_ERR_INVALID_OBJECT_TYPE
2072 * CLDSM_ERR_OBJECT_NOT_LOADED
2073 * CLDSM_ERR_OBJECT_NOT_OPEN
2074 * CLDSM_ERR_END_OF_DATA
2075 * ?
2076 *
2077 *******************************************************************************/
2078 E_DscError CDSM_FileSetPosAbs(
2079  /*I*/ H_DsmObject clDsmFileObjectHandle, U32BIT absPosition );
2080 
2081 
2082 
2083 /*******************************************************************************
2084 * Set file data 'cursor' position relative to current position
2085 *
2086 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
2087 *
2088 * Cursor can point to any byte in file data AND to notional 'position'
2089 * immediately after last byte of data but setting to anywhere else will return
2090 * error code: CLDSM_ERR_END_OF_DATA
2091 *
2092 * RETURNS:
2093 * CLDSM_OK (0)
2094 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2095 * CLDSM_ERR_INVALID_OBJECT_TYPE
2096 * CLDSM_ERR_OBJECT_NOT_LOADED
2097 * CLDSM_ERR_OBJECT_NOT_OPEN
2098 * CLDSM_ERR_END_OF_DATA
2099 * ?
2100 *
2101 *******************************************************************************/
2102 E_DscError CDSM_FileSetPosRel(
2103  /*I*/ H_DsmObject clDsmFileObjectHandle, S32BIT relPosition );
2104 
2105 
2106 
2107 /*******************************************************************************
2108 * Read (absolute) file data 'cursor' position
2109 *
2110 * The file object (clDsmFileObjectHandle) must be LOADED and OPEN.
2111 *
2112 * Value returned in 'position' is the offset (in bytes) from the start (zero
2113 * position) of the file data to the current cursor position.
2114 *
2115 * If the current cursor position points to past the end of the file data, then
2116 * the position returned is equal to the file data size. Note that it is not
2117 * legal to _read_ data from this cursor position/offset.
2118 *
2119 * RETURNS:
2120 * CLDSM_OK (0)
2121 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2122 * CLDSM_ERR_INVALID_OBJECT_TYPE
2123 * CLDSM_ERR_OBJECT_NOT_LOADED
2124 * CLDSM_ERR_OBJECT_NOT_OPEN
2125 * ?
2126 *
2127 *******************************************************************************/
2128 E_DscError CDSM_FileGetPos(
2129  /*I*/ H_DsmObject clDsmFileObjectHandle,
2130  /*O*/ U32BIT *pPosition );
2131 
2132 
2133 /* -- DIRECTORY ACCESS FUNCS -- */
2134 
2135 /*******************************************************************************
2136 *
2137 * The directory object (dirObj) must be LOADED and OPEN.
2138 *
2139 * Retrieves the total number of directory entries and the total length of all
2140 * entry names.
2141 *
2142 * RETURNS:
2143 * CLDSM_OK (0)
2144 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2145 * CLDSM_ERR_INVALID_OBJECT_TYPE
2146 * CLDSM_ERR_OBJECT_NOT_LOADED
2147 * CLDSM_ERR_OBJECT_NOT_OPEN
2148 *
2149 *******************************************************************************/
2150 E_DscError CDSM_DirEntrySizes(
2151  /*I*/ H_DsmObject dirObj,
2152  /*O*/ U16BIT *nameCount,
2153  /*O*/ U16BIT *totalNameLength );
2154 
2155 /*******************************************************************************
2156 *
2157 * The directory object must be LOADED and OPEN.
2158 *
2159 * Retrieve the first entry handle
2160 *
2161 * RETURNS:
2162 * CLDSM_OK (0)
2163 * CLDSM_ERR_INVALID_OBJECT_HANDLE
2164 * CLDSM_ERR_INVALID_OBJECT_TYPE
2165 * CLDSM_ERR_OBJECT_NOT_LOADED
2166 * CLDSM_ERR_OBJECT_NOT_OPEN
2167 * CLDSM_ERR_END_OF_DATA
2168 *
2169 *******************************************************************************/
2170 E_DscError CDSM_DirEntryFirst(
2171  /*I*/ H_DsmObject dirObj,
2172  /*O*/ void **pFirstEntry );
2173 
2174 /*******************************************************************************
2175 *
2176 * Directory entry handle (entryHandle) is return by dsmDirEntryFirst or
2177 * dsmDirEntryNext.
2178 *
2179 * Retrieve the next entry handle
2180 *
2181 * RETURNS:
2182 * CLDSM_OK (0)
2183 * CLDSM_ERR_INTERNAL
2184 *
2185 *******************************************************************************/
2186 E_DscError CDSM_DirEntryNext(
2187  /*I*/ void *entryHandle,
2188  /*O*/ void **pNextEntry );
2189 
2190 /*******************************************************************************
2191 *
2192 * The directory entry handle is return by dsmDirEntryFirst or
2193 * dsmDirEntryNext.
2194 *
2195 * Retrieve name length
2196 *
2197 * RETURNS:
2198 * Length of name copied
2199 *
2200 *******************************************************************************/
2201 U16BIT CDSM_DirEntryNameLength(
2202  /*I*/ void *entryHandle );
2203 
2204 /*******************************************************************************
2205 *
2206 * The directory entry handle is return by dsmDirEntryFirst or
2207 * dsmDirEntryNext.
2208 *
2209 * Copy name for entry to supplied memory location (pName)
2210 * Caller should ensure there is enough space in location
2211 *
2212 * RETURNS:
2213 * Length of name copied
2214 *
2215 *******************************************************************************/
2216 U16BIT CDSM_DirEntryNameCopy(
2217  /*I*/ void *entryHandle,
2218  /*O*/ U8BIT *pName );
2219 
2220 /*******************************************************************************
2221 *
2222 * Get the kind of entry this is
2223 *
2224 * RETURNS:
2225 * E_DsmObjectKind
2226 *
2227 *******************************************************************************/
2228 E_DsmObjectKind CDSM_DirEntryKind( void *entryHandle );
2229 
2230 
2231 /* -- STREAM OBJECT ACCESS FUNCS -- */
2232 
2263 E_DscError CDSM_StreamGetDeferredService( H_DsmCoreInst instance,
2264  /*I*/ H_DsmObject streamObject, void *userData1, void *userData2,
2265  /*O*/ S_DvbLocator **ppDeferredService );
2266 
2267 /* -- STREAM EVENT ACCESS FUNCS -- */
2268 
2295 E_DscError CDSM_StreamEventNameList(
2296  /*I*/ H_DsmCoreInst dsmccInstance,
2297  /*I*/ H_DsmObject streamObject,
2298  /*O*/ U8BIT **pNamesPtr, U16BIT *pNamesLen );
2299 
2315 E_DscError CDSM_StreamEventXmlData(
2316  /*I*/ H_DsmCoreInst dsmccInstance,
2317  /*I*/ H_DsmObject streamObject,
2318  /*O*/ U8BIT **ppXmlData, U16BIT *pXmlLen);
2319 
2320 U32BIT CDSM_UtilCalculateCRC(U8BIT *msg, U32BIT len);
2321 
2322 /*----------------------------------------------------------------------------*/
2323 
2324 #ifdef __cplusplus
2325 }
2326 #endif
2327 #endif /* _DSMCC_H_ */
2328 
E_DscError CDSM_StreamEventNameList(H_DsmCoreInst dsmccInstance, H_DsmObject streamObject, U8BIT **pNamesPtr, U16BIT *pNamesLen)
The Client uses this function to request list of event names for stream object Before calling this fu...
Definition: streamEvent.c:1471
E_DscError CDSM_StreamGetDeferredService(H_DsmCoreInst instance, H_DsmObject streamObject, void *userData1, void *userData2, S_DvbLocator **ppDeferredService)
The Client calls this function to obtain the Association Tag which can be used to determine the PID o...
Definition: streamObject.c:141
E_DscError CDSM_SpecialEventUnsubscribe(H_DsmCoreInst dsmccInstance, H_DsmEvent eventHandle)
Same as clDsmStreamEventUnsubscribe - used in conjuction with clDsmSpecialEventSubscribe.
Definition: streamEvent.c:753
E_DscError CDSM_GetCarouselId(H_DsmCoreInst instance, H_DsmCarousel carouselHandle, U32BIT *pCarouselId)
Retrieve Carousel Id for the loaded DSM-CC Object Carousel.
Definition: clDsmClientMain.c:218
E_DscError CDSM_CarouselUnloadFileGroups(H_DsmCoreInst instance, H_DsmCarousel clDsmCarouselHandle, S_CarouselInfoFileGroup *groups)
Release "File Group Info" data allocated by used by CDSM_CarouselLoadFileGroups() ...
Definition: clDsmClientMain.c:331
H_DsmCoreInst CDSM_ObjectGetInstance(H_DsmObject clDsmObjectHandle)
Get DSM instance to which the object belongs.
Definition: clDsmClientMain.c:1113
Definition: cldsmcc.h:620
H_DsmCarousel CDSM_CurrentCarousel(H_DsmCoreInst instance)
Retrieve handle to the current carousel for DSM-CC Instance.
Definition: clDsmClientMain.c:250
Definition: clDsmSystem.h:535
Definition: dvblocator.h:30
void(* F_NotifyStreamEvent)(H_DsmEvent eventHandle, E_StreamEventStatus status, S_UserInfo userInfo, U8BIT *namePtr, U8BIT *dataPtr, U8BIT namelen, U8BIT dataLen)
The Client defines this function to enable the DSMCC to communicate to the Client when any subscribed...
Definition: cldsmcc.h:584
E_DscError CDSM_StreamEventXmlData(H_DsmCoreInst dsmccInstance, H_DsmObject streamObject, U8BIT **ppXmlData, U16BIT *pXmlLen)
The Client uses this function to request data in XML format for stream object and associated events...
Definition: streamEvent.c:1502
E_DscError CDSM_CarouselLoadFileGroups(H_DsmCoreInst instance, H_DsmCarousel clDsmCarouselHandle, U16BIT *total, S_CarouselInfoFileGroup **pGroups)
Retrieve from Object Carousel&#39;s User Info, the "File Group Info" used by Australia and South Africa M...
Definition: clDsmClientMain.c:285
E_DscError CDSM_SetCurrentCarousel(H_DsmCoreInst instance, H_DsmCarousel carouselHandle)
Sets current carousel for DSM-CC Instance.
Definition: clDsmClientMain.c:255
H_DsmControl CDSM_SysGetControl(H_DsmCoreInst instance)
Get control handle from DSM instance .
Definition: clDsmMain.c:547
E_DscError CDSM_SysProcessTimerEvent(H_DsmCoreInst instance, void *clDsmTmrUserData, E_TimerStatus status, void *timerHandle)
Definition: clDsmMain.c:931
E_DscError CDSM_UnloadModule(H_DsmCoreInst idp, H_DsmCarousel hCarousel, U32BIT moduleRef)
Unload SSU module. To be called once the client has finished saving this module data.
Definition: clDsmClientMain.c:514
DSM-CC global types header Used by SI Query and Section Filter code.
Definition: cldsmtypes.h:155
File System types.
E_DscError CDSM_SysProcessSIQueryEvent(H_DsmCoreInst instance, H_SIQueryRef clDsmSIQueryRef, void *clDsmSIUserData, P_SIQueryResult pResult)
Notifies the result of the specified SI query (ie. a callback to startSIQueryFunc that returned SIQUE...
Definition: clDsmMain.c:1049
E_DscError CDSM_LoadCarousel(H_DsmCoreInst instance, U16BIT service_id, U32BIT carousel_id, E_SIQueryKind kind, H_DsmCarousel *pclDsmCarouselHandle)
Request load of a DSM-CC Object Carousel (service domain).
Definition: clDsmClientMain.c:78
Definition: dsm_client.c:57
E_DscError CDSM_UnloadObject(H_DsmCoreInst instance, H_DsmObject clDsmObjectHandle, E_DsmRstMode mode)
Unload (or cancel the requested load of) a DSM-CC object The client MUST first close and/or unsubscri...
Definition: clDsmClientMain.c:747
Definition: siq_main.h:33
void(* F_NotifyDeferredService)(void *userData1, void *userData2, S_DvbLocator *pDeferredService)
Called when request for deferred service of stream object has completed after clDsmStreamGetDeferredS...
Definition: cldsmcc.h:604
Definition: cldsmtypes.h:193
void CDSM_SysSetMemoryMax(H_DsmCoreInst instance, U32BIT maxMemory)
Set maximum memory usage.
Definition: clDsmMain.c:787
E_DscError CDSM_UnloadCarousel(H_DsmCoreInst instance, H_DsmCarousel clDsmCarouselHandle, E_DsmRstMode mode)
Unload (or cancel the requested load of) a DSM-CC Object Carousel (service domain). The client MUST first unload all objects before calling this function (which implies it must also have previously closed and/or unsubscribed any events on any loaded objects). If there are any active object loads in the carousel when clDsmUnloadCarousel is called then the unload will not be executed and an error returned. If the carousel is in the process of loading and/or booting the load operation will be aborted (and the notifyCarouselLoadEventFunc callback made with status OC_LOAD_ABORTED_UNLOAD). Any carousel load request that returned a valid CDSM_CarouselHandle(ie. did not generate an error at clDsmLoadCarousel call time), must be explicitly unloaded via clDsmUnloadCarousel. This is necessary, whether the carousel was successfully loaded or the load was aborted due to timeout or error. Once unload is called for a carousel, the clDsmCarouselHandle is no longer valid and must not be used by the client/calling env. If it needs to access the carousel subsequently it must re-load it and get a new clDsmCarouselHandle value. To forcefully destroy loaded objects and/or carousels (eg. where the handles may be unknown/lost) then clDsmReset can be used with force switches. Note that this physically deletes them from the cache whereas unloading (objects or carousels) does not. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: delSectionFilterFunc stopTimerFunc stopSIQueryFunc unsubscribeSIChange notifyCarouselLoadEventFunc.
Definition: clDsmClientMain.c:374
E_DscError CDSM_OpenObject(H_DsmCoreInst instance, H_DsmObject clDsmObjectHandle, E_DsmObjectKind *pKind)
Open object data for subsequent access via API functions for given object kind. The object must have ...
Definition: clDsmClientMain.c:931
E_DscError CDSM_SpecialEventSubscribe(H_DsmCoreInst dsmccInstance, U8BIT *name, U16BIT associationTag, U16BIT eventId, S_UserInfo *pUserInfo, H_DsmEvent *pEventHandle)
Like clDsmStreamEventSubscribe, except that no stream object is required. This function subscribes to...
Definition: streamEvent.c:530
E_DscError CDSM_StreamEventUnsubscribe(H_DsmCoreInst dsmccInstance, H_DsmEvent eventHandle)
This function is called by the Client to let DSMCC know when a previously subscribed stream event is ...
Definition: streamEvent.c:691
Definition: cldsmcc.h:208
E_DscError CDSM_SysSetCurrService(H_DsmCoreInst instance, U16BIT original_network_id, U16BIT transport_stream_id, U16BIT service_id)
Set/notify the current service (initially and when changing it). This MUST be called initially (ie...
Definition: clDsmMain.c:834
Definition: fs_types.h:46
Definition: cldsmtypes.h:212
E_DscError CDSM_StreamUnsubscribeEvent(H_DsmCoreInst idp, S_UserInfo *pUserInfo)
This function is called by the Client to let DSMCC know when a previously subscribed stream event is ...
Definition: streamEvent.c:775
Definition: dsm_types.h:213
E_DscError CDSM_StreamEventSubscribe(H_DsmCoreInst dsmccInstance, H_DsmObject streamObject, U8BIT *eventName, S_UserInfo *pUserInfo, H_DsmEvent *pEventHandle)
The Client uses this function to request that the DSMCC notifies it when a named stream event occurs...
Definition: streamEvent.c:360
E_DscError CDSM_SysReset(H_DsmCoreInst instance, E_DsmRstMode mode)
Reset DSM-CC Core Layer instance. Resets conditions to the same state as after CDSM_SysCreate(ie. keeps setup parameters). In normal operation the client MUST first unsubscribe all events, close and and unload all objects and unload all carousels before calling this function. This will have also stopped/deleted all associated system resources (ie. SI queries, timers, SI change monitors, section filters). If any client transactions or system transactions are still active when clDsmReset is called the reset will not be executed and an error returned. NB. The calling environment (system side) must acknowledge stop commands for SI Queries and timers (via processSIQueryEvent, processTimerEvent) and that these may occur asynchronously (ie. after a delay). This means that there may still be some active system transactions for some time after all objects and carousels are unloaded. FORCING RESET IN ERROR CONDITIONS: If all client and system transactions are apparently completed but still returns an error (eg. because handles are unknown/lost or system resource stop requests are not acknowledged) then clDsmReset can be called with appropriate force switches to clear the error condition. Any client transaction errors must first be cleared before system transaction errors can be cleared and both force switches cannot be set at the same time. NB. Only use force switches in known error conditions. It is potentially fatal (may cause illegal memory access) to call the functions: streamEventUnsubscribe, unloadObject, unloadCarousel, processSIQueryEvent, processTimerEvent with old/stale handles after clDsmReset has been forced. CALLBACKS THAT MAY BE INITIATED DURING THIS CALL: deleteSectionFilter stopTimer stopSIQuery unsubscribeSIChange.
Definition: clDsmMain.c:684
E_DscError CDSM_SysDestroy(H_DsmCoreInst instance, H_SiqInstance *pSiqInst, H_SfmInstance *pSfmInst)
Destroy DSM-CC Core Layer instance. De-allocates all &#39;static&#39; memory used by the instance (via freeFu...
Definition: clDsmMain.c:480
void CDSM_StreamEventUnload(H_DsmCoreInst idp, U32BIT carouselId)
This function is called by the Client to unload any stream event loaded from a stream object on the g...
Definition: streamEvent.c:810
Definition: sfm_main.h:36
E_DscError CDSM_SysProcessSIChangeEvent(H_DsmCoreInst instance, E_SIChangeEvent evnt, U16BIT service_id, U32BIT carousel_id)
Notify that the SI for the indicated service has changed Changes should be notified in the following ...
Definition: clDsmMain.c:1128
Define standard function types.
E_DscError CDSM_ObjectGetServiceContext(H_DsmObject clDsmObjectHandle, U32BIT serviceId, U8BIT **pSrvCtxtData, U32BIT *pSrvCtxtLen)
This function gets service context of DSM object (if available) Need by MHEG5 for specified service g...
Definition: clDsmClientMain.c:1387
Definition: dsmObject.h:58
Definition: dsm_client.c:44