libdvbv5: Digital TV frontend scan

libdvbv5 1.28.1 Library to work with Digital TV devices on Linux

Files | Data Structures | Typedefs | Functions
Digital TV frontend scan

## Files
file | dvb-scan.h
| Provides interfaces to scan programs inside MPEG-TS digital TV streams.

## Data Structures
struct | dvb_v5_descriptors_program
| Associates PMT with PAT tables. More...
struct | dvb_v5_descriptors
| Contains the descriptors needed to scan the Service ID and other relevant info at a MPEG-TS Digital TV stream. More...
struct | dvb_table_filter
| Describes the PES filters used by DVB scan. More...

## Typedefs
typedef int | check_frontend_t(void *args, struct dvb_v5_fe_parms *parms)
| Callback for the application to show the frontend status.

## Functions
struct dvb_v5_descriptors * | dvb_dev_scan (struct dvb_open_descriptor *open_dev, struct dvb_entry *entry, check_frontend_t *check_frontend, void *args, unsigned other_nit, unsigned timeout_multiply)
| Scans a DVB dvb_add_scaned_transponder.
void | dvb_table_filter_free (struct dvb_table_filter *sect)
| deallocates all data associated with a table filter
int | dvb_read_section (struct dvb_v5_fe_parms *parms, int dmx_fd, unsigned char tid, uint16_t pid, void **table, unsigned timeout)
| read MPEG-TS tables that comes from a DTV card
int | dvb_read_section_with_id (struct dvb_v5_fe_parms *parms, int dmx_fd, unsigned char tid, uint16_t pid, int ts_id, void **table, unsigned timeout)
| read MPEG-TS tables that comes from a DTV card with an specific table section ID
int | dvb_read_sections (struct dvb_v5_fe_parms *parms, int dmx_fd, struct dvb_table_filter *sect, unsigned timeout)
| read MPEG-TS tables that comes from a DTV card
struct dvb_v5_descriptors * | dvb_scan_alloc_handler_table (uint32_t delivery_system)
| allocates a struct dvb_v5_descriptors
void | dvb_scan_free_handler_table (struct dvb_v5_descriptors *dvb_scan_handler)
| frees a struct dvb_v5_descriptors
struct dvb_v5_descriptors * | dvb_get_ts_tables (struct dvb_v5_fe_parms *parms, int dmx_fd, uint32_t delivery_system, unsigned other_nit, unsigned timeout_multiply)
| Scans a DVB stream, looking for the tables needed to identify the programs inside a MPEG-TS.
void | dvb_free_ts_tables (struct dvb_v5_descriptors *dvb_desc)
| frees a struct dvb_v5_descriptors
struct dvb_v5_descriptors * | dvb_scan_transponder (struct dvb_v5_fe_parms *parms, struct dvb_entry *entry, int dmx_fd, check_frontend_t *check_frontend, void *args, unsigned other_nit, unsigned timeout_multiply)
| Scans a DVB dvb_add_scaned_transponder.
void | dvb_add_scaned_transponders (struct dvb_v5_fe_parms *parms, struct dvb_v5_descriptors *dvb_scan_handler, struct dvb_entry *first_entry, struct dvb_entry *entry)
| Add new transponders to a dvb_file.

## Detailed Description

## Typedef Documentation

## ◆ check_frontend_t

typedef int check_frontend_t(void *args, struct dvb_v5_fe_parms *parms)

Callback for the application to show the frontend status.

Parameters

  args | a pointer, opaque to libdvbv5, to be used by the application if needed.
  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened

Definition at line 293 of file dvb-scan.h.

## Function Documentation

## ◆ dvb_add_scaned_transponders()

void dvb_add_scaned_transponders | ( | struct dvb_v5_fe_parms * | parms,
|  | struct dvb_v5_descriptors * | dvb_scan_handler,
|  | struct dvb_entry * | first_entry,
|  | struct dvb_entry * | entry )

Add new transponders to a dvb_file.

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  dvb_scan_handler | pointer to a struct dvb_v5_descriptors containing scaned MPEG-TS
  first_entry | first entry of a DVB file struct
  entry | current entry on a DVB file struct

When the NIT table is parsed, some new transponders could be described inside. This function adds new entries to a dvb_file struct, pointing to those new transponders. It is used inside the scan loop, as shown at the dvb_scan_transponder(), to add new channels.

Example:

