libenatsc3route

libenatsc3route implements  a ROUTE session processor which listens on the SLS address/port for an S-TSID and instantiates LCT channels as required to receive objects delivered via the ROUTE session.

The application is notified of receipt of files, SLS documents, and changes in the ROUTE session state via callback functions. Callbacks fall into the following categories:

    • File receipt
    • Service-level signaling document availability (MPD, HELD, STSID)
    • IP address added/removed
    • LCT channel added/removed

The present implementation supports the SourceFlow component of LCT channels. It does not process RepairFlow components.

Usage

    • Applications obtain a ROUTE session processor by calling ENATSC3ROUTESessionAllocate.
    • Applications register for callbacks of interest using  ENATSC3ROUTESessionRegisterMPDAvailableCallback, ENATSC3ROUTESessionRegisterHELDAvailableCallback , ENATSC3ROUTESessionRegisterSTSIDAvailableCallback, ENATSC3ROUTESessionRegisterLCTChannelCallbacks, and ENATSC3ROUTESessionRegisterObjectCallbacks.
    • As UDP packets are received the application calls ENATSC3ROUTESessionProcessUDPPacket to provide them to the processor. The processor calls the various callback functions to deliver the various objects to the application as they are received.
    • When the application is done with the processor it is released by calling ENATSC3ROUTESessionFree.

Types

typedef enum
{
    ENATSC3ROUTESessionIdType_Unknown = 0,
    ENATSC3ROUTESessionIdType_RepId = 1,
    ENATSC3ROUTESessionIdType_Segment0URL = 2,
} ENAGTSC3ROUTESessionIdType;

ENATSC3ROUTESessionIdType specifies the type of identifier provided to allow an application to map LCT channels and objects delivered via them to DASH representations. This identifier can be either the representation Id (ENATSC3ROUTESessionIdType_RepId ) if it is provided in SrcFlow -> ContentInfo -> MediaInfo. Or, If the representation Id is not provided, then the identifier is the URL of segment 0 (as derived by applying TOI=0 to the segment template) (ENATSC3ROUTESessionIdType_Segment0URL).

typedef enum
{
    ENATSC3ROUTESessionType_Invalid = 0,
    ENATSC3ROUTESessionType_ATSC3_DASH = 1,
    ENATSC3ROUTESessionType_ATSC3_ESG = 2,
} ENATSC3ROUTESessionType;

ENATSC3ROUTESessionType indicates whether a ROUTE session carries DASH objects or ESG objects.

Callback Functions

typedef ENStatus(*ENATSC3ROUTESessionMPDAvailableCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    const char *pMPD, 
    int32_t sMPD,
    int32_t version, 
    uint32_t crc32, 
    void *pUserData
);

The MPD callback is called when a MPD is received. The application may register multiple callback functions for the MPD. Callbacks return ENStatus_Success if the MPD was accepted and the callback does not wish to be called until the version and/or crc32 changes. If all registered callbacks return Success then the MPD is considered accepted and no further callbacks will occur until the version or crc32  changes. If any callback for the MPD returns a status other than ENStatus_Success then the  MPD is considered rejected and the next instance of the STSID observed will be delivered to all callbacks. When multiple callbacks are registered for an MPD then each function must be prepared to be called multiple times with an MPD with the same version and crc32 in the event that the document was rejected by another callback function.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the document was received. If the document spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the document.
    • packetNumber: The packet number of the baseband packet from which the document was received. If the document spans baseband packets then the counter is associated with the first baseband packet containing a fragment of the document.
    • pMPD: The received document. The data pointed to is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sMPD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the enclosing MIME envelope.
    • crc32: A CRC computed over the document.
    • pUserData: Application data provided when the callback was registered.
typedef ENStatus (*ENATSC3ROUTESessionHELDAvailableCallbackFunction)( 
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    const char *pHELD, 
    int32_t sHELD, 
    int32_t version, 
    uint32_t crc32, 
    void *pUserData
);

