libenatsc3mmt

libenatsc3mmtp implements  an MMTP processor which accepts UDP packets and obtains signaling and media objects from an MMTP session .

Usage

    • Applications instantiate an MMTP processor via ENATSC3MMTPSessionAllocate.
    • Applications use ENATSC3MMTPSessionRegisterCallbacks to register callback functions that are called when MMTP signaling or media data  are available.
    • As UDP packets are received the application calls ENATSC3MMTPSessionProcessUDPPacket to provide them to the processor. The processor calls the callback functions as signaling and media data become available.
    • When the application is done with the processor it is closed by ENATSC3MMTPSessionFree.

Types

typedef struct
{
    uint16_t packet_id;
    const char *pAssetId;
    uint8_t version;
    uint32_t length;
    uint16_t service_id;
    uint16_t content_type;
    uint8_t content_version;
    uint8_t content_compression;
    uint8_t uri_length;
    const uint8_t *pURI;
    uint32_t content_length;
} ENATSC3MMTPATSC3SignalingInfo;

ENATSC3MMTPATSC3SignalingInfo carries information extracted from an ATSC 3 signaling message (i.e. an MMTP signaling message with message_id 0x8100). See A/331 7.32.1 “MMTP-Specific Signaling Message” for a definition of the structure members.

Callback Functions

typedef void (*ENATSC3MMTPUSBDAvailableCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPATSC3SignalingInfo *pSignalingInfo, 
    const char *pUSBD,
    int32_t sUSBD, 
    int32_t version, 
    void *pUserData
);

ENATSC3MMTPUSBDAvailableCallback is called when a USBD document is available.

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered the document.
    • pUSBD: 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.
    • sUSBD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the atsc3_message_content_version of the MMTP-specific signaling message.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPHELDAvailableCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPATSC3SignalingInfo *pSignalingInfo, 
    const char *pHELD,
    int32_t sHELD, 
    int32_t version, 
    void *pUserData
);

ENATSC3MMTPHELDAvailableCallback is called when a HELD document is available.

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered 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 atsc3_message_content_version of the MMTP-specific signaling message.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPVSPDAvailableCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPATSC3SignalingInfo *pSignalingInfo, 
    const uint8_t *pVSPD,
    int32_t sVSPD, 
    int32_t version, 
    void *pUserData
);

ENATSC3MMTPVSPDAvailableCallback is called when an VSPD document is available.

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered the document.
    • pVSPD: 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.
    • sVSPD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the atsc3_message_content_version of the MMTP-specific signaling message.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPASPDAvailableCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPATSC3SignalingInfo *pSignalingInfo, 
    const uint8_t *pASPD,
    int32_t sASPD, 
    int32_t version, 
    void *pUserData
);

ENATSC3MMTPASPDAvailableCallback is called when an ASPD document is available.

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered the document.
    • pASPD: 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.
    • sASPD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the atsc3_message_content_version of the MMTP-specific signaling message.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPCADAvailableCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPATSC3SignalingInfo *pSignalingInfo, 
    const uint8_t *pCAD,
    int32_t sCAD, 
    int32_t version, 
    void *pUserData
);

ENATSC3MMTPCADAvailableCallback is called when a CAD document is available.

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered the document.
    • pCAD: 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.
    • sCAD: The number of bytes referenced by pDocument.
    • version: The document version as indicated by the atsc3_message_content_version of the MMTP-specific signaling message.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPMPTSignalingMessageCallback)(
    struct timespec *pPacketTimeUTC,
    const ENATSC3MMTPMPTSignalingInfo *pSignalingInfo, 
    void *pUserData
);

ENATSC3MMTPMPTSignalingMessageCallback is called when an MTP signaling message is  received (i.e. an MMTP signaling message with message_id between 0x11 and 0x20).

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.
    • pSignalingInfo:  Information extracted from the MMTP-specific signaling message that delivered the document.
    • pUserData: Application data provided when the callback was registered.
