DAB/MOT Data Carousel System Support Library Interface...

DAB/MOT Data CarouselSystem Support Library

Interface Definition

D. Knox & O. Gardiner

98-0003-001/1.3

5th Jul 1999

ENSIGMA LtdTuring HouseStation RoadChepstowGWENTNP6 5PB

Ensigma Ltd. of 955th Jul 1999 98-0003-001/1.3

Distribution

Client

O. Gardiner

Ensigma Ltd

Project File


Contents

1. Introduction.................................................................................. 8

1.1 Change Control ........................................................................................ 8

1.1.1 Release Summary ........................................................................... 8

1.1.2 Changes .......................................................................................... 81.1.2.1 Changes in version 1.1 ...................................................................... 8

1.2 Intended Audience ................................................................................... 8

1.3 Summary................................................................................................... 8

2. System Overview ....................................................................... 10

2.1 Server ...................................................................................................... 11

2.1.1 Carousel Maintenance Model ........................................................ 12

2.2 Client ....................................................................................................... 12

3. Interface Definitions .................................................................. 14

3.1 Function Definitions............................................................................... 14

3.2 Function Naming Conventions ............................................................. 14

3.3 Data Types .............................................................................................. 15

3.3.1 File arguments ............................................................................... 16

3.3.2 Character string arguments ........................................................... 16

3.3.3 Enumerated types.......................................................................... 16

3.3.4 Handles.......................................................................................... 16

3.4 Error Handlers ........................................................................................ 16

ErrorHandler............................................................................................. 19

3.5 DAB Packet Data Group transport configuration ................................ 20

4. Server library.............................................................................. 22

4.1 Module Identification ............................................................................. 22

4.2 Version Control ...................................................................................... 22

4.2.1 Carousel Capacity.......................................................................... 23

4.3 Spooler Interaction................................................................................. 23


4.4 Module Descriptors................................................................................ 24

4.5 Server Interface Summary..................................................................... 24

MCSRVCarouselInfo ................................................................................ 26

MCSRVCloseCarousel............................................................................. 27

MCSRVControlFrequency........................................................................ 28

MCSRVCRC............................................................................................. 29

MCSRVCreateCarousel ........................................................................... 30

MCSRVCreateModule.............................................................................. 32

MCSRVDataRate ..................................................................................... 33

MCSRVDeleteCarousel............................................................................ 34

MCSRVDeleteModule .............................................................................. 35

MCSRVDescribeCarousel........................................................................ 36

MCSRVDescribeModule .......................................................................... 37

MCSRVErrorHandler................................................................................ 38

MCSRVFirstModule.................................................................................. 39

MCSRVHeaders....................................................................................... 40

MCSRVLocateModule.............................................................................. 41

MCSRVMatchModule............................................................................... 42

MCSRVModuleAccount............................................................................ 44

MCSRVModuleFrequency........................................................................ 45

MCSRVModuleInfo .................................................................................. 46

MCSRVModuleSize.................................................................................. 48

MCSRVNextModule ................................................................................. 49

MCSRVNextCarouselInfo......................................................................... 50

MCSRVNextModuleInfo ........................................................................... 52

MCSRVOpenCarousel ............................................................................. 54

MCSRVRestartCarouselInfo .................................................................... 55

MCSRVRestartModuleInfo ....................................................................... 56

MCSRVSegSize ....................................................................................... 57

MCSRVSpoolerStatistics.......................................................................... 58

MCSRVSpoolerStatus.............................................................................. 60

MCSRVStartSpooler ................................................................................ 61

MCSRVStopSpooler................................................................................. 62

MCSRVSyncCarousel .............................................................................. 63

MCSRVUpdateModule ............................................................................. 64

MCSRVUpdateSpooler ............................................................................ 65


MCSRVVersions ...................................................................................... 67

5. Client library............................................................................... 68

5.1 Access to Modules and Data................................................................. 68

5.2 Changing Data ........................................................................................ 68

5.3 Cache Hints ............................................................................................ 69

5.4 Time-outs ................................................................................................ 69

5.5 Client Interface Summary ...................................................................... 71

MCCLICarouselInfo.................................................................................. 73

MCCLICloseCarousel............................................................................... 74

MCCLICloseModule ................................................................................. 75

MCCLIErrorHandler.................................................................................. 76

MCCLIFirstModule ................................................................................... 77

MCCLILocateModule................................................................................ 78

MCCLIMatchModule................................................................................. 79

MCCLIModuleInfo .................................................................................... 81

MCCLIModuleSize ................................................................................... 82

MCCLINextModule ................................................................................... 83

MCCLINextCarouselInfo .......................................................................... 84

MCCLINextModuleInfo ............................................................................. 86

MCCLIOpenCarousel ............................................................................... 88

MCCLIOpenModule.................................................................................. 89

MCCLIPositionModule.............................................................................. 90

MCCLIReadModule.................................................................................. 91

MCCLIStats.............................................................................................. 92

MCCLITimeout ......................................................................................... 93

MCCLIZeroStats....................................................................................... 94

6. References ................................................................................. 95


List of Tables

Table 1 Library Name Prefixes ............................................................................................ 15

Table 2 Interface data types.................................................................................................. 15

Table 3 Error Severity Codes ............................................................................................... 18

Table 4 Module access codes ............................................................................................... 69


List of Figures

Figure 1 Data Carousel Server ............................................................................................. 11

Figure 2 Data Carousel Client .............................................................................................. 13


1. Introduction

This document describes a software library to support the development of data carouselapplications for DAB.

1.1 Change Control

1.1.1 Release Summary

Version Description

1.0 Initial Version

1.1 Various corrections

1.1.2 Changes

1.1.2.1 Changes in version 1.1

1. Inadvertent comments and typographical errors fixed.

2. Missing description of MCSRVDataRate added.

3. MCSRVModuleInfo and MCCLIModuleInfo modified to handle NULL descarguments.

4. Description of MCSRVDescribeModule corrected.

5. MCSRVModuleSize and MCCLIModuleSize added.

1.2 Intended Audience

This is a technical report intended for software designers familiar with the communicationsprotocols and messaging formats used within digital broadcasting and multi-media systems.

1.3 Summary

The term data carousel describes a system in which a static data set is repeatedly broadcastso that it may be accessed as required by many receivers. A common class of applicationsuses data carousels to carry a representation of a computer file system. One way ofimplementing a data carousel is to use the MOT protocol defined in [1] to carry directoryand file objects and to broadcast these objects repeatedly


This document defines a software library intended to help programmers with theimplementation of applications based on data carousels transported using MOT. It providestwo related function libraries. One is for use by the broadcaster to construct applicationserver programs (which generate, maintain and transmit the messages defining thecarousel). The second is for use in receiving systems which must decode the messages andextract the data.


2. System Overview

A data carousel is a system in which a number of data modules are repeatedly broadcast ina standardised format.

A data carousel application has two components—

• A server program operated by the broadcaster which maps application specific datainto the standardised format and then transmits it repeatedly.

• A client program, operating within receivers, performs a reverse mapping from thestandardised format to retrieve the application specific data in a form meaningful tothe application.

The data carousels discussed in this document are carried using the MOT protocol asdescribed in [1].


2.1 Server

Figure 1 illustrates the application server environment. The server program creates andupdates the data carousel, by mapping a set of files onto a set of modules and associatedcontrol information which define the carousel. Updates performed by the server applicationare applied to a working copy of the carousel. They are not immediately reflected in thedata being broadcast. Once a consistent carousel is available, it can be frozen. This createsa snapshot of the carousel state, which is coded as a set of DAB data groups according tothe MOT protocol. Further changes to the carousel can then be made by the application

DABPacket

Encoder

Spooler

Server Application

MOT codedcarousel