The HELD callback is called when a HELD is received. The application may register multiple callback functions for the HELD. Callbacks return ENStatus_Success if the HELD was accepted and the callback does not wish to be called until the version and/or crc32 changes. If all registered callbacks return Success then the HELD is considered accepted and no further callbacks will occur until the version or crc32  changes. If any callback for the HELD returns a status other than ENStatus_Success then the  HELD is considered rejected and the next instance of the STSID observed will be delivered to all callbacks. When multiple callbacks are registered for an HELD then each function must be prepared to be called multiple times with an HELDwith the same version and crc32 in the event that the document was rejected by another callback function.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the document was received. If the document spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the document.
    • packetNumber: The packet number of the baseband packet from which the document was received. If the document spans baseband packets then the counter is associated with the first baseband packet containing a fragment of the document.
    • pHELD: The received document. The data pointed to is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sHELD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the enclosing MIME envelope.
    • crc32: A CRC computed over the document.
    • pUserData: Application data provided when the callback was registered
typedef ENStatus (*ENATSC3ROUTESessionSTSIDAvailableCallbackFunction)( 
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    const char *pDocument, 
    int32_t sDocument, 
    ATSC3SLSSTSIDNodePtr pParsedSTSID, 
    int32_t version, 
    uint32_t crc32, 
    void *pUserData
);

The STSID callback is called when a STSID is received. The application may register multiple callback functions for the STSID. Callbacks return ENStatus_Success if the STSID was accepted and the callback does not wish to be called until the version and/or crc32 changes. If all registered callbacks return Success then the STSID is considered accepted and no further callbacks will occur until the version or crc32  changes. If any STSID callback returns a status other thanENStatus_Success then the  STSID is considered rejected and the next instance of the STSID observed will be delivered to all callbacks. When multiple callbacks are registered for an STSID then each function must be prepared to be called multiple times with an STSID with the same version and crc32 in the event that the document was rejected by another callback function.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the document was received. If the document spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the document.
    • packetNumber: The packet number of the baseband packet from which the document was received. If the document spans baseband packets then the counter is associated with the first baseband packet containing a fragment of the document.
    • pSTSID: The received document. The data pointed to is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sSTSID: The number of bytes referenced by pDocument.
    • pParsedSTSID: A version of the document which has been parsed using the ENXML parser.
    • version: The document version as indicated by the enclosing MIME envelope.
    • crc32: A CRC computed over the document.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ROUTESessionObjectDataCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t tsi,
    uint32_t toi, 
    uint8_t codepoint,
    int32_t formatId, 
    int32_t frag,
    int32_t order, 
    const char *pId,
    ENATSC3ROUTESessionIdType idType, 
    const uint8_t *pPayload, 
    int32_t payloadLength,
    int64_t objectPosition, 
    int64_t tolTransferLength,
    int64_t ftiTransferLength, 
    int32_t fError, 
    void *pUserData
);

The Object Data Callback delivers objects received over the LCT channels to the application. It is called as LCT packets carrying the object data is received. It is expected that the application will use the tsi and toi to uniquely identify objects and note any missing data by monitoring the objectPosition. Bot the tol and fti transfer lengths are provided. It should be noted that these may not be valid in the case where the sender begins transmitting an object before its length is known. In addition, due to data loss it is possible that the transfer length is never received, in which case it may not be possible to determine if an object was fully received (i.e. the case where only the transfer length was lost vs the case where the transfer length and the tailing portion of the object was lost.) libenatsc3route aims to make available as much information as possible so that applications can implement policies on how to address such errors without imposing any policies itself.

