ROUTE ATSC 3.0 receiver. More...

Collaboration diagram for ROUTE:

Data Structures
struct	GF_LCTFragInfo

struct	GF_ROUTEEventFileInfo

Macros
#define	GF_ATSC_MCAST_ADDR "224.0.23.60"

#define	GF_ATSC_MCAST_PORT 4937

Typedefs
typedef struct __gf_routedmx	GF_ROUTEDmx

Enumerations
enum	GF_ROUTEEventType { GF_ROUTE_EVT_SERVICE_FOUND = 0 , GF_ROUTE_EVT_SERVICE_SCAN , GF_ROUTE_EVT_MPD , GF_ROUTE_EVT_HLS_VARIANT , GF_ROUTE_EVT_FILE , GF_ROUTE_EVT_DYN_SEG , GF_ROUTE_EVT_DYN_SEG_FRAG , GF_ROUTE_EVT_FILE_DELETE , GF_ROUTE_EVT_LATE_DATA }

enum	{ GF_LCT_EXT_NOP = 0 , GF_LCT_EXT_AUTH = 1 , GF_LCT_EXT_TIME = 2 , GF_LCT_EXT_FTI = 64 , GF_LCT_EXT_FDT = 192 , GF_LCT_EXT_CENC = 193 , GF_LCT_EXT_TOL24 = 194 , GF_LCT_EXT_TOL48 = 67 }

enum	GF_LCTObjectPartial { GF_LCTO_PARTIAL_NONE =0 , GF_LCTO_PARTIAL_BEGIN , GF_LCTO_PARTIAL_ANY }

enum	GF_RouteProgressiveDispatch { GF_ROUTE_DISPATCH_FULL = 0 , GF_ROUTE_DISPATCH_PROGRESSIVE , GF_ROUTE_DISPATCH_OUT_OF_ORDER }

Functions
GF_ROUTEDmx *	gf_route_atsc_dmx_new (const char ifce, u32 sock_buffer_size, void(on_event)(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo finfo), void *udta)

GF_ROUTEDmx *	gf_route_atsc_dmx_new_ex (const char ifce, u32 sock_buffer_size, const char netcap_id, void(on_event)(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo finfo), void udta)

GF_ROUTEDmx *	gf_route_dmx_new (const char ip, u32 port, const char ifce, u32 sock_buffer_size, void(on_event)(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo finfo), void udta)

GF_ROUTEDmx *	gf_route_dmx_new_ex (const char ip, u32 port, const char ifce, u32 sock_buffer_size, const char netcap_id, void(on_event)(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo finfo), void *udta)

GF_ROUTEDmx *	gf_dvb_mabr_dmx_new (const char ip, u32 port, const char ifce, u32 sock_buffer_size, const char netcap_id, void(on_event)(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo finfo), void *udta)

void	gf_route_dmx_del (GF_ROUTEDmx *routedmx)

GF_Err	gf_route_dmx_process (GF_ROUTEDmx *routedmx)

GF_Err	gf_route_dmx_set_reorder (GF_ROUTEDmx *routedmx, Bool reorder_needed, u32 timeout_us)

GF_Err	gf_route_set_dispatch_mode (GF_ROUTEDmx *routedmx, GF_RouteProgressiveDispatch dispatch_mode)

GF_Err	gf_route_atsc3_tune_in (GF_ROUTEDmx *routedmx, u32 service_id, Bool tune_others)

u32	gf_route_dmx_get_object_count (GF_ROUTEDmx *routedmx, u32 service_id)

GF_Err	gf_route_dmx_remove_object_by_name (GF_ROUTEDmx routedmx, u32 service_id, char fileName, Bool purge_previous)

GF_Err	gf_route_dmx_force_keep_object_by_name (GF_ROUTEDmx routedmx, u32 service_id, char fileName)

Bool	gf_route_dmx_remove_first_object (GF_ROUTEDmx *routedmx, u32 service_id)

Bool	gf_route_dmx_find_atsc3_service (GF_ROUTEDmx *routedmx, u32 service_id)

void	gf_route_dmx_purge_objects (GF_ROUTEDmx *routedmx, u32 service_id)

u64	gf_route_dmx_get_first_packet_time (GF_ROUTEDmx *routedmx)

u64	gf_route_dmx_get_last_packet_time (GF_ROUTEDmx *routedmx)

u64	gf_route_dmx_get_nb_packets (GF_ROUTEDmx *routedmx)

u64	gf_route_dmx_get_recv_bytes (GF_ROUTEDmx *routedmx)

void	gf_route_dmx_debug_tsi (GF_ROUTEDmx *routedmx, u32 tsi)

