libenatsc3dashfeeder

• ATSC 3.0 Base Stack
  • License
  • Building
  • Releases
  • Documentation
    • libentsc3baseband
    • libenatsc3j288alp
    • libenatsc3ssp
    • libenatsc3alp
    • libenatsc3ipv4
    • libenatsc3route
    • libenatsc3dashfeeder
    • libenatsc3mmt
    • libenatsc3esg
    • libenatsc3lls
    • libenatsc3sls
    • EnXML

libentasc3dashfeeder implements an ATSC 3.0 DASH feeder. It uses an application-provided ROUTE processor to receive media objects via the ROUTE session’s LCT channels and presents those objects to the application.

Callbacks are provided to notify the application when a media file is started, has completed, and when additional data for a media file is available. Applications are also given the option of rejecting a media object and are notified if a media object is aborted by the DASH processor.

The DASH feeder is intended to be paired with a DASH consumer in the application, which makes use of the media objects presented by the DASH feeder.

Usage

• • Applications obtain a DASH feeder via ENATSC3FDASHFeederAllocate.
  • Applications use ENATSC3DASHFeederRegisterCallbacks to register callback function to be called when  events occur.
  • When the application is done with the processor it is released via ENATSC3DASHFeederFree.

Callback Functions

typedef ENStatus (*ENATSC3DASHFeederMediaFileBeginCallback)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    uint32_t tsi, 
    uint32_t toi,
    uint8_t codepoint, 
    const char *pId, 
    ENATSC3ROUTESessionIdType idType,
    const char *pURL, 
    const uint8_t *pPayload, 
    int32_t payloadLength,
    int32_t fError,
    void *pUserData
);

ENATSC3DASHFeederMediaFileBeginCallback is called by the DASH feeder when starting a new media file. The portion of the media file available is provided with the callback. Note that there is no guarantee on how much of the media is provided.

The application can reject the file by returning a status other than ENASC3Status_Success. No additional callbacks occur for a rejected file.

Parameters

• • pPacketTimeUTC: The timestamp of the baseband packet from which the file was received. If the file spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the file.
  • packetNumber: The baseband packet number from which the file was received. If the file spans baseband packets then the packet number is obtained from the first baseband packet containing a portion of the file.
  • tsi: The tsi of the LCT channel on which the file is received.
  • toi: The toi of the file as obtained from the LCT building block.
  • codepoint: The codepoint of the file as obtained from the LCT building block.
  • pId: A string identifer used for mapping the LCT channel delivering the file to a DASH representation. See idType..
  • idType: The type of identifier pointed to by pId. Normally idType is ENATSC3RouteSessionIdType_RepId and pId is a DASH representation Id as specified in the STSID for the LCT channel. However in the event that the representation Id is not provided in the STSID then idType is set to ENATSC3RouteSessionIdType_Segment0URL and pId contains the URL of segment 0 as derived from the segment template.
  • pURL: The URL of the file.
  • pPayload: Any payload for the file that has been received is pointed to by pPayload.
  • payloadLength: The number of bytes pointed to by pPayload.
  • .fError: non-zero if the data pointed to by pPayload contains errors, for example due to reception errors. A value of zero is not a guarantee that the data is error-free, but indicates that it is not known to contain errors.
  • pUserData: Application data provided when the callback was registered.

typedef void (*ENATSC3DASHFeederMediaFileEndCallback)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t tsi,
    uint32_t toi,
    const char *pURL, 
    int64_t objectSize, 
    int64_t objectPosition, 
    void *pUserData
);

ENATSC3DASHFeederMediaFileEndCallback is called by the DASH feeder to signal that all data has been received for the file..

Parameters

• • pPacketTimeUTC: The timestamp of the baseband packet from which the file was received. If the file spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the file.
  • packetNumber: The baseband packet number from which the file was received. If the file spans baseband packets then the packet number is obtained from the first baseband packet containing a portion of the file.
  • tsi: The tsi of the LCT channel on which the file is received.
  • toi: The toi of the file as obtained from the LCT building block.
  • pURL: The URL of the file.
  • objectSize: The expected length of the file in bytes. objectSize may be -1 if it has not yet been signaled.
  • objectPosition: The position up to which data has been processed. If pos < objectSize then the file was partially received.
  • pUserData: Application data provided when the callback was registered.

typedef void (*ENATSC3DASHFeederMediaFileDataCallback)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t tsi,
    uint32_t toi,
    const char *pURL, 
    const uint8_t *pPayload, 
    int32_t payloadLength, 
    int64_t objectPosition, 
    int64_t objectSize, 
    int32_t fError, 
    void *pUserData);

ENATSC3DASHFeederMediaFileDataCallback is called by the DASH feeder to deliver a file contents to the application.

Parameters

• • pPacketTimeUTC: The timestamp of the baseband packet from which the file was received. If the file spans baseband packets then the timestamp is obtained from the first baseband packet containing a portion of the file.
  • packetNumber: The baseband packet number from which the file was received. If the file spans baseband packets then the packet number is obtained from the first baseband packet containing a portion of the file.
  • tsi: The tsi of the LCT channel on which the file is received.
  • toi: The toi of the file as obtained from the LCT building block.
  • pURL: The URL of the file.
  • pPayload: The portion of the file delivered in this callback.
  • payloadLength: The number of bytes pointed to by pPayload.
  • objectPosition: The position within the file that the data pointed to by pPayload corresponds to.
  • objectSize: The expected length of the file in bytes. objectSize may be -1 if it has not yet been signaled.
  • .fError: non-zero if the data pointed to by pPayload contains errors, for example due to reception errors. A value of zero is not a guarantee that the data is error-free, but indicates that it is not known to contain errors.
  • pUserData: Application data provided when the callback was registered.

