libenatsc3esg

libentasc3esg implements an ATSC 3.0 ESG processor. It uses an application-provided ROUTE processor configured to operate on an ESG service to receive ESG objects. It is assumed that ESG processing is an activity which occurs alongside other activities such as receiving an audiovisual service. Consequently libenatsc3esg does not attempt to manage reception of the broadcast  below the ROUTE level (i.e. baseband, ALP, lls processing). This is left to the application to manage on behalf of all services which are being received. The application can register callbacks to received service, schedule, and content fragments.

The ESG processor uses the notion of an ESG Set. A new ESG Set is begun when the ESG service’s STSID indicates that the set of SGDDs comprising the ESG has changed. For a particular ESG Set, a particular fragment is only processed (and delivered to the application) the first time it is encountered, even though it may appear in the emission regularly.

Usage

    • Applications obtain an ESG processor via ENATSC3ESGSessionAllocate.
    • Applications use ENATSC3ESGSessionRegisterCallbacks to register callback function to be called when  ESG fragments are received.
    • When the application is done with the processor it is released via ENATSC3ESGSessionFree.

Callback Functions

typedef void (*ENATSC3ESGSessionServiceFragmentCallback)(
    struct timespec *pPacketTimeUTC, 
    int32_t esgSet, 
    uint32_t idOffset,
    int32_t idLength, 
    uint32_t version, 
    uint32_t globalServiceIDOffset,
    int32_t globalServiceIDLength, 
    const char *pXML, 
    int32_t xmlLength,
    void *pUserData
);

ENATSC3ESGSessionServiceFragmentCallback is called by the ESG processor to deliver a service fragment to the application.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the fragment was received. If the fragment spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the fragment.
    • esgSet: The ESG Set to which the fragment belongs.
    • idOffset: The offset into pXML where the fragment id begins.
    • idLength: The length of the id.
    • version: The fragment’s version. 0 if the fragment does not contain a version.
    • globalServiceIDOffset: The offset into pXML where the global service Id begins.
    • globalServiceIDLength: The length of the global service Id.
    • pXML: A pointer to the XML fragment.
    • xmlLength: The length of the XML fragment in bytes.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ESGSessionScheduleFragmentCallback)(
    struct timespec *pPacketTimeUTC, 
    int32_t esgSet, 
    uint32_t idOffset,
    int32_t idLength, 
    uint32_t version, 
    uint32_t serviceIdReference,
    int32_t serviceIdReferenceLength, 
    const char *pXML, 
    int32_t xmlLength,
    void *pUserData
);

ENATSC3ESGSessionScheduleFragmentCallback is called by the ESG processor to deliver a schedule fragment to the application.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the fragment was received. If the fragment spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the fragment.
    • esgSet: The ESG Set to which the fragment belongs.
    • idOffset: The offset into pXML where the fragment id begins.
    • idLength: The length of the id.
    • version: The fragment’s version. 0 if the fragment does not contain a version.
    • serviceIdReference: The offset into pXML where the service reference (value of the idRef attribute on the ServiceReference element) begins.
    • serviceIdReferenceLen: The length of the service reference.
    • pXML: A pointer to the XML fragment.
    • xmlLength: The length of the XML fragment in bytes.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ESGSessionContentFragmentCallback)(
    struct timespec *pPacketTimeUTC, 
    int32_t esgSet, 
    uint32_t idOffset,
    int32_t idLength, 
    uint32_t version, 
    const char *pXML, 
    int32_t xmlLength,
    void *pUserData
);

ENATSC3ESGSessionContentFragmentCallback is called by the ESG processor to deliver a content fragment to the application.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the fragment was received. If the fragment spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the fragment.
    • esgSet: The ESG Set to which the fragment belongs.
    • idOffset: The offset into pXML where the fragment id begins.
    • idLength: The length of the id.
    • version: The fragment’s version. 0 if the fragment does not contain a version.
    • pXML: A pointer to the XML fragment.
    • xmlLength: The length of the XML fragment in bytes.
    • pUserData: Application data provided when the callback was registered.

Function Reference

ENATSC3Status ENATSC3ESGSessionAllocate(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    char *pDebugName, 
    ENATSC3ESGSessionHandle_t *phSession
);