for (entry = dvb_file->first_entry; entry != NULL; entry = entry->next) {
struct dvb_v5_descriptors *dvb_scan_handler = NULL;
dvb_scan_handler = dvb_scan_transponder(parms, entry, dmx_fd,
&check_frontend, args,
args->other_nit,
args->timeout_multiply);
if (parms->abort) {
dvb_scan_free_handler_table(dvb_scan_handler);
break;
}
if (dvb_scan_handler) {
dvb_store_channel(&dvb_file_new, parms, dvb_scan_handler,
args->get_detected, args->get_nit);
dvb_scan_free_handler_table(dvb_scan_handler);
dvb_add_scaned_transponders(parms, dvb_scan_handler,
dvb_file->first_entry, entry);
dvb_scan_free_handler_table(dvb_scan_handler);
}
}
dvb_store_channel
int dvb_store_channel(struct dvb_file **dvb_file, struct dvb_v5_fe_parms *parms, struct dvb_v5_descriptors *dvb_desc, int get_detected, int get_nit)
stored a new scanned channel into a dvb_file struct
dvb_scan_transponder
struct dvb_v5_descriptors * dvb_scan_transponder(struct dvb_v5_fe_parms *parms, struct dvb_entry *entry, int dmx_fd, check_frontend_t *check_frontend, void *args, unsigned other_nit, unsigned timeout_multiply)
Scans a DVB dvb_add_scaned_transponder.
dvb_add_scaned_transponders
void dvb_add_scaned_transponders(struct dvb_v5_fe_parms *parms, struct dvb_v5_descriptors *dvb_scan_handler, struct dvb_entry *first_entry, struct dvb_entry *entry)
Add new transponders to a dvb_file.
dvb_scan_free_handler_table
void dvb_scan_free_handler_table(struct dvb_v5_descriptors *dvb_scan_handler)
frees a struct dvb_v5_descriptors
dvb_entry::next
struct dvb_entry * next
Definition dvb-file.h:107
dvb_file
Describes an entire DVB file opened.
Definition dvb-file.h:135
dvb_file::first_entry
struct dvb_entry * first_entry
Definition dvb-file.h:138
dvb_v5_descriptors
Contains the descriptors needed to scan the Service ID and other relevant info at a MPEG-TS Digital T...
Definition dvb-scan.h:87
dvb_v5_descriptors::entry
struct dvb_entry * entry
Definition dvb-scan.h:90

Examples
  dvbv5-scan.c.

## ◆ dvb_dev_scan()

struct dvb_v5_descriptors * dvb_dev_scan | ( | struct dvb_open_descriptor * | open_dev,
|  | struct dvb_entry * | entry,
|  | check_frontend_t * | check_frontend,
|  | void * | args,
|  | unsigned | other_nit,
|  | unsigned | timeout_multiply )

Scans a DVB dvb_add_scaned_transponder.

Parameters

  entry | DVB file entry that corresponds to a transponder to be tuned
  open_dev | Points to the struct dvb_open_descriptor
  check_frontend | a pointer to a function that will show the frontend status while tuning into a transponder
  args | a pointer, opaque to libdvbv5, that will be used when calling check_frontend. It should contain any parameters that could be needed by check_frontend.
  other_nit | Use alternate table IDs for NIT and other tables
  timeout_multiply | Improves the timeout for each table reception, by

This is the function that applications should use when doing a transponders scan. It does everything needed to fill the entries with DVB programs (virtual channels) and detect the PIDs associated with them.

This is the dvb_device variant of dvb_scan_transponder().

Examples
  dvbv5-scan.c.

## ◆ dvb_free_ts_tables()

void dvb_free_ts_tables | ( | struct dvb_v5_descriptors * | dvb_desc | ) |

frees a struct dvb_v5_descriptors

Parameters

  dvb_desc | pointed to the structure to be freed.

This function recursively frees everything that is allocated by dvb_get_ts_tables() and stored at dvb_desc, including dvb_desc itself.

## ◆ dvb_get_ts_tables()

struct dvb_v5_descriptors * dvb_get_ts_tables | ( | struct dvb_v5_fe_parms * | parms,
|  | int | dmx_fd,
|  | uint32_t | delivery_system,
|  | unsigned | other_nit,
|  | unsigned | timeout_multiply )

Scans a DVB stream, looking for the tables needed to identify the programs inside a MPEG-TS.

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  dmx_fd | an opened demux file descriptor
  delivery_system | delivery system to be scanned
  other_nit | use alternate table IDs for NIT and other tables
  timeout_multiply | improves the timeout for each table reception by using a value that will multiply the wait time.

Given an opened frontend and demux, this function seeks for all programs available at the transport stream, and parses the following tables: PAT, PMT, NIT, SDT (and VCT, if the delivery system is ATSC).

On sucess, it returns a pointer to a struct dvb_v5_descriptors, that can either be used to tune into a service or to be stored inside a file.

## ◆ dvb_read_section()

int dvb_read_section | ( | struct dvb_v5_fe_parms * | parms,
|  | int | dmx_fd,
|  | unsigned char | tid,
|  | uint16_t | pid,
|  | void ** | table,
|  | unsigned | timeout )

read MPEG-TS tables that comes from a DTV card

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  dmx_fd | an opened demux file descriptor
  tid | Table ID
  pid | Program ID
  table | pointer to a pointer for the table struct to be filled
  timeout | Limit, in seconds, to read a MPEG-TS table

This function is used to read the DVB tables by specifying a table ID and a program ID. The libdvbv5 should have a parser for the descriptors of the table type that should be parsed. The table will be automatically allocated on success. The function will read on the specified demux and return when reading is done or an error has occurred. If table is not NULL after the call, it has to be freed with the apropriate free table function (even if an error has occurred).

If the application wants to abort the read operation, it can change the value of parms->p.abort to 1.

Returns 0 on success or a negative error code.