Carousel underdevelopment

FreezeCarousel

DABPackets

VFS Server Library

DAB PacketData Groups

Server Library Interface

Figure 1 Data Carousel Server


while the snapshot is being transmitted. The carousel must be frozen again for thesechanges to appear in the broadcast data.

The spooler takes a repeating sequence of DAB packet data groups from the frozen versionof the carousel and passes these on to the DAB packet transmission system. Because thespooler’s access to the carousel data must be synchronised with updates generated by theserver application, the spooler is implemented as part of the library and is controlledthrough server library functions..

Applications differ in the source of their data and in the nature of the mapping onto datacarousel modules. However, all applications can use common facilities to create andmanage their representation of the data carousel.

The server library, described in this document, implements these common parts of datacarousel application servers and the spooler system.

2.1.1 Carousel Maintenance Model

By their nature, data carousels are fairly static structures but, from time to time, theircontents change and the server library must support such changes. The maintenance systemis based on the concept of a frozen “snapshot” of the carousel. Changes to the carousel areaccumulated internally but are not reflected in the data provided to the spooler until aformal “update” notification is issued. This allows carousels to be built and alteredincrementally, without requiring that the data be fully validated and self consistent at everyintermediate step.

2.2 Client

Several client (receiver) application architectures are possible. For example, three likelyvariants are—

• Client reads DAB packet data groups off-air as required.

• Client builds a local representation of the carousel and used it to service applicationrequests.

• Client caches parts of the carousel and satisfies application requests from this cacheor off-air depending on whether the data is available.

The current implementation uses a multi-processing client-server model in which a cachemanager process services requests for carousel data from a number of clients. This isillustrated in Figure 2. However, the library interface makes no assumptions about theunderlying implementation. Applications developed using the library should be portable toother implementations.


DABPacket

Decoder

ReaderClient

Client Application

Cache

CacheServer

DABPackets

DAB VFS Client Library



MOT Data Groups

MOT Data Groups

Client Library Interface

Figure 2 Data Carousel Client


3. Interface Definitions

The programmers’ interface to the libraries is defined in terms of a set of functions andassociated data types.

3.1 Function Definitions

The library functions are defined as a set of C prototypes. Note that choosing the Clanguage binding to define the interface behaviour does not necessarily imply that either thelibraries or the applications using them will actually be written in C, merely that theinterfaces will behave as if they were. The choice of C as the defining language is arbitrarybut pragmatic—

• In most environments, other languages have mechanisms for calling C compatiblelibrary functions. The converse is not always the case.

• At least for early implementations, the operating system environment will reflecttraditional UNIX culture with a C style.

Other language bindings can be constructed as wrappers around the basic functionalitydescribed here. For example in a C++ environment we might construct a wrapperpresenting the interface in terms of a set of object classes and methods.

3.2 Function Naming Conventions

We have used a standard set of function name prefixes to avoid clashes with other librarieswhich may be required for building application servers and clients. While this does notguarantee to avoid clashes, the risks are substantially reduced. In an extreme case, if a nameclash did occur, the source code could be mechanically processed to change these prefixesconsistently. Table 1 summarises the name prefixes which defined in the currentimplementation.


3.3 Data Types

To aid portability of client and server programs, the library interface is defined in terms of alimited set of data types. In any particular implementation, these will be mapped onto typesavailable in the local language. In the C language binding, this is achieved using a set oftypedefs.

Library Name Prefixes

Prefix Uses

MCSRV Server library names

MCCLI Client library names

MCAR Generic functions, not specific to client or server

DAB DAB data processing functions

Table 1 Library Name Prefixes

Interface Data Types

Type Definition

BYTE 8 bit storage unit with undefined semantics

CHAR Character — synonymous with C char

INT “Natural” signed integer — synonymous with C int.Assumed to have at least 16-bit precision.

LONG “Long” signed integer — assumed to have at least 32bits precision.

VOID Synonym for C void.

CHANDLE Handle for a data carousel

MHANDLE Handle for a module

EHANDLER Pointer to an error handling function. Error handlingfunctions are described in Section 3.4.

Table 2 Interface data types


3.3.1 File arguments

Where it is necessary to pass files to library functions, we limit the interface to file namecharacter strings. This is not a limitation in practice and ensures that language or operatingsystem specific methods of file processing are not embedded in the interface definition1.

3.3.2 Character string arguments

Character string arguments are handled according to the normal C conventions. The actualargument is a pointer to a null-terminated array of characters.

3.3.3 Enumerated types

Where arguments are naturally expressed as an enumeration of logical values, we definethem as integers and specify the numeric representations. Although the equivalencebetween integers and enumerations is natural in C, this is not the case for other languages.By defining numeric rather than symbolic representations we ensure cross languagecompatibility.

3.3.4 Handles

Where it is necessary to refer to a data carousel or to an entity within a carousel, we usehandles. Handles are typed references to hidden data objects. To aid inter-languageworking, implementations will ensure that—

• Handles can be cast to and from C pointers of type void *.

• Although handles can be stored in pointer variables, the only supported means of de-referencing a handle is to pass it as an argument to one of the functions in the library.

• A handle containing a value equivalent to a C NULL pointer is considered invalid.

The interface is defined such that no manipulation of handles is required apart fromassignment or passing them as function arguments.

3.4 Error Handlers

Since the libraries will be used to create a variety of applications in a variety of operatingenvironments, library functions do not attempt to report errors directly to the user. Insteadwe define a mechanism by which an application can establish its own error reportingregime.

The approach to error handling is—

• Functions report simple success/failure indications to their callers.

1 At least beyond the requirement that a file can be represented uniquely by a character string.


• When library functions encounter errors, they call an error handler to deal with anyreporting. This error handler is called when the error occurs, i.e., before the libraryfunction returns.

• An application can replace the supplied error handler with one more suited to itsneeds.

Possible alternative behaviours for error handlers might be to—

• Force program exit.

• Report error messages on stderr (in a UNIX or DOS environment).

• Report error messages in a pop-up dialogue box (in a windowing environment).

• Store error information in a global variable for inspection after the function returns(in the style of UNIX stdio library errno variable).

Application supplied error handlers are provided with an integer code defining the error.However, the set of possible errors will be implementation dependent. For example, in aUNIX implementation, a failure in MCSRVCreateCarousel could be caused by adirectory ownership problem, but in a DOS implementation, this concept does not exist. Toassist applications in reporting errors without necessarily being aware of the full set ofpossible failure conditions, the error handler is provided with three additional pieces ofinformation—

• A severity code. Severity codes are listed in Table 3.

• A constant text message. This is a simple textual description of the failure.

• A variable text message, possibly NULL. Contains additional information. Forexample the name of a file which couldn’t be opened.

A typical handler would—

• Examine the severity code to determine the appropriate style of reporting.

• Concatenate the two text messages with appropriate punctuation and display theresult to the user.

• Store any information required to assist with remedial action by the application afterthe library function returns.

• Force program exit if the error is not recoverable.

Error handlers must conform to C calling semantics for the ErrorHandler templateshown on Page19. The EHANDLER data type is a pointer to such a function.


Error Severity Codes

Code Interpretation

0 Information. Information messages report normal operation of the library.Typically applications will report these only when a “verbose” mode ofoperation is selected by the user.

1 Normal errors. Normal errors are those caused by erroneous use of thelibrary. E.g., bad arguments, forgetting to open a carousel.

2 Data changed errors. These occur only in the client library. See Section 5.1.

3 Time-out errors. These occur only in the client library. See Section 5.4.

4 Severe errors. Severe errors are those which indicate either design problemsinternal to the library or lack of key system resources. E.g., memoryallocation failures, full disks etc. Severe errors will result in malfunctionswithin the library. The only sensible behaviour for an error handler is toforce an immediate exit in response to a severe error.