Parameters
    • pPacketTimeUTC: The timestamp of the baseband packet from which the document was received. If the document spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the document.
    • packetNumber: The packet number of the baseband packet from which the document was received. If the document spans baseband packets then the counter is associated with the first baseband packet containing a fragment of the document.
    • tsi: The TSI of the LCT channel on which the object is being received.
    • toi The TOI of the object being received.
    • codepoint: The codepoint extracted from the LCT header containing the object fragment delivered in the callback.
    • formatId: an 8-bit value derived from codepoint indicating the payload format for objects received on the LCT chanel, See A/331 A.3.2.2.
    • frag: An 8-bit value derived from codepoint indicating how objects received on the LCT channel are fragmented. See A/331 A.3.2.2.
    • order: A boolean value derived from codepoint indicating where DASH segments are delivered in order (order=1) or may have arbitrary order (order=0). See A/331 A.3.2.2.
    • pId: An identifier allowing the application to map the object being delivered to a DASH representation. See the ROUTESessionIdType type for more information.
    • idType: Whether pId contains a representation Id or the URL of the segment with TOI=0.
    • pPayload: The payload delivered in this callback. It represents the portion of the object from objectPosition to objectPoisition + payloadLength.
    • payloadLength: The length in bytes of pPayload.
    • objectPosition: The position within the object at which pPayload begins.
    • tolTransferLength: The value of the TOL LCT header extension, if it is present. -1 otherwise.
    • ftiTransferLength: The value of the FTI LCT extension header, if it is present. -1 otherwise.
    • fError: If non-zero then pPayload may contain error’d data. A non-zero fError means that a reception error was detected at a lower level in the stack (e.g. the demodulator indicated that the baseband packet contained unrecoverable errors, or the IP/UDP checksum failed). Because packets lower in the stack may correspond to multiple LCT packets it is not guaranteed that the LCT payload corresponding to this particular LCT packet is in error.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ROUTESessionLCTChannelAddedCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t addr,
    uint16_t port, 
    uint32_t tsi, 
    const char *pId, 
    ENATSC3ROUTESessionIdType idType,
    void *pUserData
);

The LCT Channel Added callback is called when an LCT channel is added to the ROUTE session.

Parameters
    • pPacketTimeUTC: The timestamp of the last baseband packet received.
    • packetNumber: The packet number of the last baseband packet received.
    • addr: The IP address of the LCT channel being added.
    • port: The port of the LCT channel being added.
    • tsi: The TSI of the LCT channel being added.
    • pId: An identifier allowing the application to map the LCT channel to a DASH representation. See the ROUTESessionIdType type for more information.
    • idType: Whether pId contains a representation Id or the URL of the segment with TOI=0.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ROUTESessionLCTChannelRemovedCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t addr,
    uint16_t port, 
    uint32_t tsi, 
    void *pUserData
);

The LCT Channel Removed callback is called when an LCT channel is removed from the ROUTE session.

Parameters
    • pPacketTimeUTC: The timestamp of the last baseband packet received.
    • packetNumber: The packet number of the last baseband packet received.
    • addr: The IP address of the LCT channel being removed.
    • port: The port of the LCT channel being removed.
    • tsi: The TSI of the LCT channel being removed.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ROUTESessionSessionResetCallbackFunction)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    void *pUserData
);

The Session Reset callback is called when the ROUTE session is reset to provide the application an opportunity to reset any associated state. In addition to this callback, the LCT Channel Removed callback will be called for each open LCT channel after the Session Reset callback.

typedef void (*ENATSC3ROUTESessionIPAddressAddCallbackFunction)(
    uint32_t addr,
    uint16_t port, 
    void *pUserData
);

The ROUTE session calls the IP Address Add callback to alert the application that it requires packets on the indicated address and port. If an applicaion is filtering packets then it must enable the address/port. The session may call the IP Address Add and IP Address Remove callback multiple times before calling IP Address Commit. The application is not required to begin passing packets on the requested address/port until Commit is called.

The sesion may call IP Address Add multiple times for an address/port combination. If the application is filtering packets it must reference count or otherwise ensure packets on the addres/port are passed until an equal IP Address Remove has been called an equal number of times.

