libenatsc3lls

libentasc3lls is a collection of functions which parse low-level signaling XML documents into a compact representation using EnXML. Definitions and functions are provided for parsing AEAT, OnScreenMessage, RRT, SLT, and SystemTime documents.

libenatsc3lls also provides a function for parsing LLS signed multitables into discrete LLS tables, which can then be processed as if they were delivered individually as (unsigned) tables.

Callback Functions

typedef void (*ENATSC3LLSTableCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    ENATSC3LLSTableHeader *pLLSTableHeader, 
    const uint8_t *pPayload,
    int32_t payloadLength, 
    int32_t fSigned, 
    void *pUserData
);

ENATSC3LLSTableCallbackFunction is called by ENATSC3LLSProcessSignedMultiTable to deliver a single table of a signed multitable to an application.

Parameters
    • pPacketTimeUTC: The packet time of the signed multitable as it was provided to ENATSC3LLSProcessSignedMultiTable.
    • packetNumber: The packet number of the signed multitable as it was provided to ENATSC3LLSProcessSignedMultiTable.
    • pLLSTableHeader: The LLS table header for the LLS table being delivered.
    • pPayload: The LLS table being delivered.
    • payloadLength: The length in bytes of the table pointed to by pPayload.
    • fSigned: This value is always 1 (true) when ENATSC3LLSTableCallbackFunction is called from ENATSC3LLSProcessSignedMultiTable. It is provided in the event that an application uses ENATSC3LLSTableCallbackFunction as a common function to process signed and unsigned tables.
    • pUserData: Application data provided to ENATSC3LLSProcessSignedMultiTable .

Function Reference

ENStatus ENATSC3LLSProcessSignedMultiTable(
    struct timespec *pPacketTimeUTC,
    uint64_t packetNumber, 
    const ENATSC3LLSTableHeader *pLLSTableHeader,
    const uint8_t *pPayload, 
    int32_t payloadLength,
    ENATSC3LLSTableCallbackFunction LLSTableCallback, 
    void *pUserData);

Parses a signed multitable document into its constituent documents and calls LLSTableCallback once for each document. Note that while the signed multitable is structurally checked, its signature is not verified. The application should call ENATSC3SSPVerifySignedMultitableSignature to verify a signed multitable’s signature prior to calling ENATSC3LLSProcessSignedMultiTable.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the signed multitable was received. If the signed multitable spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the signed multitable.
    • packetNumber: The packet number of the baseband packet from which the signed multitable was received. If the signed multitable spans baseband packets then the packet number is obtained from the first baseband packet containing a fragment of the signed multitable.
    • pLLSTableHeader: A pointer to the four-byte LLS table header. See A/331 Table 6.1 “Common Bit Stream Syntax for LLS Tables”.
    • pPayload: The LLS table (i.e. SLT, RRT, etc. in A/331 Table 6.1 “Common Bit Stream Syntax for LLS Tables”.)
    • payloadLength: The length in bytes of the table pointed to by pPayload.
    • LLSTableCallback: A callback function called once for each table in the signed multitable.
    • pUserData: User data passed as the pUserData parameter of the LLSTableCallback callback function.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENStatus ATSC3LLSParseAEAT(
    const char *pXML, 
    int32_t sXML,
    ATSC3LLSAEAT_AEATNode *pParsedATSC3LLSAEAT
);

Parses an AEAT document to an EnXML representation.

Parameters
    • pXML: The XML document.
    • sXML: The number of bytes in the XML document.
    • pParsedATSC3LLSAEAT: A pointer to an ATSC3LLSAEAT_AEATNode. On successful return it is populated with the parsed document. pParsedATSC3LLSAEAT must be freed using  ATSC3LLSFreeParsedAEAT when the application is done with the parsed representation. On failure the contents of pParsedATSC3LLSAEAT is undefined and ATSC3LLSFreeParsedAEAT must not be called on it.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENStatus ATSC3LLSFreeParsedAEAT(
    ATSC3LLSAEAT_AEATNode *pParsedATSC3LLSAEAT
);

ATSC3LLSFreeParsedAEAT frees the memory associated with an  ATSC3LLSAEAT_AEATNode  that was parsed using ATSC3LLSParseAEAT.

Parameters
    • pParsedATSC3LLSAEAT: A pointer to the ATSC3LLSAEAT_AEATNode .
Return Values
    • ENStatus_Success: The object was freed.
    • ENStatus_Failure: An error was encountered while freeing the object.
ENStatus ATSC3LLSParseOnscreenMessageNotification(
    const char *pXML, 
    int32_t sXML,
    ATSC3LLSOSMN_OnscreenMessageNotificationNode *pParsedOnscreenMessageNotification
);

Parses an OnScreenMessageNotification document to an EnXML representation.