Table 3 Error Severity Codes


ErrorHandler

Definition:

VOID ErrorHandler(code, severity, text1, text2)

Arguments:

INT code Error code

INT severity Error severity code

CHAR * text1 Error message text

CHAR * text2 Supplementary text (possibly NULL)

Returns:

VOID

Description:

This is a template for customised error handling functions provided by applicationsand established using the MCSRVErrorHandler library function.

The code argument defines the error condition which resulted in the handler call.The complete set of error codes is implementation dependent. For maximumportability, application writers may prefer to limit themselves to acting in response tothe severity code and the success/failure indication returned by the library functiongiving rise to the error.

The two text arguments may be used directly for reporting errors to the user. The firstargument, text1, is always provided and contains a generic description of the errorcondition. The second argument, text2, provides supplementary information suchas the name of a file which could not be opened. If no supplementary information isavailable, text2 contains the value NULL.

Severity codes are listed in Table 3.

The default handler forces exit in response to severe errors and ignores others.


3.5 DAB Packet Data Group transport configuration

The output from server applications built with the library is a series of DAB packet datagroups which must subsequently be packaged for transmission in a DAB packet dataservice. Conversely a received packet data service must be presented as a series of DABpacket data groups for input to client applications.

In any given implementation, some means must be provided to “connect” the data groupstream produced by the server’s spooler to the DAB transmission system. Similarly, theclient must be able to receive packet data groups streams. DAB data group access functionsare system specific. Furthermore, the interaction between the client library functions andthe lower level I/O functions is implementation dependent. For example—

• In most server implementations, the spooler is a separate task from the main serverapplication, so it will not be practical for the application to configure the spooler byproviding a pointer to a suitable data group output function via the server interface.

• In client applications with carousel managers, data group message input will behandled by a separate task. Again it will not be practical to configure data inputsimply by passing a function pointer through the client interface.

• Some operating systems may provide a “read with time-out” function. In others, somekind of status polling may be necessary.

Instead, transport layer configuration is performed at compile time by linking suitable datagroup I/O functions when the server spooler or the client application is built.

Porting the library to different operating environments is thus a two stage process—

1. The first stage is to implement the library for a particular operating systemenvironment (for example, UNIX, WinNT, VxWorks or whatever, with or withoutcarousel manager on client side). This will generally involve re-writing the librarycode to accommodate the particular features of the operating system concerned (fileI/O, inter task communications etc) and to implement whatever caching strategies areconsidered appropriate. Part of the implementation process is to ensure that allmessage I/O is channelled through a small number of functions, whose definition isconsidered part of the implementation.

2. For any given implementation, the second stage is to implement the defined set ofDAB data group message I/O functions to match the transport facilities provided (forexample TCP/IP socket interface in a UNIX implementation, or some kind of directhardware access in an embedded receiver design).

Typically, the first stage is a fairly substantial exercise, possibly involving a complete re-write. The second stage will be fairly quick in any given environment. For example in aUnix implementation, we anticipate that the server side transport interface (used by thespooler) would be defined by just three functions—


DABHANDLE ServerOpenDAB(char *command);

ServerSendDAB(DABHANDLE channel, BYTE *group);

INT ServerCloseDAB(DABHANDLE channel);

The command argument to ServerOpenDAB is derived from that provided toMCSRVStartSpooler(). A possible interface for the client side would be—

DABHANDLE ClientOpenDAB(char *command);

INT ClientGetDAB(DABHANDLE channel, BYTE *msgbuf, INT buflen, INT timeout);

ClientCloseDAB(DSMCCHANDLE channel);

The command argument to ClientOpenDAB would perhaps be derived from the pathargument to DCCLLIOpenCarousel. Many implementations will restrict operation to asingle DAB channel at any one time, in which case the DABHANDLE channel identifierscan be dispensed with.

These transport layer interfaces are not part of the library definition and are illustrativeonly.


4. Server library

The server library provides support for applications which need to build and manage datacarousels. It allows an application to—

• Create, open and close data carousels.

• Insert delete and modify modules.

• Define module properties (descriptions and transmission frequency).

• Control the spooler associated with the carousel.

The concept of “opening” and “closing” the carousel is introduced so that—

• A server application can access more than one data carousel.

• A carousel can be locked against concurrent changes by more than one application ina multi-tasking environment.

4.1 Module Identification

The server library encapsulates and hides the concept of the module identifiers as follows—

• When a module is created, an unused module identifier is allocated.

• When a module is deleted, its module identifier is made available for re-use.

• When a module is replaced, its module identifier is reused by the replacement.

• Re-use of module identifiers is delayed as long as possible to minimise the possibilityof a receiver failing to notice a change

4.2 Version Control

MOT provides for a version number to be associated with each module. These versionnumbers are encoded as parameters associated with each module. As such they areessentially descriptive information to be interpreted by the applications built on top of thedata carousel. The primary method of change detection is the unique transportIdidentifying each module.

The library arranges that—

• If a module is unchanged in successive versions of a carousel, then itstransportId will be unchanged.

• If a module is changed in any way (content or description) a new transportId isallocated.

• If the same transportId is used in two successive versions of a carousel, then theassociated module is identical.


• The library allocates new transportIds on a cyclical basis so as to minimise thepossibility of a receiver not noticing that a module has changed.

The encoding of MOT version number parameters is optional and controlled by theMCSRVVersions function. The server library encodes version and transportIdinformation as follows—

• When a module is first created, it is allocated version number 1 and a newtransportId.

• If an existing module is replaced, it is marked as changed.

• When a set of changes are finalised and incorporated into an updated carousel, theversion numbers of changed modules are incremented and new transportIds areallocated. Unchanged modules retain their previous version numbers andtransportIds.

4.2.1 Carousel Capacity

Modules in MOT carousels are identified by a 16-bit transportId so, in principle, thecarousel can contain 65,536 modules. However, because the library arranges thattransportIds are not re-used for different modules in successive versions of a carousel,the actual capacity of a carousel may be less than the theoretical maximum. The extent ofthe reduction will depend on the carousel’s change history.

In extreme circumstances, it may become necessary for server applications to change and“freeze” the carousel in stages to release transportIds for re-use. In such cases, areasonable time should elapse between successive carousel versions in order to givereceivers the best chance of detecting the change.2,3

4.3 Spooler Interaction

The server library provides functions for starting, stopping and notifying updates to thespooler. In most implementations, the spooler will be a separate task which will be leftrunning even if the application server is not. The normal way to manage spooler executionwill be to construct simple start_spooler and stop_spooler applications, whichcall the corresponding spooler control functions. This ensures that the operational status ofthe spooler is communicated correctly to other server applications.

2 I.e. to give receivers an opportunity to detect that the MOT directory object has been updated before re-usedtransportIds appear in the carousel.

3 Receivers based on the original MOT protocol (prior to the introduction of the MOT directory object) maynot be able to deal well with this situation.


4.4 Module Descriptors

Module descriptors can be defined by using MCSRVDescribeModule. These descriptorsprovide the basic mechanisms by which applications identify modules.

4.5 Server Interface Summary

The server library interface is defined by the following functions—

Data carousel control:

• MCSRVCarouselInfo

• MCSRVCloseCarousel

• MCSRVControlFrequency

• MCSRVCRC

• MCSRVCreateCarousel

• MCSRVDataRate

• MCSRVDeleteCarousel

• MCSRVHeaders

• MCSRVNextCarouselInfo

• MCSRVOpenCarousel

• MCSRVRestartCarouselInfo

• MCSRVSegSize

• MCSRVSyncCarousel

• MCSRVVersions

Module management:

• MCSRVCreateModule

• MCSRVDeleteModule

