libenatsc3ipv4

libentasc3ipv4 implements an IPv4 packet processor accepting  IPv4 packets and producing assembled transport layer (UDP for ATSC 3) packets.

Usage

    • Applications instantiate an IPv4 packet processor via ENATSC3IPV4Open.
    • Applications use ENATSC3IPV4RegisterTransportPacketCallbacks to register a callback function to be called when  assembled transport layer packets are available.
    • As IPv4 packets are received the application calls ENATSC3IPV4ProcessIPV4Packet to provide them to the processor. The processor calls the ENATSC3IPV4TransportPacketCallbackFunction  callback as assembled transport layer packets become available.
    • When the application is done with the processor it is closed by ENATSC3IPV4Close.

Callback Functions

typedef void (*ENATSC3IPV4TransportPacketCallbackFunction)(
    int32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t sourceAddress, 
    uint32_t destinationAddress, 
    uint16_t protocol,
    const uint8_t *pPacket, 
    int32_t sPacket, 
    void *pUserData
);

ENATSC3IPV4TransportPacketCallbackFunction is called by the IPv4 packet processor to deliver an assembled transport layer packet to the application.

Parameters
    • plpId: The PLP on which the IPv4 packet was received.
    • pPacketTimeUTC: The timestamp of the baseband packet from which the transport packet was received. If the transport packet spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the IPv4 packet.
    • packetNumber: The packet number of the baseband packet from which the transport packet was received. If the transport packet spans baseband packets then the packet number is obtained from the first baseband packet containing a fragment of the transport packet
    • sourceAddress: The source address of the transport packet.
    • destinationAddress: The destination address of the transport packet.
    • protocol: The internet protocol of the assembled packet. A value of 17 indicates UDP.
    • pPacket: The IPv4 assembled 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 ENATSC3IPV4Open(
    ENATSC3IPV4Handle_t *phATSC3IPV4
);

ENATSC3IPV4Open instantiates an IPv4 packet processor.

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

ENATSC3IPV4Close closes an IPv4 packet processor opened with ENATSC3IPV4Open.

Parameters
    • hATSC3IPV4: A handle to the IPv4 packet processor to close.
Return Values
    • ENStatus_Success: The processor was closed.
    • ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3IPV4RegisterCallbacks(
    ENATSC3IPV4Handle_t hATSC3IPV4,
    ENATSC3IPV4TransportPacketCallbackFunction pTransportPacketCallback,
    void *pUserData
);

ENATSC3IPV4RegisterCallbacks registers functions to be called when processor events occur.

Parameters
    • hATSC3IPV4: A handle to the IPv4 packet processor on which to register the callbacks.
    • pTransportPacketCallback: The function called when assembled transport layer packets are 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 ENATSC3IPV4ProcessIPV4Packet(
    ENATSC3IPV4Handle_t hATSC3IPV4,
    int32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    const uint8_t *pPayload, 
    int32_t payloadLength
);

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

Parameters
    • hATSC3IPV4: A handle to the IPv4 packet processor receiving the IPv4 fragment.
    • plpId: The PLP on which the IPv4 packet originated.
    • pPacketTimeUTC: The time at which the IPv4 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 IPv4 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 IPv4 packet.
    • payloadLength: The number of bytes referenced by pPayload.
Return Values
    • ENStatus_Success: The IPv4 fragment was accepted by the processor.
    • ENStatus_Failure: The packet was rejected by the processor.