void	gf_route_dmx_set_service_udta (GF_ROUTEDmx routedmx, u32 service_id, void udta)

void *	gf_route_dmx_get_service_udta (GF_ROUTEDmx *routedmx, u32 service_id)

GF_Err	gf_route_dmx_patch_frag_info (GF_ROUTEDmx routedmx, u32 service_id, GF_ROUTEEventFileInfo finfo, u32 br_start, u32 br_end)

GF_Err	gf_route_dmx_mark_active_quality (GF_ROUTEDmx routedmx, u32 service_id, const char period_id, s32 as_id, const char *rep_id, Bool is_selected)

void	gf_route_dmx_reset_all (GF_ROUTEDmx *routedmx)

Detailed Description

The ROUTE receiver implements part of the ATSC 3.0 specification, mostly low-level signaling and ROUTE reception. It gathers objects from a ROUTE session and sends them back to the user through a callback, or deletes them if no callback is sent. The route demuxer does not try to repairing files, it is the user responsibility to do so.

Data Structure Documentation

◆ GF_LCTFragInfo

struct GF_LCTFragInfo

LCT fragment information

Data Fields
u32	offset	offset in bytes of fragment in object / file
u32	size	size in bytes of fragment in object / file

◆ GF_ROUTEEventFileInfo

struct GF_ROUTEEventFileInfo

Structure used to communicate file objects properties to the user

Collaboration diagram for GF_ROUTEEventFileInfo:

Data Fields
const char *	filename	original file name
const char *	mime	mime type if known, NULL otherwise
GF_Blob *	blob	blob data pointer - the route user is responsible for setting the blob flags if desired
u32	total_size	total size of object if known, 0 otherwise
u32	tsi	object TSI
u32	toi	object TOI
u32	download_ms	download time in ms
Bool	updated	flag set if file content has been modified - not set for GF_ROUTE_EVT_DYN_SEG (always true)
Bool	first_toi_received	flag set if first segment has been received for the given TSI - not set for init segments
u32	nb_frags	number of fragments, only set for GF_ROUTE_EVT_DYN_SEG
GF_LCTFragInfo *	frags	fragment info, set for all file events - this info is shared with the LCT object being reassembled and should not be modified concurrently from route demux Any reallocation of the fragment info SHALL be done using gf_route_dmx_patch_frag_info
u32	late_fragment_offset	offset of late received data, only for GF_ROUTE_EVT_LATE_DATA
GF_LCTObjectPartial	partial
void *	udta	user data set to current object after callback, and passed back on next callbacks on same object Only used for GF_ROUTE_EVT_FILE, GF_ROUTE_EVT_DYN_SEG, GF_ROUTE_EVT_DYN_SEG_FRAG and GF_ROUTE_EVT_FILE_DELETE

Macro Definition Documentation

◆ GF_ATSC_MCAST_ADDR

#define GF_ATSC_MCAST_ADDR "224.0.23.60"

ATSC3.0 bootstrap address for LLS

◆ GF_ATSC_MCAST_PORT

#define GF_ATSC_MCAST_PORT 4937

ATSC3.0 bootstrap port for LLS

Typedef Documentation

◆ GF_ROUTEDmx

typedef struct __gf_routedmx GF_ROUTEDmx

The GF_ROUTEDmx object.

Enumeration Type Documentation

◆ GF_ROUTEEventType

enum GF_ROUTEEventType

The types of events used to communicate withe the demuxer user.

Enumerator
GF_ROUTE_EVT_SERVICE_FOUND	A new service is detected, service ID is in evt_param, no file info
GF_ROUTE_EVT_SERVICE_SCAN	Service scan completed, no evt_param, no file info
GF_ROUTE_EVT_MPD	New MPD or HLS master playlist available for service, service ID is in evt_param, file info carries manifest info
GF_ROUTE_EVT_HLS_VARIANT	HLS variant update for service, service ID is in evt_param, file info carries variant info
GF_ROUTE_EVT_FILE	static file update (with predefined TOI), service ID is in evt_param
GF_ROUTE_EVT_DYN_SEG	Segment reception, identified through a file template, service ID is in evt_param
GF_ROUTE_EVT_DYN_SEG_FRAG	fragment reception (part of a segment), identified through a file template, service ID is in evt_param Note The data always begins at the start of the object
GF_ROUTE_EVT_FILE_DELETE	Object deletion (only for dynamic TOIs), used to notify the cache that an object is no longer available. File info only contains the filename being removed
GF_ROUTE_EVT_LATE_DATA	Delayed data reception

◆ GF_LCTObjectPartial