ParameterS
    • addr: The IP address being added.
    • port: The port being added..
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ROUTESessionIPAddressRemoveCallbackFunction)(
    uint32_t addr,
    uint16_t port, 
    void *pUserData
);

The ROUTE session calls the IP Address Remove callback to alert the application that it no longer requires packets on the indicated address and port.  The session may call the IP Address Add and IP Address Remove callback multiple times before calling IP Address Commit. The application is not required to begin passing packets on the requested address/port until Commit is called.

The session may call IP Address Add and IP Address Remove multiple times for an address/port combination. If the application is filtering packets it must reference count or otherwise ensure packets on the address/port are passed until an equal IP Address Remove has been called an equal number of times.

ParameterS
    • addr: The IP address being added.
    • port: The port being added..
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3ROUTESessionIPAddressCommitFunction)(
    void *pUserData
);

The ROUTE session calls the IP Address Commit callback to alert the application that it should process previous IP Address Add and IP Address Remove request. The session may call the IP Address Add and IP Address Remove callback multiple times before calling IP Address Commit. The application is not required to begin passing packets on the requested address/port until Commit is called.

ParameterS
    • pUserData: Application data provided when the callback was registered.

Function Reference

ENStatus ENATSC3ROUTESessionAllocate(
    ENATSC3ROUTESessionType routeSessionType,
    uint32_t slsAddr, 
    int32_t slsPort,
    ENATSC3ROUTESessionIPAddressAddCallbackFunction IPAddressAddCallback,
    ENATSC3ROUTESessionIPAddressRemoveCallbackFunction IPAddressRemoveCallback,
    ENATSC3ROUTESessionIPAddressCommitCallbackFunction IPAddressCommitCallback,
    void *pIPAddrCallbackUserData, 
    char *pDebugName,
    ENATSC3ROUTESessionHandle_t *phROUTESession
);

ENATSC3ROUTESessionAllocate allocates a ROUTE session processor and begins listening on LCT Channel with TSI=0 on the indicated address and port. If the session type is DASH then the processor obtains additional information from the S-TSID that allows mapping of LCT channels to DASH representations.

Parameters
    • routeSessionType: Either ENATSC3ROUTESessionType_DASH or ENATSC3ROUTESessionType_ESG, indicating the type of objects delivered via the session.
    • slsAddr: The destrination IP address carrying SLS data for the service. The ROUTE proessor will listen on slsAddr/slsPort LCT channel 0 for service signaling.
    • slsPort: The destination port carrying SLS data for the service.
    • IPAddressAddCallback: Called to notify the application that data arriving on the indicated destination IP address and port are required by the processor.
    • IPAddressRemoveCallback: Called to notify the application that data arriving on the indicated destination IP address and port is no longer required by the processor.
    • IPAddressCommitCallback: Called after a sequence of IPAddressAddCallback and/or IPAddressRemoveCallback calls to indicate that the added and/or removed IP addresses should take effect. Applications may choose to process changed immediatelty or defer processing until IPAddressCommitCallback is called.
    • pIPAddrCallbackUserData: A pointer passed to the callback functions.
    • pDebugName: A string identifying this ROUTE session during debug logging.
    • phROUTESession: On successful return contains a handle to the ROUTE processor.
Return Values
    • ENStatus_Success: A ROUTE session processor was allocated and a handle to the processor is returned in *phROUTESession. The processor must be freedwith ENATSC3ROUTESessionFree when the application no longer requires the processor.
    • ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phROUTESession is undefined.
ENStatus ENATSC3ROUTESessionFree(
    ENATSC3ROUTESessionHandle_t hROUTESession
);

ENATSC3ROUTESessionFree frees a ROUTE session processor allocated with ENATSC3ROUTESessionAllocate.

Parameters
    • hROUTESession: A handle to the ROUTE session processor to free.
