libgpac
Documentation of the core library of GPAC

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_FILE ,
  GF_ROUTE_EVT_DYN_SEG , GF_ROUTE_EVT_DYN_SEG_FRAG , GF_ROUTE_EVT_FILE_DELETE
}
 
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
}
 

Functions

GF_ROUTEDmxgf_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_ROUTEDmxgf_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_ROUTEDmxgf_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_ROUTEDmxgf_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)
 
void gf_route_dmx_del (GF_ROUTEDmx *routedmx)
 
GF_Err gf_route_dmx_process (GF_ROUTEDmx *routedmx)
 
GF_Err gf_route_set_reorder (GF_ROUTEDmx *routedmx, Bool force_reorder, u32 timeout_ms)
 
GF_Err gf_route_set_allow_progressive_dispatch (GF_ROUTEDmx *routedmx, Bool allow_progressive)
 
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)
 

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

GF_Blob * blob

blob data pointer

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)

u32 nb_frags

number of fragments, only set for GF_ROUTE_EVT_DYN_SEG

GF_LCTFragInfo * frags

fragment info, only set for GF_ROUTE_EVT_DYN_SEG

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

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

Enumerator
GF_ROUTE_EVT_SERVICE_FOUND 

A new service 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 available for service, service ID is in evt_param, no file 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 is always beginning 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

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
ifcenetwork interface to monitor, NULL for INADDR_ANY
sock_buffer_sizedefault buffer size for the udp sockets. If 0, uses 0x2000
on_eventthe user callback function
udtathe 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
ifcenetwork interface to monitor, NULL for INADDR_ANY
sock_buffer_sizedefault buffer size for the udp sockets. If 0, uses 0x2000
netcap_idID of netcap configuration to use, may be null (see gpac -h netcap)
on_eventthe user callback function
udtathe 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
ipIP address of ROUTE session
portport of ROUTE session
ifcenetwork interface to monitor, NULL for INADDR_ANY
sock_buffer_sizedefault buffer size for the udp sockets. If 0, uses 0x2000
on_eventthe user callback function
udtathe 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
ipIP address of ROUTE session
portport of ROUTE session
ifcenetwork interface to monitor, NULL for INADDR_ANY
sock_buffer_sizedefault buffer size for the udp sockets. If 0, uses 0x2000
netcap_idID of netcap configuration to use, may be null (see gpac -h netcap)
on_eventthe user callback function
udtathe user data passed back by the callback
Returns
the ROUTE demultiplexer created

◆ gf_route_dmx_del()

void gf_route_dmx_del ( GF_ROUTEDmx routedmx)

Deletes an ROUTE demultiplexer

Parameters
routedmxthe 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
routedmxthe ROUTE demultiplexer
Returns
error code if any, GF_IP_NETWORK_EMPTY if nothing was read

◆ gf_route_set_reorder()

GF_Err gf_route_set_reorder ( GF_ROUTEDmx routedmx,
Bool  force_reorder,
u32  timeout_ms 
)

Sets reordering on.

Parameters
routedmxthe ROUTE demultiplexer
force_reorderif 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_msmaximum delay to wait before considering the object is done when ROUTE/LCT order is not used. A value of 0 implies waiting forever (default value is 5s).
Returns
error code if any

◆ gf_route_set_allow_progressive_dispatch()

GF_Err gf_route_set_allow_progressive_dispatch ( GF_ROUTEDmx routedmx,
Bool  allow_progressive 
)

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
routedmxthe ROUTE demultiplexer
allow_progressiveif TRUE, fragments of segments will be sent during download
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
routedmxthe ROUTE demultiplexer
service_idID of the service to tune in. 0 means no service, 0xFFFFFFFF means all services and 0xFFFFFFFE means first service found
tune_othersif 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
routedmxthe ROUTE demultiplexer
service_idID 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
routedmxthe ROUTE demultiplexer
service_idID of the service to query
fileNamename of the file associated with the object
purge_previousif 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
routedmxthe ROUTE demultiplexer
service_idID of the service to query
fileNamename 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
routedmxthe ROUTE demultiplexer
service_idID 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
routedmxthe ROUTE demultiplexer
service_idID 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
routedmxthe ROUTE demultiplexer
service_idID 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
routedmxthe 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
routedmxthe 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
routedmxthe 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
routedmxthe 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
routedmxthe ROUTE demultiplexer
tsithe 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
routedmxthe ROUTE demultiplexer
service_idthe target service
udtathe 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
routedmxthe ROUTE demultiplexer
service_idthe target service
Returns
the user data associated with the service