typedef void (*ENATSC3DASHFeederMediaFileAbortCallback)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t tsi,
    uint32_t toi, 
    const char *pURL, 
    int64_t objectSize, 
    int64_t objectPosition, 
    void *pUserData);

ENATSC3DASHFeederMediaFileAbortCallback is called by the DASH feeder to indicate that receipt of a file is being aborted.

Parameters

• • pPacketTimeUTC: The timestamp of the baseband packet being processed at the time the file was aborted.
  • packetNumber: The baseband packet number of the baseband packet being proessed at the time the file was aborted.
  • tsi: The tsi of the LCT channel on which the file is received.
  • toi: The toi of the file as obtained from the LCT building block.
  • pURL: The URL of the file.
  • pPayload: The portion of the file delivered in this callback.
  • objectSize: The expected length of the file in bytes. objectSize may be -1 if it has not yet been signaled.
  • objectPosition: The position within the file that the data pointed to by pPayload corresponds to.
  • pUserData: Application data provided when the callback was registered.

typedef void (*ENATSC3DASHFeederLCTChannelRemovedCallback)(
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber, 
    uint32_t tsi, 
    void *pUserData
);

ENATSC3DASHFeederLCTChannelRemovedCallback is called to notify the application that the LCT channel with the specified tsi has been removed. Any future objects received on an LCT channel with the tsi means that the LCT channel was re-opened and is not related to the LCT channel being removed.

Parameters

• • pPacketTimeUTC: The timestamp of the baseband packet being processed at the time the LCT channel was removed.
  • packetNumber: The baseband packet number being processed at the time the LCT channel was removed.
  • tsi: The tsi of the LCT channel which was removed.
  • pUserData: Application data provided when the callback was registered.

Function Reference

ENStatus ENATSC3DASHFeederAllocate(
    ENATSC3ROUTESessionHandle_t hROUTESession, 
    const char *pDebugName,
    ENATSC3DASHFeederHandle_t *phENATSC3DASHFeeder
);

ENATSC3DASHFeederAllocate allocates a DASH feeder using the provided ROUTE session to receive data.

Parameters

• • hROUTESession: A handle to a ROUTE session that the DASH feeder uses to receive data. The application sets up this ROUTE session to receive data from the desired service. The DASH feeder registers callbacks to receive objects from the ROUTE session.’
  • pDebugName: A string used for debug logging.
  • phENATSC3DASHFeeder: On success phENATSC3DASHFeeder contains a handle to the DASH feeder. Its contents are undefined in the case of failure.

Return Values

• • ENStatus_Success: A DASH feeder was instantiated and a handle to the feeder is returned in *phENATSC3DASHFeeder. The feeder must be released with ENATSC3DASHFeederFree when the application no longer requires the feeder.
  • ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phENATSC3DASHFeeder is undefined.

ENStatus ENATSC3DASHFeederFree(
    ENATSC3DASHFeederHandle_t hENATSC3DASHFeeder
);

ENATSC3DASHFeederFree releases a DASH Feeder obtained with ENATSC3DASHFeederAllocate.

Parameters

• • hENATSC3DASHFeeder: A handle to the DASH feeder to free.

Return Values

• • ENStatus_Success: The feeder was freed.
  • ENStatus_Failure: An error was encountered while freeing the feeder.

ENStatus ENATSC3DASHFeederRegisterCallbacks(
    ENATSC3DASHFeederHandle_t hENATSC3DASHFeeder,
    ENATSC3DASHFeederMediaFileBeginCallback MediaFileBeginCallback,
    ENATSC3DASHFeederMediaFileEndCallback MediaFileEndCallback,
    ENATSC3DASHFeederMediaFileAbortCallback MediaFileAbortCallback,
    ENATSC3DASHFeederMediaFileDataCallback MediaFileDataCallback,
    ENATSC3DASHFeederLCTChannelRemovedCallback LCTChannelRemovedCallback,
    void *pCallbackUserData
);

ENATSC3DASHFeederRegisterCallbacks registers functions to be called on DASH feeder events.

Parameters

• • hSession: A handle to the DASH feeder on which to register the callbacks.
  • MediaFileBeginCallback: Called when the feeder begins processing a media file.
  • MediaFileEndCallback: Called when the feeder has completed reception of a media file.
  • MediaFileAbortCallback: Called when reception of a media file is being aborted
  • .MediaFileDataCallback: Called when data arrives for a media file.
  • LCTChannelRemovedCallback: 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 ENATSC3DASHFeederSetVerbosity(
    ENATSC3DASHFeederHandle_t hENATSC3DASHFeeder, 
    ENVerbosity verbosity
);

ENATSC3ESGSessionSetVerbosity specifies the logging verbosity for the DASH feeder.

Parameters

• • hSession: A handle to the DASH feeder 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.