• MCSRVDescribeCarousel

• MCSRVDescribeModule

• MCSRVFirstModule

• MCSRVLocateModule

• MCSRVMatchModule

• MCSRVModuleFrequency


• MCSRVModuleInfo

• MCSRVModuleSize

• MCSRVNextModule

• MCSRVNextModuleInfo

• MCSRVRestartModuleInfo

• MCSRVUpdateModule

Spooler control:

• MCSRVSpoolerStatus

• MCSRVStartSpooler

• MCSRVStopSpooler

• MCSRVUpdateSpooler

Playout accounting and statistics

• MCSRVModuleAccount

• MCSRVSpoolerStatistics

Error reporting and debugging information:

• MCSRVErrorHandler

These are described on the following pages.


MCSRVCarouselInfo

Definition:

INT MCSRVCarouselInfo(carousel, tag, desc, buflen)

Arguments:

CHANDLE carousel Carousel reference.

INT tag Descriptor tag.

BYTE * desc Description buffer.

INT buflen Length of desc.

Returns:

INT >0 Success, length of descriptive information

<0 Success, no information defined for tag.

0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page ??.

On successful completion, the return value is the length of the description associatedwith tag. The result is truncated if necessary to fit within the desc argument whoselength is specified in buflen. Note that descriptive information returned by thisfunction does not include a string terminator.

The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is thenumber of bytes available, but no data is written.


MCSRVCloseCarousel

Definition:

INT MCSRVCloseCarousel(carousel)

Arguments:

CHANDLE carousel Reference to a carousel

Returns:

INT non-zero Success

zero Failure

Description:

This function closes a carousel identified by the carousel handle argument.Once closed, a carousel can not be accessed (except by the spooler) without firstbeing re-opened.

Applications should always explicitly close a carousel to ensure that updates areproperly reflected in permanent storage.

On successful completion, the function returns a non-zero value.


MCSRVControlFrequency

Definition:

INT MCSRVControlFrequency(carousel, frequency)

Arguments:


INT frequency Control frequency

Returns:

INT non-zero New control frequency

zero Failure

Description:

Normally, the control information in a data carousel is transmitted once perrotation. Responsiveness in some applications can be improved if the controlinformation is transmitted more often. This function can be used to change thecontrol transmission frequency of an open carousel. The frequency argumentmust be greater than zero to effect a change. A zero frequency argument can beused to query the current setting.

On successful completion, the function returns the new control frequency. A zeroreturn indicates failure.


MCSRVCRC

Definition:

INT MCSRVCRC(carousel, crcs)

Arguments:


INT crcs CRC parameter

Returns:

INT CRC control setting

Description:

This function controls whether CRCs are included in the DAB data groups of theencoded carousel. By default carousels are created with CRCs enabled.

The crcs argument is interpreted as follows—

>0 – Enable CRC generation

<0 – Disable CRC generation

0 – Query the current setting without making changes

The function return value indicates the new setting as follows—

1 – CRC generation enabled

0 – CRC generation disabled

Since a receiver can choose to ignore the CRCs, probably the only reason to disableCRC generation would be to improve the performance of the spooler.


MCSRVCreateCarousel

Definition:

CHANDLE MCSRVCreateCarousel(path, crc, dlest)

Arguments:

CHAR * path Path to data carousel store.

INT crc Enable module CRCs.

INT dlest Enable download time estimates

Returns:

CHANDLE non-NULL Success

NULL Failure

Description:

This function creates and initialises a new (empty) data carousel identified by thestring path. The precise interpretation of path is system dependent. In UNIXimplementations, path is the name of a directory where the internal representationof the carousel will be stored. In other implementations, the interpretation may bedifferent. For example path may be simply an identifying name for the carousel,with the precise storage location determined by system configuration.

The main requirement is that path is interpreted consistently between thisfunction, MCSRVDeleteCarousel and MCSRVOpenCarousel.

The crc and dlest arguments enable optional features of the carousel—

• If crc is non-zero, then 32 bit CRCs will be included in the descriptiveinformation transmitted with each module. This is a DSM-CC facility whichis probably superfluous because the DAB environment applies its own CRCchecks.

• If dlest is non-zero, then download time estimates will be included in thedescriptive information transmitted with each module.


These options should not be enabled if they are not required, because each reducesthe amount of space available for module descriptions (seeMCSRVDescribeModule).

After creating the data carousel, MCSRVOpenCarousel is implicitly called withthe same path argument and a handle to reference the carousel is returned.


MCSRVCreateModule

Definition:

MHANDLE MCSRVCreateModule(carousel, modpath)

Arguments:


CHAR * modpath path to a file containing module contents

Returns:

MHANDLE non-NULL Success

NULL Failure

Description:

This function creates a new module in the carousel. The module contents aretaken from the file specified by modpath. The function returns a handle which canbe used to reference the newly created module.

If modpath is NULL an empty module is created. Empty modules can carrydescriptive information even though they have no data content4.

A NULL handle is returned if the function fails.

Note that, although modules are created from files, this does not necessarily requirethat there is a one-to-one correspondence between application files and datacarousel modules. For example, an application might package several files in onemodule or it might split a file across many modules. In such cases, the applicationserver would construct temporary intermediate files in order to use this function.

4 An empty module is represented in a DAB data carousel by descriptors in DownloadInfoIndicationmessages. It has zero length and there are no corresponding DownloadDataBlock messages.


MCSRVDataRate

Definition:

INT MCSRVDataRate(carousel, rate)

Arguments:


INT rate Data rate in kBit/s

Returns:

INT non-zero New data rate

zero Failure

Description:

This function defines the average data transmission rate for the carousel. This isused by the carousel generator to define various time-out fields which aretransmitted in the carousel’s control messages.

This function does not actually change the transmitted data rate. It affects only thecontrol information which is transmitted after the next spooler update.

A value of zero for rate can be used to query the current setting without changingit.

Newly created carousels have a valid but undefined data rate.

On successful completion, the function returns the new data rate. A zero returnindicates failure.


MCSRVDeleteCarousel

Definition:

INT MCSRVDeleteCarousel(path)

Arguments:


Returns:


zero Failure

Description:

This function deletes the carousel referenced by path.

The precise interpretation of path is system dependent. In UNIX implementations,path is the name of a directory where the internal representation of the carouselwill be stored. In other implementations, the interpretation may be different. Forexample path may be simply an identifying name for the carousel, with the precisestorage location determined by system configuration.

The main requirement is that path is interpreted consistently between thisfunction, MCSRVCreateCarousel and MCSRVOpenCarousel.

A carousel can not be deleted while it is open (either by the caller or by another taskin a multi-processing system) or while its spooler is running.



MCSRVDeleteModule

Definition:

INT MCSRVDeleteModule(module)

Arguments:

MHANDLE module Module reference

Returns:


zero Failure

Description:

This deletes a module from the carousel containing it. Once a module has beendeleted, its handle is no longer valid.

If a module is a member of a group, then the group contents are adjusted toaccommodate the deletion. Deleting a module may leave an empty group, which isnot deleted.

The function returns a non-zero value on success and zero on failure.


MCSRVDescribeCarousel

Definition:

INT MCSRVDescribeCarousel(carousel, tag, desc,length)

Arguments:

CHANDLE carousel Carousel reference

INT tag Descriptor tag

BYTE * desc Descriptive information

INT length Length in bytes of descriptive information

Returns:


zero Failure

Description:

This function adds descriptive information provided as an array of bytes in desc tothe specified carousel. The length of the descriptive information in desc isspecified by length. For text descriptions, string terminator characters (such asthe NULL termination character in C) should not be included in length. Thedescriptive information is transmitted as an MOT parameter whose identifier isgiven by the tag value.