typedef void (*ENATSC3MMTPMediaDataCallback)(
    struct timespec *pPacketTimeUTC,
    int32_t packet_id, 
    const char *pAssetId, 
    int32_t fragment_type,
    uint32_t sequence_number, 
    uint64_t mpuPresentationTime, 
    uint32_t mpuDuration,
    uint64_t timeScale, 
    const uint8_t *pData, 
    int32_t sData, 
    void *pUserData
);

ENATSC3MMTPMediaDataCallback is called when media data is available.

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.
    • packet_id:  The packet_id as obtained from the MMTP protocol packet containing the media data.
    • pAssetId:The asset ID asociated with the media data as obtained from the most recent MMPU box.
    • fragment_type: The fragment type as obtained from the MMTP payload header of the packet carrying the data delivered in this callback. It may be one of  MPU metadata (0), movie fragment metdata (1), or MFU (2).
    • sequence_number: The sequence_number as obtained from the MMTP protocol packet containing the media data.
    • mpuPresentationTime: The presentation time associated with the first access unit of the MPU for which data is being delivered.
    • mpuDuration: The duration of the MPU for which data is being delivered.
    • timeScale: The time scale in fractions of a second used with mpuPresentationTime and mpuDuration (e.g. the MPU duration in seconds is mpuDuration / timeScale).
    • pData: A pointer to the media data.
    • sData: The number of bytes referenced by pData.
    • pUserData: Application data provided when the callback was registered.
typedef void (*MMTPIPAddressAddCallback)(
    uint32_t addr, 
    uint16_t port,
    void *pUserData
);

MMTPIPAddressAddCallback is called when the MMTP processor requires data delivered on an IP address and port. The application should alter an IP filtering to allow the requested packets through.

Parameters
    • addr: The IPv4 address requested.
    • port: the port requested.
typedef void (*MMTPIPAddressRemoveCallback)(
    uint32_t addr, 
    uint16_t port,
    void *pUserData
);

MMTPIPAddressRemoveCallback is called when the MMTP processor no longer requires data delivered on an IP address and port. The application may filter packtes on the address/port.

Parameters
    • addr: The IPv4 address no longer required.
    • port: the port no longer required.

Function Reference

ENStatus ENATSC3MMTPSessionAllocate(
    uint32_t addr, 
    uint16_t port,
    MMTPIPAddressAddCallback IPAddressAddCallback,
    MMTPIPAddressRemoveCallback IPAddressRemoveCallback,
    void *pIPAddrCallbackUserData, 
    char *pDebugName,
    MMTPSessionHandle_t *phMMTPSession
);

ENATSC3MMTPSessionAllocate allocates an MMTP processor which will begin listening for MMTP data on the indicated address and port.

Parameters
    • addr: The IPv4 address on which the processor should listen.
    • port: The port on which the processor should listen.
    • 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.
    • pIPAddrCallbackUserData: An application-supplied  pointer passed to the callback functions.
    • pDebugName: A string identifying this MMTP processor during debug logging.
    • phMMTPSession: On successful return contains a handle to the MMTP processor.
Return Values
    • ENStatus_Success: An MMTP processor was allocated and a handle to the processor is returned in *phMMTPSession. The processor must be freed with ENATSC3MMTPSessionFree when the application no longer requires the processor.
    • ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phMMTPSession is undefined.
ENStatus ENATSC3MMTPSessionFree(
    MMTPSessionHandle_t hMMTPSession
);

ENATSC3MMTPSessionFree frees an MMTP processor allocated with ENATSC3MMTPSessionAllocate.

Parameters
    • hMMTPSession: A handle to the MMTP processor to free.
Return Values
    • ENStatus_Success: The processor was closed.
    • ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3MMTPSessionRegisterCallbacks(
    MMTPSessionHandle_t hMMTPSession,
    ENATSC3MMTPUSBDAvailableCallback USBDAvailableCallback,
    ENATSC3MMTPHELDAvailableCallback HELDAvailableCallback,
    ENATSC3MMTPVSPDAvailableCallback VSPDAvailableCallback,
    ENATSC3MMTPASPDAvailableCallback ASPDAvailableCallback,
    ENATSC3MMTPCADAvailableCallback CADAvailableCallback,
    ENATSC3MMTPMPTSignalingMessageCallback MPTSignalingMessageCallback,
    ENATSC3MMTPMediaDataCallback MediaDataCallback,
    void *pUserData
);