Parameters
    • pXML: The XML document.
    • sXML: The number of bytes in the XML document.
    • pParsedOnscreenMessageNotification: A pointer to an ATSC3LLSOSMN_OnscreenMessageNotificationNode. On successful return it is populated with the parsed document. pParsedOnscreenMessageNotification must be freed using  ATSC3LLSFreeParsedOnscreenMessageNotification when the application is done with the parsed representation. On failure the contents of pParsedOnscreenMessageNotification is undefined and ATSC3LLSFreeParsedOnscreenMessageNotification must not be called on it.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENBATSC3Status ATSC3LLSFreeParsedOnscreenMessageNotification(
    ATSC3LLSOSMN_OnscreenMessageNotificationNode *pParsedOnscreenMessageNotification
);

ATSC3LLSFreeParsedOnscreenMessageNotificationfrees the memory associated with an  ATSC3LLSOSMN_OnscreenMessageNotificationNode that was parsed using ATSC3LLSParseOnscreenMessageNotification.

Parameters
    • pParsedOnscreenMessageNotification: A pointer to the ATSC3LLSOSMN_OnscreenMessageNotificationNode .
Return Values
    • ENStatus_Success: The object was freed.
    • ENStatus_Failure: An error was encountered while freeing the object.
ENStatus ATSC3LLSParseRRT(
    const char *pXML, 
    int32_t sXML,
    ATSC3LLSRRT_RatingRegionTablesNode *
pRatingRegionTablesNode);

Parses an RRT document to an EnXML representation.

Parameters
    • pXML: The XML document.
    • sXML: The number of bytes in the XML document.
    • pRatingRegionTablesNode: A pointer to an ATSC3LLSRRT_RatingRegionTablesNodeOn successful return it is populated with the parsed document. pRatingRegionTablesNode must be freed using  ATSC3LLSFreeParsedRRT when the application is done with the parsed representation. On failure the contents of pRatingRegionTablesNode  is undefined and ATSC3LLSFreeParsedRRT must not be called on it.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENStatus ATSC3LLSFreeParsedRRT(
    ATSC3LLSRRT_RatingRegionTablesNode *pRatingRegionTablesNode
);

ATSC3LLSFreeParsedRRT frees the memory associated with an  ATSC3LLSRRT_RatingRegionTablesNode that was parsed using ATSC3LLSParseRRT.

Parameters
    • pRatingRegionTablesNode: A pointer to the ATSC3LLSRRT_RatingRegionTablesNode .
Return Values
    • ENStatus_Success: The object was freed.
    • ENStatus_Failure: An error was encountered while freeing the object.
ENStatus ATSC3LLSParseSLT(
    const char *pXML, 
    int32_t sXML,
    ATSC3LLSSLT_SLTNode *pParsedSLT
);

Parses an SLT document to an EnXML representation.

Parameters
    • pXML: The XML document.
    • sXML: The number of bytes in the XML document.
    • pParsedSLT: A pointer to an ATSC3LLSSLT_SLTNode. On successful return it is populated with the parsed document. pParsedSLT must be freed using  ATSC3LLSFreeParsedSLT when the application is done with the parsed representation. On failure the contents of pParsedSLT is undefined and ATSC3LLSFreeParsedSLT must not be called on it.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENStatus ATSC3LLSFreeParsedSLT(
    ATSC3LLSSLT_SLTNode *pParsedSLT
);

ATSC3LLSFreeParsedSLT frees the memory associated with an  ATSC3LLSSLT_SLTNode  that was parsed using ATSC3LLSParseSLT.

Parameters
    • pParsedSLT: A pointer to the ATSC3LLSSLT_SLTNode .
Return Values
    • ENStatus_Success: The object was freed.
    • ENStatus_Failure: An error was encountered while freeing the object.
ENStatus ATSC3LLSParseSystemTime(
    const char *pXML, 
    int32_t sXML,
    ATSC3LLSSystemTime_SystemTimeNode *pParsedSystemTime
);

Parses a SystemTimw document to an EnXML representation.

Parameters
    • pXML: The XML document.
    • sXML: The number of bytes in the XML document.
    • pParsedSystemTime: A pointer to an ATSC3LLSSystemTime_SystemTimeNode . On successful return it is populated with the parsed document. pParsedSystemTime must be freed using  ATSC3LLSFreeParsedSystemTime when the application is done with the parsed representation . On failure the contents of pParsedSystemTime is undefined and ATSC3LLSFreeParsedSystemTime must not be called on it.
Return Values
    • ENStatus_Success: The document was successfully parsed.
    • ENStatus_Failure: An error was encountered parsing the document.
ENStatus ATSC3LLSFreeParsedSystemTime(
    ATSC3LLSSystemTime_SystemTimeNode *pParsedSystemTime
);

ATSC3LLSFreeParsedSystemTime frees the memory associated with an  ATSC3LLSSystemTime_SystemTimeNode that was parsed using ATSC3LLSParseSystemTime.

Parameters
    • pParsedSystemTime: A pointer to the ATSC3LLSSystemTime_SystemTimeNode .
Return Values
    • ENStatus_Success: The object was freed.
    • ENStatus_Failure: An error was encountered while freeing the object.