enum GF_LCTObjectPartial

Type of partial event

◆ GF_RouteProgressiveDispatch

enum GF_RouteProgressiveDispatch

Progressive dispatch mode for LCT objects

Enumerator
GF_ROUTE_DISPATCH_FULL	notification is only sent once the entire object is received
GF_ROUTE_DISPATCH_PROGRESSIVE	notifications are sent whenever the first byte-range starting at 0 changes, in which case the partial field is set to GF_LCTO_PARTIAL_BEGIN
GF_ROUTE_DISPATCH_OUT_OF_ORDER	notifications are sent whenever a new packet is received, in which case the partial field is set to GF_LCTO_PARTIAL_ANY

Function Documentation

◆ gf_route_atsc_dmx_new()

GF_ROUTEDmx* gf_route_atsc_dmx_new	(	const char *	ifce,
		u32	sock_buffer_size,
		void()(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo *finfo)	on_event,
		void *	udta
	)

Creates a new ROUTE ATSC3.0 demultiplexer

Parameters

ifce	network interface to monitor, NULL for INADDR_ANY
sock_buffer_size	default buffer size for the udp sockets. If 0, uses 0x2000
on_event	the user callback function
udta	the user data passed back by the callback

Returns: the ROUTE demultiplexer created

◆ gf_route_atsc_dmx_new_ex()

GF_ROUTEDmx* gf_route_atsc_dmx_new_ex	(	const char *	ifce,
		u32	sock_buffer_size,
		const char *	netcap_id,
		void()(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo *finfo)	on_event,
		void *	udta
	)

Creates a new ROUTE ATSC3.0 demultiplexer

Parameters

ifce	network interface to monitor, NULL for INADDR_ANY
sock_buffer_size	default buffer size for the udp sockets. If 0, uses 0x2000
netcap_id	ID of netcap configuration to use, may be null (see gpac -h netcap)
on_event	the user callback function
udta	the user data passed back by the callback

Returns: the ROUTE demultiplexer created

◆ gf_route_dmx_new()

GF_ROUTEDmx* gf_route_dmx_new	(	const char *	ip,
		u32	port,
		const char *	ifce,
		u32	sock_buffer_size,
		void()(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo *finfo)	on_event,
		void *	udta
	)

Creates a new ROUTE demultiplexer

Parameters

ip	IP address of ROUTE session
port	port of ROUTE session
ifce	network interface to monitor, NULL for INADDR_ANY
sock_buffer_size	default buffer size for the udp sockets. If 0, uses 0x2000
on_event	the user callback function
udta	the user data passed back by the callback

Returns: the ROUTE demultiplexer created

◆ gf_route_dmx_new_ex()

GF_ROUTEDmx* gf_route_dmx_new_ex	(	const char *	ip,
		u32	port,
		const char *	ifce,
		u32	sock_buffer_size,
		const char *	netcap_id,
		void()(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo *finfo)	on_event,
		void *	udta
	)

Creates a new ROUTE demultiplexer

Parameters

ip	IP address of ROUTE session
port	port of ROUTE session
ifce	network interface to monitor, NULL for INADDR_ANY
sock_buffer_size	default buffer size for the udp sockets. If 0, uses 0x2000
netcap_id	ID of netcap configuration to use, may be null (see gpac -h netcap)
on_event	the user callback function
udta	the user data passed back by the callback

Returns: the ROUTE demultiplexer created

◆ gf_dvb_mabr_dmx_new()

GF_ROUTEDmx* gf_dvb_mabr_dmx_new	(	const char *	ip,
		u32	port,
		const char *	ifce,
		u32	sock_buffer_size,
		const char *	netcap_id,
		void()(void udta, GF_ROUTEEventType evt, u32 evt_param, GF_ROUTEEventFileInfo *finfo)	on_event,
		void *	udta
	)

Creates a new DVB MABR Flute demultiplexer

Parameters

ip	IP address of LCT session carrying the initial FDT
port	port of LCT session carrying the initial FDT
ifce	network interface to monitor, NULL for INADDR_ANY
sock_buffer_size	default buffer size for the udp sockets. If 0, uses 0x2000
netcap_id	ID of netcap configuration to use, may be null (see gpac -h netcap)
on_event	the user callback function
udta	the user data passed back by the callback

Returns: the demultiplexer created

◆ gf_route_dmx_del()

void gf_route_dmx_del ( GF_ROUTEDmx * routedmx )

Deletes an ROUTE demultiplexer

Parameters

routedmx the ROUTE demultiplexer to delete

◆ gf_route_dmx_process()