ENATSC3MMTPSessionRegisterCallbacks registers functions to be called as MMTP signaling or media data becomes available.

Parameters
    • hMMTPSession: A handle to the MMTP processor on which to register the callbacks.
    • USBDAvailableCallback: Called when USBD signaling is received.
    • HELDAvailableCallback: Called when HELD signaling is received.
    • VSPDAvailableCallback: Called when VSPD signaling is received.
    • ASPDAvailableCallback: Called when ASPD signaling is received.
    • CADAvailableCallback: Called when CAD signaling is received.
    • MPTSignalingMessageCallback: Called when MPT signaling is received.
    • 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 ENATSC3MMTPSessionUnregisterCallbacks(
    MMTPSessionHandle_t hMMTPSession,
    ENATSC3MMTPUSBDAvailableCallback USBDAvailableCallback,
    ENATSC3MMTPHELDAvailableCallback HELDAvailableCallback,
    ENATSC3MMTPVSPDAvailableCallback VSPDAvailableCallback,
    ENATSC3MMTPASPDAvailableCallback ASPDAvailableCallback,
    ENATSC3MMTPCADAvailableCallback CADAvailableCallback,
    ENATSC3MMTPMPTSignalingMessageCallback MPTSignalingMessageCallback,
    ENATSC3MMTPMediaDataCallback MediaDataCallback,
    void *pUserData
);

ENATSC3MMTPSessionUnregisterCallbacks unregisters callbacks previously set with ENATSC3MMTPSessionRegisterCallbacks. Note that both ENATSC3MMTPSessionRegisterCallbacks and ENATSC3MMTPSessionUnregisterCallbacks treat the provided function pointers and user data pointer as a set. The sets used to unregister callbacks must match the set used to register callbacks.

Parameters
    • hMMTPSession: A handle to the MMTP processor on which to unregister the callbacks.
    • USBDAvailableCallback: The USBD callback to unregister.
    • HELDAvailableCallback: The HELD callback to unregister.
    • VSPDAvailableCallback: The VSPD callback to unregister.
    • ASPDAvailableCallback: The ASPD callback to unregister.
    • CADAvailableCallback: The CAD callback to unregister.
    • MPTSignalingMessageCallback: The MPT signaling callback to unregister.
    • pUserData: The user data pointer to unregister.
Return Values
    • ENStatus_Success: The callbacks were unregistered.
    • ENStatus_Failure: An error was encountered while unregistering the callbacks. This may occur if the set of callback functions and the userdata pointer does not match a set previously registered with ENATSC3MMTPSessionRegisterCallbacks .
ENARTSC3Status ENATSC3MMTPSessionProcessUDPPacket(
    MMTPSessionHandle_t hMMTPSession,
    struct timespec *pPacketTime, 
    uint64_t packetNumber,
    const uint8_t *pPayload, 
    int32_t payloadLength
);

Applications call ENATSC3MMTPSessionProcessUDPPacket to provide UDP packets to the MMTP processor. The UDP packet is not  assumed to be valid once ENATSC3MMTPSessionProcessUDPPacket returns.

Parameters
    • hMMTPSession: A handle to the MMTP processor on which to submit the UDP paclet.
    • pPacketTime: The time stamp associated with the first baseband packet delivering data associated with the UDP packet.
    • packetNumber: The packet number associated with the first baseband packet delivering data associated with the UDP packet.
    • pPayload: The UDP packet.
    • payloadLength: The length in bytes of the UEP packet.
Return Values
    • ENStatus_Success: The packet was accepted..
    • ENStatus_Failure: An error was encountered while procssing the UDP packet.