Return Values
    • ENStatus_Success: The processor was closed.
    • ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3ROUTESessionReset(
    ENATSC3ROUTESessionHandle_t hROUTESession
);

ENATSC3ROUTESessionReset resets a ROUTE session processor. All in-progress objects are aborted, LCT channels are removed, and all previously received signaling data is discarded.

Parameters
    • hROUTESession: A handle to the ROUTE session processor to reset.
Return Values
    • ENStatus_Success: The processor was reset.
    • ENStatus_Failure: An error was encountered while resetting the processor.
ENStatus ENATSC3ROUTESessionRegisterMPDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionMPDAvailableCallbackFunction MPDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionRegisterMPDAvailableCallback registers a function to be called when an MPD is received. The callback is called only when the processor encounters a new MPD – where either the version or crc32 computed over the MPD has changed. Multiple callbacks can be registered. The present implementation allows up to four registered callbacks. All registered callbacks must return ENStatus_Success before the processor considers the MPD as successfully received. If any callback returns a status other than ENStatus_Success then the processor considers the MPD rejected, and the callbacks may be called again with an MPD having the same version and crc32.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to register the callback.
    • MPDAvailableCallback: The function called when an MPD is received.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callback was registered.
    • ENStatus_Failure: An error was encountered while registering the callback.
ENStatus ENATSC3ROUTESessionUnegisterMPDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionMPDAvailableCallbackFunction MPDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionUnregisterMPDAvailableCallback unregisters a callback function previously registered with ENATSC3ROUTESessionRegisterMPDAvailableCallback. Both the callback function and user data pointer must match those provided to ENATSC3ROUTESessionRegisterMPDAvailableCallback.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to unregister the callback.
    • MPDAvailableCallback: The callback function previously provided to ENATSC3ROUTESessionRegisterMPDAvailableCallback..
    • pUserData: The user data pointer previously provided to ENATSC3ROUTESessionRegisterMPDAvailableCallback..
Return Values
    • ENStatus_Success: The callback was unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callback.
ENStatus ENATSC3ROUTESessionRegisterHELDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionHELDAvailableCallbackFunction HELDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionRegisterHELDAvailableCallback registers a function to be called when a HELD is received. The callback is called only when the processor encounters a new HELD – where either the version or crc32 computed over the HELD has changed. Multiple callbacks can be registered. The present implementation allows up to four registered callbacks. All registered callbacks must return ENStatus_Success before the processor considers the HELD as successfully received. If any callback returns a status other than ENStatus_Success then the processor considers the HELD rejected, and the callbacks may be called again with a HELD having the same version and crc32.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to register the callback.
    • HELDAvailableCallback: The function called when an HELD is received.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callback was registered.
    • ENStatus_Failure: An error was encountered while registering the callback.
ENStatus ENATSC3ROUTESessionUnegisterHELDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionHELDAvailableCallbackFunction HELDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionUnregisterHELDAvailableCallback unregisters a callback function previously registered with ENATSC3ROUTESessionRegisterHELDAvailableCallback. Both the callback function and user data pointer must match those provided to ENATSC3ROUTESessionRegisterHELDAvailableCallback.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to unregister the callback.
    • HELDAvailableCallback: The callback function previously provided to ENATSC3ROUTESessionRegisterHELDAvailableCallback..
    • pUserData: The user data pointer previously provided to ENATSC3ROUTESessionRegisterHELDAvailableCallback..
Return Values
    • ENStatus_Success: The callback was unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callback.
ENStatus ENATSC3ROUTESessionRegisterSTSIDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionSTSIDAvailableCallbackFunction STSIDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionRegisterSTSIDAvailableCallback registers a function to be called when an STSID is received. The callback is called only when the processor encounters a new STSID – where either the version or crc32 computed over the STSID has changed. Multiple callbacks can be registered. The present implementation allows up to four registered callbacks. All registered callbacks must return ENStatus_Success before the processor considers the MPD as successfully received. If any callback returns a status other than ENStatus_Success then the processor considers the STSID rejected, and the callbacks may be called again with an STSID having the same version and crc32.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to register the callback.
    • STSIDAvailableCallback: The function called when an STSID is received.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callback was registered.
    • ENStatus_Failure: An error was encountered while registering the callback.