GF_Err gf_route_dmx_process ( GF_ROUTEDmx * routedmx )

Processes demultiplexing, returns when nothing to read

Parameters

routedmx the ROUTE demultiplexer

Returns: error code if any, GF_IP_NETWORK_EMPTY if nothing was read

◆ gf_route_dmx_set_reorder()

GF_Err gf_route_dmx_set_reorder	(	GF_ROUTEDmx *	routedmx,
		Bool	reorder_needed,
		u32	timeout_us
	)

Sets reordering on.

Parameters

routedmx	the ROUTE demultiplexer
reorder_needed	if TRUE, the order flag in ROUTE/LCT is ignored and objects are gathered for the given time. Otherwise, if order flag is set in ROUTE/LCT, an object is considered done as soon as a new object starts
timeout_us	maximum delay in microseconds to wait before considering the object is done when ROUTE/LCT order is not used. A value of 0 implies any out-of-order packet triggers a download completion (default value is 1 ms).

Returns: error code if any

◆ gf_route_set_dispatch_mode()

GF_Err gf_route_set_dispatch_mode	(	GF_ROUTEDmx *	routedmx,
		GF_RouteProgressiveDispatch	dispatch_mode
	)

Allow segments to be sent while being downloaded.

Note: Files with a static TOI association are always sent once completely received, other files using TOI templating may be sent while being received if enabled. The data sent is always contiguous data since the beginning of the file in that case.

Parameters

routedmx	the ROUTE demultiplexer
dispatch_mode	set dispatch mode

Returns: error code if any

◆ gf_route_atsc3_tune_in()

GF_Err gf_route_atsc3_tune_in	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		Bool	tune_others
	)

Sets the service ID to tune into for ATSC 3.0

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to tune in. 0 means no service, 0xFFFFFFFF means all services and 0xFFFFFFFE means first service found
tune_others	if set, will tune all non-selected services to get the MPD, but won't receive any media data

Returns: error code if any

◆ gf_route_dmx_get_object_count()

u32 gf_route_dmx_get_object_count	(	GF_ROUTEDmx *	routedmx,
		u32	service_id
	)

Gets the number of objects currently loaded in the service

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to query

Returns: number of objects in service

◆ gf_route_dmx_remove_object_by_name()

GF_Err gf_route_dmx_remove_object_by_name	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		char *	fileName,
		Bool	purge_previous
	)

Removes an object with a given filename

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to query
fileName	name of the file associated with the object
purge_previous	if set, indicates that all objects with the same TSI and a TOI less than TOI of the deleted object will be removed

Returns: error if any, GF_NOT_FOUND if no such object

◆ gf_route_dmx_force_keep_object_by_name()

GF_Err gf_route_dmx_force_keep_object_by_name	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		char *	fileName
	)

Flags an object to be kept until gf_route_dmx_remove_object_by_name is called

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to query
fileName	name of the file associated with the object

Returns: error if any, GF_NOT_FOUND if no such object

◆ gf_route_dmx_remove_first_object()

Bool gf_route_dmx_remove_first_object	(	GF_ROUTEDmx *	routedmx,
		u32	service_id
	)

Removes the first object loaded in the service

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to query

Returns: GF_TRUE if success, GF_FALSE if no object could be removed (the object is in download)

◆ gf_route_dmx_find_atsc3_service()

Bool gf_route_dmx_find_atsc3_service	(	GF_ROUTEDmx *	routedmx,
		u32	service_id
	)

Checks existence of a service for atsc 3.0

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to query

Returns: true if service is found, false otherwise

◆ gf_route_dmx_purge_objects()

void gf_route_dmx_purge_objects	(	GF_ROUTEDmx *	routedmx,
		u32	service_id
	)

Removes all non-signaling objects (ie TSI!=0), keeping only init segments and currently/last downloaded objects

Note: this is mostly useful in case of looping session, or at MPD switch boundaries

Parameters

routedmx	the ROUTE demultiplexer
service_id	ID of the service to cleanup

◆ gf_route_dmx_get_first_packet_time()

u64 gf_route_dmx_get_first_packet_time ( GF_ROUTEDmx * routedmx )

Gets high resolution system time clock of the first packet received

Parameters

routedmx the ROUTE demultiplexer

Returns: system clock in microseconds of first packet received

◆ gf_route_dmx_get_last_packet_time()

u64 gf_route_dmx_get_last_packet_time ( GF_ROUTEDmx * routedmx )

Gets high resolution system time clock of the last packet received

Parameters

routedmx the ROUTE demultiplexer

Returns: system clock in microseconds of last packet received

◆ gf_route_dmx_get_nb_packets()