ENATSC3ESGSessionAllocate allocates an ESG processor using the provided ROUTE session to receive data.

Parameters
    • hROUTESession: A handle to a ROUTE session that the ESG processor uses to receive data. The application sets up this ROUTE session to receive data from the ESG service. The ESG processor registers callbacks to receive objects from the ROUTE session.’
    • pDebugName: A string used for debug logging.
    • phSession: On success phSession contains a handle to the ESG processor. Its contents are undefined in the case of failure.
Return Values
    • ENATSC3Status_Success: An ESG processor was instantiated and a handle to the processor is returned in *phSession The processor must be released with ENATSC3ESGSessionFree when the application no longer requires the processor.
    • ENATSC3Status_Failure: An error was encountered while instantiating the processor. The value of *phSession is undefined.
ENATSC3Status ENATSC3ESGSessionFree(
    ENATSC3ESGSessionHandle_t hSession
);

ENATSC3ESGSessionFree releases an ESG processor obtained with ENATSC3ESGSessionAllocate.

Parameters
    • hSession: A handle to the ESG processor to close.
Return Values
    • ENATSC3Status_Success: The processor was closed.
    • ENATSC3Status_Failure: An error was encountered while closing the processor.
ENATSC3Status ENATSC3ESGSessionRegisterCallbacks(
    ENATSC3ESGSessionHandle_t hSession,
    ENATSC3ESGSessionServiceFragmentCallback ServiceFragmentCallback,
    ENATSC3ESGSessionScheduleFragmentCallback ScheduleFragmentCallback,
    ENATSC3ESGSessionContentFragmentCallback ContentFragmentCallback,
    void *pUserData
);

ENATSC3ESGSessionRegisterCallbacks registers functions to be called when fragments are available.

Parameters
    • hSession: A handle to the ESG processor on which to register the callbacks.
    • ServiceFragmentCallback: The function called when service fragments are available.
    • ScheduleFragmentCallback: The function called when schedule fragments are available.
    • ContentFragmentCallback: The function called when content fragments are available.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENATSC3Status_Success: The callbacks were registered.
    • ENATSC3Status_Failure: An error was encountered while registering the callbacks.
ENATSC3Status ENATSC3ESGSessionUnregisterCallbacks(
    ENATSC3ESGSessionHandle_t hSession,
    ENATSC3ESGSessionServiceFragmentCallback ServiceFragmentCallback,
    ENATSC3ESGSessionScheduleFragmentCallback ScheduleFragmentCallback,
    ENATSC3ESGSessionContentFragmentCallback ContentFragmentCallback,
    void *pUserData
);

ENATSC3ESGSessionUnregisterCallbacks unregisters callbacks registered via ENATSC3ESGSessionRegisterCallbacks. The callbacks and user data pointer are treated as a set; all callbacks and the user data pointer must match a prior call to ENATSC3ESGSessionRegisterCallbacks for the callbacks to be unregistered.

Parameters
    • hSession: A handle to the ESG processor on which to unregister the callbacks.
    • ServiceFragmentCallback: The service fragment callback to unregister.
    • ScheduleFragmentCallback: The schedule fragment callback to unregister.
    • ContentFragmentCallback: The content fragment callback to unregister.
    • pUserData: The user data pointer to unregister.
Return Values
    • ENATSC3Status_Success: The callbacks were unregistered.
    • ENATSC3Status_Failure: An error was encountered while registering the callbacks. This may indicate that the set of callbacks and the user data pointer did not match a corresponding set registered via ENATSC3ESGSessionRegisterCallbacks.
ENATSC3Status ENATSC3ESGSessionSetVerbosity(
    ENATSC3ESGSessionHandle_t hSession,
    ENVerbosity verbosity
);

ENATSC3ESGSessionSetVerbosity specifies the logging verbosity for the ESG processor.

Parameters
    • hSession: A handle to the ESG processor on which to set the verbosity.
    • verbosity: The verbosity level to set.
Return Values
    • ENATSC3Status_Success: The verbosity level was set.
    • ENATSC3Status_Failure: An error was encountered while setting the verbosity level.