The maximum permissible length for a MOT parameter data field (given by desc)is 32767 bytes. The tag argument should take one of the values defined in [1]. Thefunction will report an error if tag is less than 0 or greater than 0x3f. Notehowever that [1] imposes additional restrictions which are not detected.

Applications should avoid using tag 0x06 if automatic MOT version numbering(see MCSRVVersions) is to be used, since this may cause duplicated orconflicting MOT version number parameters to be included in the carousel.


MCSRVDescribeModule

Definition:

INT MCSRVDescribeModule(module, tag, desc, length)

Arguments:


INT tag Descriptor tag

BYTE * desc Descriptive information

INT length Length in bytes of descriptive information

Returns:


zero Failure

Description:

This function adds descriptive information provided as an array of bytes in desc tothe specified module. The length of the descriptive information in desc isspecified by length. For text descriptions, string terminator characters (such asthe NULL termination character in C) should not be included in length. Thedescriptive information is transmitted as an MOT parameter whose identifier isgiven by the tag value.

The maximum permissible length for a MOT parameter data field (given by desc)is 32767 bytes. The tag argument should take one of the values defined in [1]. Thefunction will report an error if tag is less than 0 or greater than 0x3f. Notehowever that [1] imposes additional restrictions which are not detected.

Applications should avoid using tag 0x06 if automatic MOT version numbering(see MCSRVVersions) is to be used, since this may cause duplicated orconflicting MOT version number parameters to be included in the carousel.


MCSRVErrorHandler

Definition:

EHANDLER MCSRVErrorHandler(handler)

Arguments:

EHANDLER handler Error handling function.

Returns:

EHANDLER non-NULL Previous error handler.

NULL Failure

Description:

This function allows a server application to replace the current error handler. Thereturn value contains a pointer to the old handler so it can be re-established later ifrequired.

If an application does not establish its own error handler, the library supplies a defaulthandler, which does nothing.


MCSRVFirstModule

Definition:

MHANDLE MCSRVFirstModule(carousel)

Arguments:


Returns:

MHANDLE non-NULL Module handle

NULL Failure

Description:

This function returns a handle to the first module in the specified carousel.

The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to this function followed by successive calls to MCSRVNextModulewill eventually iterate through all the modules in the carousel.

During iterative processing of carousel modules, applications must take care to—

• Not create new modules. It is unpredictable whether the new module will beinserted before or after the current iteration location.

• Not delete the current module until after using its handle to locate the nextone in sequence.

A NULL handle is returned if the function fails or if the carousel is empty.


MCSRVHeaders

Definition:

INT MCSRVHeaders(carousel, headers)

Arguments:


INT headers MOT header control

Returns:

INT header control setting

Description:

This function controls whether MOT headers are included in the carousel5. Bydefault carousels are created with MOT header encoding disabled.

The headers argument is interpreted as follows—

>0 – Enable MOT header encoding

<0 – Disable MOT header encoding



1 – MOT header encoding enabled

0 – MOT header encoding disabled

5 MOT headers are not essential to decode a data carousel and they are not required by the client librarydecoder. However, they may be required by older decoders which pre-date the introduction of the MOTDirectory object.


MCSRVLocateModule

Definition:

MHANDLE MCSRVLocateModule(carousel, tag, desc, length)

Arguments:


INT tag Descriptor tag value

BYTE * desc Match data

INT length Length of desc

Returns:

MHANDLE non-NULL Module handle.

NULL Failure

Description:

This function locates an existing module in the carousel with a descriptor oftype tag and content desc. The tag argument should be one of the descriptortypes listed under MCSRVDescribeModule on 37. Only exact matches arereturned. This function does not provide any pattern matching or wildcardprocessing facilities.

If no matching module is found, the function fails. If more than one modulematches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.

It is up to the application to ensure that module descriptors are managed in such away as to provide unique access if such functionality is required.



MCSRVMatchModule

Definition:

MHANDLE MCSRVMatchModule(carousel, dcount, tag, desc, length)

Arguments:


INT dcount Descriptor count

INT * tag Descriptor tag values

BYTE ** desc Descriptor data arrays

INT * length Lengths of descriptor data arrays

Returns:


NULL Failure

Description:

This function is similar to MCSRVLocateModule, except that the tag, descand length arguments are all arrays. Corresponding elements in these arraysdefine a descriptor, with the total number of descriptors being specified by thedcount argument6. The function returns a handle for a module with matchingdescriptors for every item in the descriptor set. For example, this function could beused to locate a module with a particular name and type. Only exact matches arereturned. There are no pattern matching or wildcard processing facilities.

If no matching module is found, the function fails. If more than one module

6 We use this interface rather than a single array or linked list of structs to ease the problems associatedwith using the library from languages other than C.


matches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.




MCSRVModuleAccount

Definition:

INT MCSRVModuleAccount(module, account)

Arguments:

MHANDLE module Reference to a module

INT account Account code

Returns:

INT non-zero New module account

zero Failure

Description:

Each module in a carousel can be assigned an account code for service monitoringpurposes, The MCSRVSpoolerStatistics function can then be used to reportthe total number of bytes transmitted for each account code.

This function associates an account code with a module. An account code is a smallinteger in the range 1…MCSRV_MAX_ACCOUNT7. By default, modules areassigned to account code 1 when they are first created. If a module is updated (withMCSRVUpdateModule) it retains its previous account code unless it is explicitlyaltered by calling this function.

A zero account argument can be used to query the current setting without makingany changes.

On successful completion, the function returns the new account code. A zero returnindicates failure (for example an out-of-range account).

7 15 in the current implementation, although this can be changed by recompiling the library.


MCSRVModuleFrequency

Definition:

INT MCSRVModuleFrequency(module, frequency)

Arguments:

MHANDLE module Reference to a module

INT frequency Module frequency

Returns:

INT non-zero New module frequency

zero Failure

Description:

Normally, each module in a data carousel is transmitted once per rotation.Responsiveness in some applications can be improved if some modules aretransmitted more often. This function can be used to change the transmissionfrequency of a module. The frequency argument must be greater than zero toeffect a change. A zero frequency argument can be used to query the currentsetting.

On successful completion, the function returns the new frequency. A zero returnindicates failure.


MCSRVModuleInfo

Definition:

INT MCSRVModuleInfo(module, tag, frequency, desc, buflen)

Arguments:

MHANDLE module Module reference.


INT * frequency Module transmission frequency.



Returns:



0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37.


The function return value is normally the number of bytes written to desc (allowingfor any truncation) unless desc is NULL, in which case the return value is the


number of bytes available, but no data is written.

Regardless of the values in tag and desc, the module transmission frequency (intransmissions per carousel turn) is always returned in the frequency argument.


MCSRVModuleSize

Definition:

LONG MCSRVModuleSize(module)

Arguments:


Returns:

LONG >= 0 Success, size of module in bytes

<0 Failure.

Description:

This function returns the size (in bytes) of the specified module. Modules may havezero size.


MCSRVNextModule

Definition:

MHANDLE MCSRVNextModule(module)

Arguments:

MHANDLE module Current module reference

Returns:


NULL Failure

Description:

This function returns a handle to module’s successor in the carousel whichcontains it.

The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to MCSRVFirstModule followed by successive calls toMCSRVNextModule will eventually iterate through all the modules in thecarousel.

During iterative processing of carousel modules, applications must take care to—

• Not create new modules. It is unpredictable whether the new module will beinserted before or after the current iteration location.

• Not delete the current module until after using its handle to locate the nextone in sequence.

A NULL handle is returned if the function fails or if there are no more modules inthe carousel.


MCSRVNextCarouselInfo

Definition:

INT MCSRVNextCarouselInfo(carousel, tag, desc,buflen)

Arguments:





Returns:



0 Failure

Description:

This function retrieves descriptive information about a carousel. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page??. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.

On successful completion, the return value is the length of the next descriptionassociated with tag. The result is truncated if necessary to fit within the descargument whose length is specified in buflen. Note that descriptive informationreturned by this function does not include a string terminator.



MCSRVNextModuleInfo

Definition:

INT MCSRVNextModuleInfo(module, tag, frequency, desc, buflen)

Arguments:






Returns:



0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.



MCSRVOpenCarousel

Definition:

CHANDLE MCSRVOpenCarousel(path)

Arguments:


Returns:

CHANDLE non-NULL Carousel handle

NULL Failure

Description:

This function opens an existing data carousel for modifications. The carousel isidentified by the string path. The precise interpretation of path is systemdependent. In UNIX implementations, path is the name of a directory where theinternal representation of the carousel will be stored. In other implementations, theinterpretation may be different. For example path may be simply an identifyingname for the carousel, with the precise storage location determined by systemconfiguration.

The main requirement is that path is interpreted consistently between thisfunction, MCSRVDeleteCarousel and MCSRVCreateCarousel.

In a multi-processing environment, only one process may open a carousel formodifications at a time.

On successful completion, the function returns a handle to reference the carousel.


MCSRVRestartCarouselInfo

Definition:

VOID MCSRVRestartCarouselInfo(carousel)

Arguments:

CHANDLE carousel Carousel handle

Returns:

Description:

This function resets the internal pointer for iterating through carousel descriptorswith calls to MCSRVNextCarouselInfo.


MCSRVRestartModuleInfo

Definition:

VOID MCSRVRestartModuleInfo(module)

Arguments:

MHANDLE module Module handle

Returns:

Description:

This function resets the internal pointer for iterating through module descriptorswith calls to MCSRVNextModuleInfo.


MCSRVSegSize

Definition:

INT MCSRVSegSize(carousel, segsize)

Arguments:


INT segsize Segmentation size

Returns:

INT non-zero New segmentation size

zero Failure

Description:

This function sets the MOT segmentation size for the carousel. The segsizeargument must be in the range 1 to 8191. The default value for a new carousel is8191. A zero segsize argument simply returns the current segmentation sizewithout making any changes.

Although the MOT protocol allows different modules to have different segmentsizes8, the server library encodes all modules with the same segment size. Normallythe default is adequate.

On successful completion, the function returns the new segmentation size. A zeroreturn indicates failure.

8 And the client library can recognise and decode modules with different segment sizes.


MCSRVSpoolerStatistics

Definition:

INT MCSRVSpoolerStatistics(carousel, stats, reset)

Arguments:


ULONG * stats Statistics array

INT reset Statistics reset flag

Returns:

INT 1 Success

0 Error

Description:

This provides the current spooler accounting statistics for the specified carousel.It returns meaningful values only when the spooler is running. If the spooler is notrunning, an error is signalled.

9 Account codes are values in the range 1…DCSRV_MAX_ACCOUNT. The array must contain at least(MCSRV_MAX_ACCOUNT + 1) elements


The stats argument should be a pointer to an array of ULONGs to receive thecurrent counters. On completion of the function, this array will contain the number ofbytes transmitted since the spooler was started or the counters were last reset (seebelow). The array is indexed by account code9.

Element zero of the stats array will receive the counter for bytes not associatedwith any particular code. In practice, this means the carousel directory information10.

If the reset argument is non-zero, then all the counters will be zeroed once theirvalues have been copied to the function arguments.

10 Directory object data groups in the case of an MOT carousel.


MCSRVSpoolerStatus

Definition:

INT MCSRVSpoolerStatus(carousel, info, infolen)

Arguments:


CHAR * info Text buffer

INT infolen Length of text buffer

Returns:

INT 0 Error

1 Spooler stopped (stopped on request)

2 Spooler running

3 Spooler abort (spooler encountered an error)

Description:

This function provides the current operating status of the spooler.

The info argument allows the return of a text string with implementation dependentextra information from the spooler (possibly the command line with which thespooler was invoked). This information is truncated if necessary to fit within thebuffer length indicated by infolen (including a string terminator).

A NULL info argument can be provided. In this case infolen should be zero.


MCSRVStartSpooler

Definition:

INT MCSRVStartSpooler(carousel, command)

Arguments:


CHAR * command Spooler command string

Returns:


zero Failure

Description:

This function starts the spooler associated with the specified carousel. The spoolerwill use the most recent “frozen” state of the carousel. The function fails if thespooler is already running. Applications should call MCSRVSpoolerStatus to testthis possibility before attempting to start the spooler.

The command argument is a text string containing control information for thespooler. It’s significance will depend on the implementation. For example, it could beused to specify destination network and port addresses for the spooler.

If there is no command data, a NULL argument may be provided.


MCSRVStopSpooler

Definition:

INT MCSRVStopSpooler(carousel)

Arguments:


Returns:


zero Failure

Description:

This function stops the spooler associated with the specified carousel.

Note that attempting to stop a spooler that is not running is considered an error.Applications may wish to test for this possibility with MCSRVSpoolerStatus.


MCSRVSyncCarousel

Definition:

INT MCSRVSyncCarousel(carousel)

Arguments:


Returns:


0 Failure

Description:

The server library maintains its description of the current state of the carousel inmemory. This description is written to disk when the carousel is closed. If aprogram using the server library fails without closing the carousel properly, thecarousel description on disk may be left in an inconsistent state.

To help protect against this possibility, programs can call MCSRVSyncCarouselto bring the on-disk description up to date with respect to the memory residentdescription.

Whether to call this function and, if so how often, is a design decision depending onthe nature of the particular application program. Simple batch processes may notneed to use this function at all. Interactive carousel editor programs may wish tosynchronise after every successful update.


MCSRVUpdateModule

Definition:

MHANDLE MCSRVUpdateModule(module, modpath)

Arguments:


CHAR * modpath Path to a file containing new module contents

Returns:


NULL Failure

Description:

This function replaces the contents of a module. The new module contents aretaken from the file specified by modpath. The function returns a handle which canbe used to reference the updated module. (Unless there is an error, this will be thesame as the module argument provided to the function).



MCSRVUpdateSpooler

Definition:

INT MCSRVUpdateSpooler(carousel, when)

Arguments:


INT when Update timing code

Returns:


zero Failure

Description:

This function validates the data carousel by attempting to generate a new “frozen”configuration. If this is successful, the spooler is instructed to use the newconfiguration. The changeover to the new configuration occurs at one of a messageboundary, module boundary or carousel turn boundary depending on the code in thewhen argument.

If the spooler is not running, the new frozen configuration will replace the old, but thespooler will not be started.

The when argument is coded as follows—

0 No replacement

1 Next message boundary

2 Next module boundary

3 Next carousel turn boundary

The “no replacement” option is provided to allow carousel configurations to be tested


without influencing the spooler. If this option is selected, the new frozen carousel isgenerated and verified, but then discarded. The old carousel is not replaced.

If the function call fails in any way, the old carousel is not replaced.


MCSRVVersions

Definition:

INT MCSRVVersions(carousel, versions)

Arguments:


INT versions MOT version parameter

Returns:

INT version control setting

Description:

This function controls whether MOT version number parameters are automaticallyincluded in the carousel11. By default carousels are created with MOT versionnumber parameters disabled.

The versions argument is interpreted as follows—

>0 – Enable MOT version number parameter encoding

<0 – Disable MOT version number parameter encoding



1 – MOT version number parameter encoding enabled

0 – MOT version number parameter encoding disabled

11 MOT version parameters are not needed to decode a data carousel. The client library does not use versionnumbers to detect changes. However, version numbers may be significant to some carousel applications.


5. Client library