u64 gf_route_dmx_get_nb_packets ( GF_ROUTEDmx * routedmx )

Gets the number of packets received since start of the session, for all active services

Parameters

routedmx the ROUTE demultiplexer

Returns: number of packets received

◆ gf_route_dmx_get_recv_bytes()

u64 gf_route_dmx_get_recv_bytes ( GF_ROUTEDmx * routedmx )

Gets the number of bytes received since start of the session, for all active services

Parameters

routedmx the ROUTE demultiplexer

Returns: number of bytes received

◆ gf_route_dmx_debug_tsi()

void gf_route_dmx_debug_tsi	(	GF_ROUTEDmx *	routedmx,
		u32	tsi
	)

Gather only objects with given TSI (for debug purposes)

Parameters

routedmx	the ROUTE demultiplexer
tsi	the target TSI, 0 for no filtering

◆ gf_route_dmx_set_service_udta()

void gf_route_dmx_set_service_udta	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		void *	udta
	)

Sets udta for given service id

Parameters

routedmx	the ROUTE demultiplexer
service_id	the target service
udta	the target user data

◆ gf_route_dmx_get_service_udta()

void* gf_route_dmx_get_service_udta	(	GF_ROUTEDmx *	routedmx,
		u32	service_id
	)

Gets udta for given service id

Parameters

routedmx	the ROUTE demultiplexer
service_id	the target service

Returns: the user data associated with the service

◆ gf_route_dmx_patch_frag_info()

GF_Err gf_route_dmx_patch_frag_info	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		GF_ROUTEEventFileInfo *	finfo,
		u32	br_start,
		u32	br_end
	)

Patch fragment info of object after a repair

Parameters

routedmx	the ROUTE demultiplexer
service_id	the target service
finfo	file info event as passed to the caller. Only tsi and toi info are used to loacate the object. The frags and nb_frags fileds are updated by this function
br_start	start offset of byte range being patched
br_end	end offset of byte range being patched

Returns: error if any

◆ gf_route_dmx_mark_active_quality()

GF_Err gf_route_dmx_mark_active_quality	(	GF_ROUTEDmx *	routedmx,
		u32	service_id,
		const char *	period_id,
		s32	as_id,
		const char *	rep_id,
		Bool	is_selected
	)

Set active status of a representation

Parameters

routedmx	the ROUTE demultiplexer
service_id	the target service
period_id	ID of the DASH period containing the representation, may be NULL
as_id	ID of the DASH adaptation set containing the representation, may be 0
rep_id	ID of the period containing the representation or HLS variant playlist URL, shall not be NULL
is_selected	representation status

Returns: error if any

◆ gf_route_dmx_reset_all()

void gf_route_dmx_reset_all ( GF_ROUTEDmx * routedmx )

Cancel all current transfer on all services

Parameters

routedmx the ROUTE demultiplexer

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ GF_LCTFragInfo

◆ GF_ROUTEEventFileInfo

Macro Definition Documentation

◆ GF_ATSC_MCAST_ADDR

◆ GF_ATSC_MCAST_PORT

Typedef Documentation

◆ GF_ROUTEDmx

Enumeration Type Documentation

◆ GF_ROUTEEventType

◆ GF_LCTObjectPartial

◆ GF_RouteProgressiveDispatch

Function Documentation

◆ gf_route_atsc_dmx_new()

◆ gf_route_atsc_dmx_new_ex()

◆ gf_route_dmx_new()

◆ gf_route_dmx_new_ex()

◆ gf_dvb_mabr_dmx_new()

◆ gf_route_dmx_del()

◆ gf_route_dmx_process()

◆ gf_route_dmx_set_reorder()

◆ gf_route_set_dispatch_mode()

◆ gf_route_atsc3_tune_in()

◆ gf_route_dmx_get_object_count()

◆ gf_route_dmx_remove_object_by_name()

◆ gf_route_dmx_force_keep_object_by_name()

◆ gf_route_dmx_remove_first_object()

◆ gf_route_dmx_find_atsc3_service()

◆ gf_route_dmx_purge_objects()

◆ gf_route_dmx_get_first_packet_time()

◆ gf_route_dmx_get_last_packet_time()

◆ gf_route_dmx_get_nb_packets()

◆ gf_route_dmx_get_recv_bytes()

◆ gf_route_dmx_debug_tsi()

◆ gf_route_dmx_set_service_udta()

◆ gf_route_dmx_get_service_udta()

◆ gf_route_dmx_patch_frag_info()

◆ gf_route_dmx_mark_active_quality()

◆ gf_route_dmx_reset_all()