ENStatus ENATSC3ROUTESessionUnegisterSTSIDAvailableCallback(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionMPDAvailableCallbackFunction STSIDAvailableCallback,
    void *pUserData
);

ENATSC3ROUTESessionUnregisterSTSIDAvailableCallback unregisters a callback function previously registered with ENATSC3ROUTESessionRegisterSTSIDAvailableCallback. Both the callback function and user data pointer must match those provided to ENATSC3ROUTESessionRegisterSTSIDAvailableCallback.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to unregister the callback.
    • STSIDAvailableCallback: The callback function previously provided to ENATSC3ROUTESessionRegisterSTSIDAvailableCallback.
    • pUserData: The user data pointer previously provided to ENATSC3ROUTESessionRegisterSTSIDAvailableCallback.
Return Values
    • ENStatus_Success: The callback was unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callback.
ENStatus ENATSC3ROUTESessionRegisterLCTChannelCallbacks(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionLCTChannelAddedCallbackFunction LCTChannelAddedCallback,
    ENATSC3ROUTESessionLCTChannelRemovedCallbackFunction LCTChannelRemovedCallback,
    void *pUserData
);

ENATSC3ROUTESessionRegisterLCTChannelCallbacks registers  functions to be called when an LCT channel is added to or removed from the ROUTE session..

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to register the callbacks.
    • LCTChannelAddedCallback: The function called when an LCT channel is added.
    • LCTChannelRemovedCallback: The function called when an LCT channel is removed.
    • 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 ENATSC3ROUTESessionUnregisterLCTChannelCallbacks(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionLCTChannelAddedCallbackFunction LCTChannelAddedCallback,
    ENATSC3ROUTESessionLCTChannelRemovedCallbackFunction LCTChannelRemovedCallback,
    void *pUserData
);

ENATSC3ROUTESessionUnregisterLCTChannelCallbacks unregisters  functions previously registered with ENATSC3ROUTESessionRegisterLCTChannelCallbacks. All function pointers as well as the user data pointer must match those provided to ENATSC3ROUTESessionRegisterLCTChannelCallbacks.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to unregister the callbacks.
    • LCTChannelAddedCallback: The function called when an LCT channel is added.
    • LCTChannelRemovedCallback: The function called when an LCT channel is removed.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callbacks were unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callbacks.
ENStatus ENATSC3ROUTESessionRegisterObjectCallbacks(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionObjectDataCallbackFunction ObjectDataCallback,
    ENATSC3ROUTESessionSessionResetCallbackFunction SessionResetCallback,
    void *pUserData
);

ENATSC3ROUTESessionRegisterObjectCallbacks registers  functions to be called when object data is received on an LCT channel or when the ROUTE session is reset.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to register the callbacks.
    • ObjectDataCallback: The function called when object data is received on an LCT channel.
    • SessionResetCallback: The function called when the ROUTE session is reset.
    • 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 ENATSC3ROUTESessionUnregisterObjectCallbacks(
    ENATSC3ROUTESessionHandle_t hROUTESession,
    ENATSC3ROUTESessionObjectDataCallbackFunction ObjectDataCallback,
    ENATSC3ROUTESessionSessionResetCallbackFunction SessionResetCallback,
    void *pUserData
);

ENATSC3ROUTESessionUnegisterObjectCallbacks unregisters  callback functions previously registered with ENATSC3ROUTESessionRegisterObjectCallbacks. All function pointers as well as the user data pointer must match those provided to ENATSC3ROUTESessionRegisterObjectCallbacks.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to unregister the callbacks.
    • ObjectDataCallback: The function called when object data is received on an LCT channel.
    • SessionResetCallback: The function called when the ROUTE session is reset.
    • pUserData: A pointer passed to the callback functions.