The client library interface provides access to modules and their descriptions, whileencapsulating and hiding the details of their encoding in DAB Packet data groups.

The caching strategy is also hidden. Different library implementations may or may notprovide a carousel manager and caches of control and module data. However, this is hiddenfrom the application, which uses the same interface in all cases. Cache “hints” to optimiseperformance are specified in terms of the application’s anticipated access to the modules,not in terms of the internal caching mechanisms. Depending on the implementation, thesehints may or may not actually affect performance.

The library is intended for implementation within some suitable multi-tasking softwareenvironment. The interface does not provide any scheduling functionality12. The interfacefunctions simply block the calling task until they either complete or time out.

5.1 Access to Modules and Data

The client library provides functions such as MCCLILocateModule to navigate throughthe carousel structure and return handles by which the modules can be referenced.Descriptive information associated with modules may be accessed via these handleswithout restriction. However, before a module’s data can be accessed (usingMCCLIReadModule or MCCLIPositionModule), the module must first be openedwith MCCLIOpenModule. Once access to a module’s data is no longer required, it shouldbe closed with MCCLICloseModule. Most implementations will impose a limit on thenumber of modules which may be opened simultaneously. Applications should closemodules after use to conserve resources.

5.2 Changing Data

The data carousel model implies repeated broadcasts of a fairly static data set. However,from time to time, the data will change. If such changes occur while a client application isactive, remedial action will almost certainly be necessary.

If the library detects that a data carousel has changed, all subsequent client library callsexcept MCCLICloseCarousel will fail and signal an error with severity code 2 usingthe mechanism described in Section 3.4. The application must close and re-open thecarousel to recover from this situation.

12 For example, we do not adopt a style in which a function returns immediately and some time later raises asignal or calls a completion function.


Closing the carousel implicitly closes any open modules and invalidates all module andgroup handles.

5.3 Cache Hints

We anticipate that some client library implementations will retain data in internal caches toimprove performance. MCCLIOpenModule and MCCLICloseModule take accesspattern arguments to indicate anticipated future use of the module. Client libraries may beable to exploit this data to influence caching strategy and improve performance.

An access pattern argument of 0 indicates no information. For MCCLIOpenModule,this indicates the default of single sequential access. For MCCLICloseModule, the valueprovided on the previous MCCLIOpenModule call is used

Non-zero access pattern arguments are coded as 1 plus one or more of the following—

These access codes do not affect the functionality of the library in any way. Onlyperformance might be affected. Client applications may access module data in any orderregardless of anything they might have suggested though access arguments. However, insome implementations, performance may be improved if anticipated and actual accesspatterns agree. Performance may also be degraded if anticipated and actual access patternsdisagree.

In many cases, clients will simply specify access codes of zero and leave the library toimplement its default caching strategies.

5.4 Time-outs

The programming model presented to the client is that of a set of essentially static moduleswhich can be accessed through the interface functions. In reality of course, module data isonly briefly accessible as the broadcast carousel “turns”. Consequently, there may be a

Module Access Codes

Code Meaning Interpretation

2 Random access. Overrides the default assumption that module data willbe accessed sequentially and that once a block has beenread it is unlikely to be re-read without first closing andre-opening the module.

4 Repeated access. Overrides the default assumption that a module will notbe required again for some time after closure.

Table 4 Module access codes


significant delay when accessing data. This delay may be exacerbated in poor transmissionconditions where errors could cause data blocks to be missed and require that the clientwait for the next turn of the carousel. In severe conditions, this process might continueindefinitely.

To address this problem, client functions may time-out, which they indicate by failing andsignalling an error with severity code 3 using the mechanism described in Section 3.4. Thedata carousel itself contains information indicating reasonable time-out periods (whichdepend on the total size of the carousel and the transmission data rate). The client libraryderives its default time-out behaviour from this information.

If a particular implementation supports time-outs, the defaults time-outs are established soas to be as short as practical while ensuring that, in good transmission conditions, time-outerrors rarely occur. Client applications may vary time-out values relative to the defaults byusing MCCLITimeout().


5.5 Client Interface Summary

The client library interface is defined by the following functions—

Data carousel access:

• MCCLICarouselInfo

• MCCLICloseCarousel

• MCCLINextCarouselInfo

• MCCLIOpenCarousel

• MCCLIRestartCarouselInfo

• MCCLITimeout

Carousel Debugging Statistics:

• MCCLIStats

• MCCLIZeroStats

Module access:

• MCCLICloseModule

• MCCLIFirstModule

• MCCLILocateModule

• MCCLIMatchModule

• MCCLIModuleInfo

• MCCLIModuleSize

• MCCLINextModule

• MCCLINextModuleInfo

• MCCLIOpenModule

• MCCLIPositionModule

• MCCLIReadModule

• MCCLIRestartModuleInfo

Error reporting and debugging information:

• MCCLIErrorHandler

These are described on the following pages.


MCCLICarouselInfo

Definition:

INT MCCLICarouselInfo(carousel, tag, desc, buflen)

Arguments:





Returns:



0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which takes the same set of values as defined forMCSRVDescribeCarousel on Page ??.




MCCLICloseCarousel

Definition:

INT MCCLICloseCarousel(carousel)

Arguments:


Returns:


zero Failure

Description:

This function closes a carousel identified by the carousel handle argument.Once closed, a carousel can not be accessed without first being re-opened.

Closing a carousel releases any resources associated with its management.



MCCLICloseModule

Definition:

MHANDLE MCCLICloseModule(module, access)

Arguments:


INT access Access pattern code

Returns:

MHANDLE non-NULL New module handle

NULL Failure

Description:

This function closes a module identified by the module handle argument. Onceclosed, a module’s data can not be accessed without first re-opening the module.However, descriptive information about the module can still be retrieved using thehandle returned by the function.

The access argument takes one of the values listed in Section 5.3.

Module handles change when modules are opened or closed. After closing amodule, only the handle value returned by this function should be used for futurereferences. The following example is typical in C—

MHANDLE mh; … if ((mh = MCCLICloseModule(mh, 0)) == NULL) { /* error recovery */ } else { /* carry on using mh to refer to (closed) module */ }


MCCLIErrorHandler

Definition:

EHANDLER MCCLIErrorHandler(handler)

Arguments:

EHANDLER handler Error handling function.

Returns:

EHANDLER Previous error handler

Description:

This function allows a client application to replace the current error handler. Thereturn value contains a pointer to the old handler so it can be re-established later ifrequired.

If an application does not establish its own error handler, the library supplies a defaulthandler, which does nothing.


MCCLIFirstModule

Definition:

MHANDLE MCCLIFirstModule(carousel)

Arguments:


Returns:


NULL Failure

Description:

This function returns a handle to the first module in the specified carousel.

The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to this function followed by successive calls to MCCLINextModulewill eventually iterate through all the modules in the carousel.

A NULL handle is returned if the function fails or if the carousel is empty.


MCCLILocateModule

Definition:

MHANDLE MCCLILocateModule(carousel, tag, desc, length)

Arguments:


INT tag Descriptor tag value

BYTE * desc Match data

INT length Length of desc

Returns:


NULL Failure

Description:

This function locates an existing module in the carousel with a descriptor oftype tag and content desc. The tag argument should be one of the descriptortypes listed under MCSRVDescribeModule on Page 37. Only exact matches arereturned. This function does not provide any pattern matching or wildcardprocessing facilities.

If no matching module is found, the function fails. If more than one modulematches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.

It is up to the server application to ensure that module descriptors are managed insuch a way as to provide unique access for the client if such functionality isrequired.



MCCLIMatchModule

Definition:

MHANDLE MCCLIMatchModule(carousel, dcount, tag, desc, length)

Arguments:


INT dcount Descriptor count

INT * tag Descriptor tag values