Example usage:

struct dvb_table_pat *pat;
int r = dvb_read_section( parms, dmx_fd, DVB_TABLE_PAT, DVB_TABLE_PAT_PID,
(void **) &pat, 5 );
if (r < 0)
dvb_logerr("error reading PAT table");
else {
// do something with pat
}
if (pat)
dvb_table_pat_free( pat );
DVB_TABLE_PAT_PID
#define DVB_TABLE_PAT_PID
PAT Program ID.
Definition pat.h:56
DVB_TABLE_PAT
#define DVB_TABLE_PAT
PAT table ID.
Definition pat.h:55
dvb_table_pat_free
void dvb_table_pat_free(struct dvb_table_pat *table)
Frees all data allocated by the PAT table parser.
dvb_read_section
int dvb_read_section(struct dvb_v5_fe_parms *parms, int dmx_fd, unsigned char tid, uint16_t pid, void **table, unsigned timeout)
read MPEG-TS tables that comes from a DTV card
dvb_table_pat
MPEG-TS PAT table.
Definition pat.h:108

## ◆ dvb_read_section_with_id()

int dvb_read_section_with_id | ( | struct dvb_v5_fe_parms * | parms,
|  | int | dmx_fd,
|  | unsigned char | tid,
|  | uint16_t | pid,
|  | int | ts_id,
|  | void ** | table,
|  | unsigned | timeout )

read MPEG-TS tables that comes from a DTV card with an specific table section ID

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  dmx_fd | an opened demux file descriptor
  tid | Table ID
  pid | Program ID
  ts_id | Table section ID (for multisession filtering). If no specific table section is needed, -1 should be used
  table | pointer to a pointer for the table struct to be filled
  timeout | limit, in seconds, to read a MPEG-TS table

This is a variant of dvb_read_section() that also seeks for an specific table section ID given by ts_id.

## ◆ dvb_read_sections()

int dvb_read_sections | ( | struct dvb_v5_fe_parms * | parms,
|  | int | dmx_fd,
|  | struct dvb_table_filter * | sect,
|  | unsigned | timeout )

read MPEG-TS tables that comes from a DTV card

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  dmx_fd | an opened demux file descriptor
  sect | section filter pointer
  timeout | limit, in seconds, to read a MPEG-TS table

This is a variant of dvb_read_section() that uses a struct dvb_table_filter to specify the filter to use.

## ◆ dvb_scan_alloc_handler_table()

struct dvb_v5_descriptors * dvb_scan_alloc_handler_table | ( | uint32_t | delivery_system | ) |

allocates a struct dvb_v5_descriptors

Parameters

  delivery_system | Delivery system to be used on the table

At success, returns a pointer. NULL otherwise.

## ◆ dvb_scan_free_handler_table()

void dvb_scan_free_handler_table | ( | struct dvb_v5_descriptors * | dvb_scan_handler | ) |

frees a struct dvb_v5_descriptors

Parameters

  dvb_scan_handler | pointer to the struct to be freed.

Examples
  dvbv5-scan.c.

## ◆ dvb_scan_transponder()

struct dvb_v5_descriptors * dvb_scan_transponder | ( | struct dvb_v5_fe_parms * | parms,
|  | struct dvb_entry * | entry,
|  | int | dmx_fd,
|  | check_frontend_t * | check_frontend,
|  | void * | args,
|  | unsigned | other_nit,
|  | unsigned | timeout_multiply )

Scans a DVB dvb_add_scaned_transponder.

Parameters

  parms | pointer to struct dvb_v5_fe_parms created when the frontend is opened
  entry | DVB file entry that corresponds to a transponder to be tuned
  dmx_fd | an opened demux file descriptor
  check_frontend | a pointer to a function that will show the frontend status while tuning into a transponder
  args | a pointer, opaque to libdvbv5, that will be used when calling check_frontend. It should contain any parameters that could be needed by check_frontend.
  other_nit | Use alternate table IDs for NIT and other tables
  timeout_multiply | Improves the timeout for each table reception, by

This is the function that applications should use when doing a transponders scan. It does everything needed to fill the entries with DVB programs (virtual channels) and detect the PIDs associated with them.

A typical usage is to after open a channel file, open a dmx_fd and open a frontend. Then, seek for the MPEG tables on all the transponder frequencies with:

for (entry = dvb_file->first_entry; entry != NULL; entry = entry->next) {
struct dvb_v5_descriptors *dvb_scan_handler = NULL;
dvb_scan_handler = dvb_scan_transponder(parms, entry, dmx_fd,
&check_frontend, args,
args->other_nit,
args->timeout_multiply);
if (parms->abort) {
dvb_scan_free_handler_table(dvb_scan_handler);
break;
}
if (dvb_scan_handler) {
dvb_store_channel(&dvb_file_new, parms, dvb_scan_handler,
args->get_detected, args->get_nit);
dvb_scan_free_handler_table(dvb_scan_handler);
}
}

## ◆ dvb_table_filter_free()

void dvb_table_filter_free | ( | struct dvb_table_filter * | sect | ) |

deallocates all data associated with a table filter

Parameters

  sect | table filter pointer