Return Values
    • ENStatus_Success: The callbacks were unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callbacks.
ENStatus ENATSC3ROUTESessionGetObjectURLAndContentType(
    ENATSC3ROUTESessionHandle_t hROUTESession, 
    uint32_t tsi, 
    uint32_t toi,
    char *pURL, 
    int32_t sURL, 
    char *pContentType, 
    int32_t sContentType
);

ENATSC3ROUTESessionGetObjectURLAndContentType obtains the URL and content-type associated with the object with the indicated TOI and received on the LCT channel with the indiated TSI.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to operate.
    • tsi: The TSI of the LCT channel delivering the object.
    • toi: The TOI of the object.
    • pURL: Pointer to a buffer where the zero-terminated URL will be stored.
    • sURL: The size of the buffer pointed to by pURL.
    • pContentType: Pointer to a buffer where the zero-terminated content-type will be stored.
    • sContentType: The size of the buffer pointed to by pContentType.
Return Values
    • ENStatus_Success: The URL and content-type were retrieved.
    • ENStatus_Failure: An error was encountered while retrieving the URL and/or content-type.

 

ENStatus
ENATSC3ROUTESessionGetEntityModeObjectURLAndContentType(
    ENATSC3ROUTESessionHandle_t hROUTESession, 
    uint32_t tsi,
    const uint8_t *pPayload, 
    int32_t payloadLength, 
    int32_t *pPayloadOffset,
    char *pURL, 
    int32_t sURL, 
    char *pContentType, 
    int32_t sContentType);
);

ENATSC3ROUTESessionGetEntityModeObjectURLAndContentType obtains the URL and content-type associated with the entity format object in pPayload and received on the LCT channel with the indicated TSI. It processes the headers at the beginning of pPaand returns an offset to where the file payload begins in pPayloadOffset.

Parameters
    • hROUTESession: A handle to the ROUTE session processor on which to operate.
    • tsi: The TSI of the LCT channel delivering the object.
    • pPayload: The object as delivered on the LCT channel.
    • payloadLength: The size in bytes of the object.
    • pPayloadOffset: On return, the offset into pPayload where the file  payload begins.
    • pURL: Pointer to a buffer where the zero-terminated URL will be stored.
    • sURL: The size of the buffer pointed to by pURL.
    • pContentType: Pointer to a buffer where the zero-terminated content-type will be stored.
    • sContentType: The size of the buffer pointed to by pContentType.
Return Values
    • ENStatus_Success: The URL and content-type were retrieved.
    • ENStatus_Failure: An error was encountered while retrieving the URL and/or content-type.

 

ENStatus ENATSC3ROUTESessionProcessUDPPacket(
    ENATSC3ROUTESessionHandle_t hROUTESession, 
    struct timespec *pPacketTimeUTC,
    uint64_t packetNumber, 
    uint8_t plpId, 
    const uint8_t *pPayload,
    int32_t payloadLength
);

ENATSC3ROUTESessionProcessUDPPacket provides a UDP packet to the ROUTE session processor. The UDP packet’s payload is not assumed to be available once ENATSC3ROUTESessionProcessUDPPacket returns.

Parameters
    • hROUTESession: A handle to the ROUTE session processor receiving the UDP packet.
    • pPacketTimeUTC: The time at which the UDP 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 UDP packet. The packet number is not used by the Base Stack libraries but is passed throughout the stack for use by the application.
    • plpId: The PLP on which the UDP packet originated.
    • pPayload: The UDP packet.
    • payloadLength: The number of bytes referenced by pPayload.
Return Values
    • ENStatus_Success: The UDP packet was accepted by the processor.
    • ENStatus_Failure: The packet was rejected by the processor.