libentasc3j288alp implements a J288 packet processor accepting J288 packets carrying ATSC 3.0 ALP packets and producing ALP and/or baseband packets. When baseband packets are requested the provided baseband packet is synthesized by wrapping an ALP packet in a baseband packet.
Usage
-
- Applications instantiate a J288 packet processor via ENATSC3J288ALPOpen.
- Applications use ENATSC3J288ALPRegisterCallbacks to register callback functions to be called when ALP or baseband packets or PTP information is available.
- As J288 packets are received the application calls ENATSC3J288ALPProcessJ288Packets to provide them to the processor. The processor calls the ENATSC3J288BasebandCallbackFunction and/or ENATSC3J288ALPCallbackFunction callbacks as ALP packets are extracted. The ENATSC3J288PTPCallbackFunction is called when PTP information is obtained.
- When the application is done with the processor it is closed by ENATSC3J288ALPClose.
Types
typedef struct
{
// See A/322 9.2.1. The time_info_flag indicates whether the physical
// layer frame from which the L1B was extracted contains timing
// information, and if so to what precision. Valid values are:
// 0: Time information is not included in the current frame.
// 1: Time information is included in the current frame and signaled
// to ms precision.
// 2: Time information is included in the current frame and signaled
// to us precision.
// 3: Time information is included in the current frame and signaled
// to ns precision.
int32_t L1B_time_info_flag;
// See A/322 9.3.1.
uint32_t L1D_time_sec;
uint16_t L1D_time_msec;
uint16_t L1D_time_usec;
uint16_t L1D_time_nsec;
} ENATSC3J288PTPInfo;
Callback Functions
typedef void(*ENATSC3J288ALPCallbackFunction)(
uint32_t plpId,
struct timespec *pPacketTimeUTC,
uint64_t packetNumber,
int32_t fError,
const uint8_t *pPacket,
int32_t sPacket,
void *pUserData
);
ENATSC3J288BasebandCallbackFunction is called by the J288 packet processor to deliver an ALP packet to the application.
Parameters
-
- plpId: The PLP on which the ALP packet was received.
- pPacketTimeUTC: The timestamp of the J288 packet from which the ALP packet was received. If the ALP packet spans J288 packets then the timestamp is obtained from the first J288 packet containing a fragment of the ALP packet.
- packetNumber: The packet number of the J288 packet from which the ALP packet was received. If the ALP packet spans J288 packets then the packet number is obtained from the first J288 packet containing a fragment of the ALP packet.
- pPacket: The ALP 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.
typedef void(*ENATSC3J288BasebandCallbackFunction)(
uint32_t plpId,
struct timespec *pPacketTimeUTC,
uint64_t packetNumber,
int32_t fError,
const uint8_t *pPacket,
int32_t sPacket,
void *pUserData
);
ENATSC3J288BasebandCallbackFunction is called by the J288 packet processor to deliver an ALP packet wrapped in a baseband packet to the application.
Parameters
-
- plpId: The PLP on which the ALP packet was received.
- pPacketTimeUTC: The timestamp of the J288 packet from which the ALP packet was received. If the ALP packet spans J288 packets then the timestamp is obtained from the first J288 packet containing a fragment of the ALP packet.
- packetNumber: The packet number of the J288 packet from which the ALP packet was received. If the ALP packet spans J288 packets then the packet number is obtained from the first J288 packet containing a fragment of the ALP packet.
- pPacket: The baseband 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.
typedef void(*ENATSC3J288PTPCallbackFunction)(
struct timespec *pPacketTimeUTC,
uint64_t packetNumber,
ENATSC3J288PTPInfo *pPTPInfo,
void *pUserData
);
ENATSC3J288PTPCallbackFunction is called by the J288 packet processor when PTP information is found in the J288 stream.
Parameters
-
- pPacketTimeUTC: The timestamp of the J288 packet from which the PTP information was received.
- packetNumber: The packet number of the J288 packet from which the PTP information was received.
- pPTPInfo: The PTP information. The data pointed to by pPTPInfo is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
- pUserData: Application data provided when the callback was registered.
Function Reference
ENStatus ENATSC3J288ALPOpen(
ENATSC3J288ALPHandle_t *phATSC3J288ALP
);
ENATSC3J288ALPOpen instantiates a J288 packet processor.
Parameters
-
- phATSC3J288ALP: On successful return contains a handle to the J288 processor.
Return Values
-
- ENStatus_Success: A J288 packet processor was instantiated and a handle to the processor is returned in *phATSC3J288ALP. The processor must be closed with ENATSC3J288ALPClose when the application no longer requires the processor.
- ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phATSC3J288ALPis undefined.
ENStatus ENATSC3J288ALPClose(
ENATSC3J288ALPHandle_t hATSC3J288ALP
);
ENATSC3J288ALPClosecloses a J288 packet processor opened with ENATSC3J288ALPOpen.
Parameters
-
- hATSC3J288ALP: A handle to the J288 packet processor to close.
Return Values
-
- ENStatus_Success: The processor was closed.
- ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3J288ALPRegisterCallbacks(
ENATSC3J288ALPHandle_t hATS3J288ALP,
ENATSC3J288ALPCallbackFunction pALPCallback,
ENATSC3J288BasebandCallbackFunction pBasebandCallback,
ENATSC3J288PTPCallbackFunction pPTPCallback,
void *pUserData
);
ENATSC3J288ALPRegisterCallbacks registers functions to be called when processor events occur.
Parameters
-
- hATS3J288ALP: A handle to the J288 packet processor on which to register the callbacks.
- pALPCallback: The function called when ALP packets are available.
- pBasebandCallback: The function called when ALP packets are available. The baseband packet delivered is a single ALP packet wrapped in a baseband packet.
- pPTPCallback: The function called when PTP information 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 ENATSC3J288ALPProcessJ288Packets(
ENATSC3J288ALPHandle_t hATSC3J288ALP,
struct timespec *pPacketTimeUTC,
const uint8_t *pData,
int32_t nBytes
);
Applications cann ENATSC3J288ALPProcessJ288Packets to provide J288 packets to the processor. The J288 packet payloads are not assumed to be available once ENATSC3J288ALPProcessJ288Packets returns.
Parameters
-
- hATSC3J288ALP: A handle to the J288 packet processor receiving the J288 packets.
- pPacketTimeUTC: The time at which the first supplied J288 packet was received from the demodulator. This timestamp is not used by the Base Stack libraries but is passed throughout the stack for use by the application.
- pData: A pointer to J288 packets.
- nBytes: The number of bytes referenced by pData. nBytes must be a multiple of 188.
Return Values
-
- ENStatus_Success: The J288 packets were accepted by the procesor.
- ENStatus_Failure: One or more packets were rejected by the processor.
ENStatus ENATSC3J288ALPSetVerbosity(
ENATSC3J288ALPHandle_t hATSC3J288ALP,
ENVerbosity verbosity
);
ENATSC3J288ALPSetVerbosity specifies the logging verbosity for the J288 packet processor.
Parameters
-
- hATSC3J288ALP: A handle to the J288 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.