BYTE ** desc Descriptor data arrays

INT * length Lengths of descriptor data arrays

Returns:


NULL Failure

Description:

This function is similar to MCCLILocateModule, except that the tag, descand length arguments are all arrays. Corresponding elements in these arraysdefine a descriptor, with the total number of descriptors being specified by thedcount argument13. The function returns a handle for a module with matchingdescriptors for every item in the descriptor set. For example, this function could beused to locate a module with a particular name and type. Only exact matches arereturned. There are no pattern matching or wildcard processing facilities.

If no matching module is found, the function fails. If more than one module

13 We use this interface rather than a single array or linked list of structs to ease the problems associatedwith using the library from languages other than C.


matches the search criterion, a valid handle will be returned, but precisely which ofthe matching modules is referenced is unpredictable.




MCCLIModuleInfo

Definition:

INT MCCLIModuleInfo(module, tag, desc, buflen)

Arguments:





Returns:



0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which takes the same set of values as defined forMCSRVDescribeModule on Page 37.




MCCLIModuleSize

Definition:

LONG MCCLIModuleSize(module)

Arguments:


Returns:

LONG >= 0 Success, size of module in bytes

<0 Failure.

Description:

This function returns the size (in bytes) of the specified module. Modules may havezero size.


MCCLINextModule

Definition:

MHANDLE MCCLINextModule(module)

Arguments:

MHANDLE module Current module reference

Returns:


NULL Failure

Description:

This function returns a handle to module’s successor in the carousel whichcontains it.

The sense in which modules are sequenced is undefined. All that is guaranteed isthat a call to MCCLIFirstModule followed by successive calls toMCCLINextModule will eventually iterate through all the modules in thecarousel.

A NULL handle is returned if the function fails or if there are no more modules inthe carousel.


MCCLINextCarouselInfo

Definition:

INT MCCLINextCarouselInfo(carousel, tag, desc,buflen)

Arguments:





Returns:



0 Failure

Description:

This function retrieves descriptive information about a carousel. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeCarousel on Page??. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.




MCCLINextModuleInfo

Definition:

INT MCCLINextModuleInfo(module, tag, frequency, desc, buflen)

Arguments:






Returns:



0 Failure

Description:

This function retrieves descriptive information about a module. The informationreturned is selected by tag which take the same set of values as defined forMCSRVDescribeModule on Page 37. Where multiple instances of a givendescriptor may be applied to a module, this function allows all instances to beretrieved.



MCCLIOpenCarousel

Definition:

CHANDLE MCCLIOpenCarousel(source, path, timeout)

Arguments:

CHAR * source See description

CHAR * path See description

INT timeout Initial time-out in seconds.

Returns:

CHANDLE non-NULL Carousel handle

NULL Failure

Description:

This function opens a data carousel for access. The carousel is identified by thepath and source arguments. The precise interpretation of path and sourcesystem dependent. Typically, path specifies a directory in which carousel data iscached and source specifies the connection over which carousel messages arereceived. In a PC based implementation, source might specify a networkconnection to a packet dis-assembler task. In an integrated receiver environment,source might specify tuning and service information for the receiver to retrieveDAB packet data, while path might be unused.

Although data carousels include information which allows library functions toapply appropriate time-out values automatically, this information is only availableafter the carousel has been opened. The timeout argument specifies a time-outperiod for the initial carousel opening. If a zero timeout is specified, the functioncontinues indefinitely to try to open the carousel.

On successful completion, the function returns a handle to reference the carousel.


MCCLIOpenModule

Definition:

MHANDLE MCCLIOpenModule(module, access)

Arguments:


INT access Access pattern code

Returns:

MHANDLE non-NULL New module handle

NULL Failure

Description:

This function opens a module identified by the module handle argument. Amodule must be opened before MCCLIReadModule orMCCLIPositionModule can be used.

The access argument takes one of the values listed in Section 5.3.

Module handles change when modules are opened or closed. After opening amodule, the handle value returned by this function should be used for futurereferences. The following example is typical in C—

MHANDLE mh; … if ((mh = MCCLIOpenModule(mh, 0)) == NULL) { /* error recovery */ } else { /* carry on using mh to refer to (open) module */ }


MCCLIPositionModule

Definition:

INT MCCLIPositionModule(module, offset)

Arguments:

MHANDLE module Open module reference.

INT offset Byte offset from start of module.

Returns:

INT >= 0 New position.

< 0 Failure

Description:

This function sets the module read pointer to the specified offset from themodule start. If offset is negative, the function merely reports the currentposition. If offset is greater than the module size, the function fails.

A module must be opened with MCCLIOpenModule before this function can beused.

In some implementations, it may be helpful to set a module position some timebefore reading the data, since this may give the software time to pre-load internalcaches or perform other optimisations.

A module offset is set to zero when it is opened. Subsequently, unless this functionis called, module positions are incremented by successive MCCLIReadModulecalls.


MCCLIReadModule

Definition:

INT MCCLIReadModule(module, buf, size)

Arguments:

MHANDLE module Open module reference

BYTE * buf Buffer to receive module data

INT size Number of bytes to read

Returns:

INT ≥ 0 Number of bytes actually read

< 0 Failure

Description:

This function reads size bytes from module, starting at is current position andreturning the data in buf. The return value will normally be the same as size,unless the end of the module is encountered, in which case the return value is thenumber of bytes actually read (possibly zero if the module is positioned at its endwhen the function is called).

The module read pointer is advanced by the number of bytes actually read.

A module must be opened with MCCLIOpenModule before this function can beused.

A negative return value indicates a failure.


MCCLIStats

Definition:

INT MCCLIStats(carousel, hits, misses)

Arguments:

CHANDLE module Open carousel reference

INT * hits Returns number of cache hits

INT * misses Returns number of cache misses

Returns:


0 Failure

Description:

This function provides statistics about the operation of the cache underlying thespecified carousel. Note that not all implementations necessarily implement acache. Those that do not will return zero for both hits and misses.

A zero return value indicates a failure.


MCCLITimeout

Definition:

INT MCCLITimeout(carousel, scale)

Arguments:


INT scale time-out scale factor percentage

Returns:

INT ≥ 0 New scale factor

< 0 Failure

Description:

This function allows client applications to adjust the time-out values for thecarousel relative to the defaults. The scale parameter specifies a multiplier forthe default time-out values established by the library in response to the controlinformation in the carousel. These defaults are appropriate for good transmissionconditions. Applications may wish to extend the time-out periods to avoid failuresin less reliable conditions. It will rarely be sensible to reduce them relative to thedefaults.

The scale parameter is specified as a percentage. I.e., 100 represents the defaultvalue, 200 doubles all time-out values, 50 halves them. A value of 0 disables time-outs (i.e., library functions wait for ever). Small scale values may not behonoured accurately since the implementation will normally have some minimumgranularity in its time-out processing.

If the implementation does not support time-outs, then this function will returns 0,regardless of the scale value.

A negative return value indicates a failure.


MCCLIZeroStats

Definition:

INT MCCLIZeroStats(carousel)

Arguments:

CHANDLE module Open carousel reference

Returns:


0 Failure

Description:

This function zeroes the statistics associated with the cache underlying the specifiedcarousel. Note that not all implementations necessarily implement a cache. Inthose that do not, this function is ignored.

Note that a cache may be shared by all processes accessing the carousel. If morethan one process zeroes the statistics, the results reported by MCCLIStats mayseem confusing.

A zero return value indicates a failure.


6. References

[1] ETSI. Digital Audio Broadcasting(DAB) Multimedia Object Transfer (MOT)protocol. EN 301 234.

DAB/MOT Data Carousel System Support Library Interface...

Documents

Transcript of DAB/MOT Data Carousel System Support Library Interface...