libenatsc3alp

libentasc3alp implements an ATSC 3.0 ALP packet processor accepting ALP packets and producing network packets and link-layer signaling.

The library is aware of both standard LMTs and “Korean” LMTs and will process ALP packet streams with either type of LMT.

Usage

    • Applications instantiate an ALP packet processor via ENATSC3ALPOpen.
    • Applications use ENATSC3ALPRegisterCallbacks to register callback function to be called when  network packets or link-layer signaling are available.
    • The application sets the PLP(s) on which the processor operates by calling ENATSC3ALPSetPLPs. The PLPs can be changed at any time by calling ENATSC3ALPSetPLPs.
    • As ALP packets are received the application calls ENATSC3ALPProcessALPPacket to provide them to the processor. The processor calls the ENATSC3ALPIPV4CallbackFunction callback as IPV4 packets are produced and ENATSC3ALPLinkLayerSignalingCallbackFunction as signaling information becomes available.
    • When the application is done with the processor it is closed by ENATSC3ALPClose.

Callback Functions

typedef void (*ENATSC3ALPIPV4CallbackFunction)(
    uint32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    const uint8_t *pPacket, 
    int32_t sPacket, 
    int32_t SID, 
    void *pUserData
);

ENATSC3ALPIPV4CallbackFunction is called by the ALP packet processor to deliver an IPV4 packet to the application.

Parameters
    • plpId: The PLP on which the ALP packet was received.
    • pPacketTimeUTC: The timestamp of the baseband packet from which the ALP packet was received. If the ALP packet spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the ALP packet.
    • packetNumber: The packet number of the baseband packet from which the IPV4 packet was received. If the IPV4 packet spans baseband packets then the packet number is obtained from the first baseband packet containing a fragment of the IPV4 packet.
    • pPacket: The IPV4 packet. The data pointed to by pPacket is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sPacket: The number of bytes referenced by pPacket.
    • SID: The sub-stream identifier, if present. If the sub-stream ID is not present then SID has a value of -1.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ALPLinkLayerSignalingCallbackFunction)(
    uint32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    const uint8_t *pPacket, 
    int32_t sPacket, 
    void *pUserData
);

ENATSC3ALPLinkLayerSignalingCallbackFunction is called by the ALP packet processor to deliver a packet containing signaling information to the application.

Parameters
    • plpId: The PLP on which the ALP packet was received.
    • pPacketTimeUTC: The timestamp of the baseband packet from which the ALP packet was received. If the ALP packet spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the ALP packet.
    • packetNumber: The packet number of the baseband packet from which the IPV4 packet was received. If the IPV4 packet spans baseband packets then the packet number is obtained from the first baseband packet containing a fragment of the IPV4 packet.
    • pPacket: The IPV4 packet. The data pointed to by pPacket is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sPacket: The number of bytes referenced by pPacket.
    • pUserData: Application data provided when the callback was registered.

Function Reference

ENStatus ENATSC3ALPOpen(
    ENATSC3ALPHandle_t *phATSC3ALP
);

ENATSC3ALPOpen instantiates an ALP packet processor.

Parameters
    • phATSC3ALP: On successful return contains a handle to the ALP processor.
Return Values
    • ENStatus_Success: An ALP packet processor was instantiated and a handle to the processor is returned in *phATSC3ALP. The processor must be closed with ENATSC3ALPClose when the application no longer requires the processor.
    • ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phATSC3ALP is undefined.
ENStatus ENATSC3ALPClose(
    ENATSC3ALPHandle_t hATSC3ALP
);

ENATSC3ALPClose closes an ALP packet processor opened with ENATSC3ALPOpen.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor to close.
Return Values
    • ENStatus_Success: The processor was closed.
    • ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3ALPRegisterCallbacks(
    ENATSC3ALPHandle_t hATSC3ALP,
    ENATSC3ALPIPV4CallbackFunction pIPV4Callback,
    ENATSC3ALPLinkLayerSignalingCallbackFunction pLinkLayerSignalingCallback,
    void *pUserData
);

ENATSC3ALPRegisterCallbacks registers functions to be called when processor events occur.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor on which to register the callbacks.
    • pIPV4Callback: The function called when IPV4 packets are available.
    • pLinkLayerSignalingCallback: The function called when a signaling message is available.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callbacks were registered.
    • ENStatus_Failure: An error was encountered while registering the callbacks.
ENStatus ENATSC3ALPSetPLPs(
    ENATSC3ALPHandle_t hALP, 
    uint64_t plpIdMask
);

ENATSC3ALPSetPLPs specifies the PLPs on which the processor operates. ALP packets corresponding to other PLPs are ignored.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor on which to specify the PLPs.
    • plpIdMask: A bitmask indicating the PLPs the processor operates on. A ‘1’ in the corresponding bit position enables processing. For example a plpIdMask of 0x8000000000000007 enables PLPs 0, 1 and 2, and 63.
Return Values
    • ENStatus_Success: The PLPs were set.
    • ENStatus_Failure: An error was encountered while setting the PLPs.
ENStatus ENATSC3ALPProcessALPPacket(
    ENATSC3ALPHandle_t hATSC3ALP, 
    uint32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    const uint8_t *pPayload, 
    int32_t payloadLength
);

Applications call ENATSC3ALPProcessALPPacket to provide ALP packets to the processor. The ALP packet’s payload is not assumed to be available once ENATSC3ALPProcessALPPacket returns.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor receiving the ALP packet.
    • plpId: The PLP on which the ALP packet originated.
    • pPacketTimeUTC: The time at which the ALP packet was received from the demodulator. This timestamp is not used by the Base Stack libraries but is passed throughout throughout the stack for use by the application.
    • packetNumber: The baseband packet number (counter) corresponding to the ALP packet. The packet number is not used by the Base Stack libraries but is passed throughout the stack for use by the application.
    • pPayload: The ALP packet.
    • payloadLength: The number of bytes referenced by pPayload.
Return Values
    • ENStatus_Success: The ALP packet was accepted by the procesor.
    • ENStatus_Failure: The packet was rejected by the processor.
ENStatus ENATSC3ALPSetVerbosity(
    ENATSC3ALPHandle_t hATSC3ALP,
    ENVerbosity verbosity
);

ENATSC3ALPSetVerbosity specifies the logging verbosity for the ALP packet processor.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor on which to set the verbosity.
    • verbosity: The verbosity level to set.
Return Values
    • ENStatus_Success: The verbosity level was set.
    • ENStatus_Failure: An error was encountered while setting the verbosity level.
void ENATSC3ALPSetBitrateStatisticsEnabled(
    ENATSC3ALPHandle_t hATSC3ALP, 
    int32_t fEnabled
);

ENATSC3ALPSetBitrateStatisticsEnabled enables or disables bitrate statistics collection. When enabled statistics such as the ALP packet bitrate is registered with the bitrate statistics facility in libenatsc3utils.

Parameters
    • hATSC3ALP: A handle to the ALP packet processor on which to enable or disable statistics collection.
    • fEnabled: Whether to enable (non-zero) or disable (zero) collection..