1 /*
2 * Copyright (c) 2011-2014 - Mauro Carvalho Chehab
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation version 2.1 of the License.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program; if not, write to the Free Software
15 */
16 #ifndef _DVB_FILE_H
17 #define _DVB_FILE_H
18
19 #include "dvb-fe.h"
20
21 /**
22 * @file dvb-file.h
23 * @ingroup file
24 * @brief Provides interfaces to deal with DVB channel and program files.
25 * @copyright GNU Lesser General Public License version 2.1 (LGPLv2.1)
26 * @author Mauro Carvalho Chehab
27 *
28 * There are basically two types of files used for DVB:
29 * - files that describe the physical channels (also called as transponders);
30 * - files that describe the several programs found on a MPEG-TS (also called
31 * as zap files).
32 *
33 * The libdvbv5 library defines an unified type for both types. Other
34 * applications generally use different formats.
35 *
36 * The purpose of the functions and structures defined herein is to provide
37 * support to read and write to those different formats.
38 *
39 * @par Bug Report
40 * Please submit bug reports and patches to linux-media@vger.kernel.org
41 */
42
43 /*
44 * DVB structures used to represent all files opened by the libdvbv5 library.
45 *
46 * Those structs represents each individual entry on a file, and the file
47 * as a whole.
48 */
49
50 /**
51 * @struct dvb_elementary_pid
52 * @brief associates an elementary stream type with its PID
53 * @ingroup file
54 *
55 * @param type Elementary stream type
56 * @param pid Elementary stream Program ID
57 */
58 struct dvb_elementary_pid {
59 uint8_t type;
60 uint16_t pid;
61 };
62
63 /**
64 * @struct dvb_entry
65 * @brief Represents one entry on a DTV file
66 * @ingroup file
67 *
68 * @param props A property key/value pair. The keys are the ones
69 * specified at the DVB API, plus the ones defined
70 * internally by libdvbv5, at the dvb-v5-std.h
71 * header file.
72 * @param next a pointer to the next entry. NULL if this is
73 * the last one.
74 * @param service_id Service ID associated with a program inside a
75 * transponder. Please note that pure "channel"
76 * files will have this field filled with 0.
77 * @param video_pid Array with the video program IDs inside a service
78 * @param audio_pid Array with the audio program IDs inside a service
79 * @param other_el_pid Array with all non-audio/video program IDs
80 * inside a service
81 * @param video_pid_len Size of the video_pid array
82 * @param audio_pid_len Size of the audio_pid array
83 * @param other_el_pid_len Size of the other_el_pid array
84 * @param channel String containing the name of the channel
85 * @param vchannel String representing the Number of the channel
86 * @param location String representing the location of the channel
87 * @param sat_number For satellite streams, this represents the
88 * number of the satellite dish on a DiSeqC
89 * arrangement. Should be zero on arrangements
90 * without DiSeqC.
91 * @param freq_bpf SCR/Unicable band-pass filter frequency to
92 * use, in kHz.
93 * For non SRC/Unicable arrangements, it should
94 * be zero.
95 * @param diseqc_wait Extra time to wait for DiSeqC commands to
96 * complete, in ms. The library will use 15 ms
97 * as the minimal time,
98 * plus the time specified on this field.
99 * @param lnb String with the name of the LNBf to be used for
100 * satellite tuning. The names should match the
101 * names provided by dvb_sat_get_lnb() call
102 * (see dvb-sat.h).
103 */
104 struct dvb_entry {
105 struct dtv_property props[DTV_MAX_COMMAND];
106 unsigned int n_props;
107 struct dvb_entry *next;
108 uint16_t service_id;
109 uint16_t *video_pid, *audio_pid;
110 struct dvb_elementary_pid *other_el_pid;
111 unsigned video_pid_len, audio_pid_len, other_el_pid_len;
112 char *channel;
113 char *vchannel;
114
115 char *location;
116
117 int sat_number;
118 unsigned freq_bpf;
119 unsigned diseqc_wait;
120 char *lnb;
121
122 uint16_t network_id;
123 uint16_t transport_id;
124
125 };
126
127 /**
128 * @struct dvb_file
129 * @brief Describes an entire DVB file opened
130 *
131 * @param fname name of the file
132 * @param n_entries number of the entries read
133 * @param first_entry entry for the first entry. NULL if the file is empty.
134 */
135 struct dvb_file {
136 char *fname;
137 int n_entries;
138 struct dvb_entry *first_entry;
139 };
140
141 /*
142 * DVB file format tables
143 *
144 * The structs below are used to represent oneline formats like the ones
145 * commonly found on DVB legacy applications.
146 */
147
148 /**
149 * @struct dvb_parse_table
150 * @brief Describes the fields to parse on a file
151 * @ingroup file
152 *
153 * @param prop Name of the DVBv5 or libdvbv5 property field
154 * @param table Name of a translation table for string to
155 * int conversion
156 * @param size Size of the translation table
157 * @param mult_factor Multiply factor - Used, for example, to
158 * multiply the symbol rate read from a DVB-S
159 * table by 1000.
160 * @param has_default_value It is different than zero when the property
161 * can be optional. In this case, the next field
162 * should be present
163 * @param default_value Default value for the optional field
164 */
165 struct dvb_parse_table {
166 unsigned int prop;
167 const char **table;
168 unsigned int size;
169 int mult_factor;
170 int has_default_value;
171 int default_value;
172 };
173 /**
174 * @struct dvb_parse_struct
175 * @brief Describes the format to parse an specific delivery system
176 * @ingroup file
177 *
178 * @param id String that identifies the delivery system on the
179 * file to be parsed
180 * @param delsys Delivery system
181 * @param table the struct dvb_parse_table used to parse for this
182 * specific delivery system
183 * @param size Size of the table
184 */
185 struct dvb_parse_struct {
186 char *id;
187 uint32_t delsys;
188 const struct dvb_parse_table *table;
189 unsigned int size;
190 };
191
192 /**
193 * @struct dvb_parse_file
194 * @brief Describes an entire file format
195 *
196 * @param has_delsys_id A non-zero value indicates that the id field
197 * at the formats vector should be used
198 * @param delimiter Delimiters to split entries on the format
199 * @param formats A struct dvb_parse_struct vector with the
200 * per delivery system parsers. This table should
201 * terminate with an empty entry.
202 */
203 struct dvb_parse_file {
204 int has_delsys_id;
205 char *delimiter;
206 struct dvb_parse_struct formats[];
207 };
208
209 /**
210 * @enum dvb_file_formats
211 * @brief Known file formats
212 * @ingroup file
213 *
214 * @details
215 * Please notice that the channel format defined here has a few optional
216 * fields that aren't part of the dvb-apps format, for DVB-S2 and for DVB-T2.
217 * They're there to match the formats found at dtv-scan-tables package up to
218 * September, 5 2014.
219 *
220 * @var FILE_UNKNOWN
221 * @brief File format is unknown
222 * @var FILE_ZAP
223 * @brief File is at the dvb-apps "dvbzap" format
224 * @var FILE_CHANNEL
225 * @brief File is at the dvb-apps output format for dvb-zap
226 * @var FILE_DVBV5
227 * @brief File is at libdvbv5 format
228 * @var FILE_VDR
229 * @brief File is at DVR format (as supported on version 2.1.6).
230 * Note: this is only supported as an output format.
231 */
232 enum dvb_file_formats {
233 FILE_UNKNOWN,
234 FILE_ZAP,
235 FILE_CHANNEL,
236 FILE_DVBV5,
237 FILE_VDR,
238 };
239
240 struct dvb_v5_descriptors;
241
242 #ifdef __cplusplus
243 extern "C" {
244 #endif
245
246 /**
247 * @brief Deallocates memory associated with a struct dvb_file
248 * @ingroup file
249 *
250 * @param dvb_file dvb_file struct to be deallocated
251 *
252 * This function assumes that several functions were dynamically allocated
253 * by the library file functions.
254 */
dvb_file_free(struct dvb_file * dvb_file)255 static inline void dvb_file_free(struct dvb_file *dvb_file)
256 {
257 struct dvb_entry *entry = dvb_file->first_entry, *next;
258 while (entry) {
259 next = entry->next;
260 if (entry->channel)
261 free(entry->channel);
262 if (entry->vchannel)
263 free(entry->vchannel);
264 if (entry->location)
265 free(entry->location);
266 if (entry->video_pid)
267 free(entry->video_pid);
268 if (entry->audio_pid)
269 free(entry->audio_pid);
270 if (entry->other_el_pid)
271 free(entry->other_el_pid);
272 if (entry->lnb)
273 free(entry->lnb);
274 free(entry);
275 entry = next;
276 }
277 free(dvb_file);
278 }
279
280 /*
281 * File format description structures defined for the several formats that
282 * the library can read natively.
283 */
284
285 /**
286 * @brief File format definitions for dvb-apps channel format
287 * @ingroup file
288 */
289 extern const struct dvb_parse_file channel_file_format;
290
291 /**
292 * @brief File format definitions for dvb-apps zap format
293 * @ingroup file
294 */
295 extern const struct dvb_parse_file channel_file_zap_format;
296
297 /*
298 * Prototypes for the several functions defined at dvb-file.c
299 */
300
301 /**
302 * @brief Read a file at libdvbv5 format
303 * @ingroup file
304 *
305 * @param fname file name
306 *
307 * @return It returns a pointer to struct dvb_file describing the entries that
308 * were read from the file. If it fails, NULL is returned.
309 */
310 struct dvb_file *dvb_read_file(const char *fname);
311
312 /**
313 * @brief Write a file at libdvbv5 format
314 * @ingroup file
315 *
316 * @param fname file name
317 * @param dvb_file contents of the file to be written
318 *
319 * @return It returns zero if success, or a positive error number if it fails.
320 */
321 int dvb_write_file(const char *fname, struct dvb_file *dvb_file);
322
323 /**
324 * @brief Read a file on any format natively supported by
325 * the library
326 * @ingroup file
327 *
328 * @param fname file name
329 * @param delsys Delivery system, as specified by enum fe_delivery_system
330 * @param format Name of the format to be read
331 *
332 * @return It returns a pointer to struct dvb_file describing the entries that
333 * were read from the file. If it fails, NULL is returned.
334 */
335 struct dvb_file *dvb_read_file_format(const char *fname,
336 uint32_t delsys,
337 enum dvb_file_formats format);
338
339 /**
340 * @brief Write a file on any format natively supported by
341 * the library
342 * @ingroup file
343 *
344 * @param fname file name
345 * @param dvb_file contents of the file to be written
346 * @param delsys Delivery system, as specified by enum fe_delivery_system
347 * @param format Name of the format to be read
348 *
349 * @return It a pointer to struct dvb_file on success, NULL otherwise.
350 */
351 int dvb_write_file_format(const char *fname,
352 struct dvb_file *dvb_file,
353 uint32_t delsys,
354 enum dvb_file_formats format);
355
356
357 /**
358 * @brief Stores a key/value pair on a DVB file entry
359 * @ingroup file
360 *
361 * @param entry entry to be filled
362 * @param cmd key for the property to be used. It be one of the DVBv5
363 * properties, plus the libdvbv5 ones, as defined at dvb-v5-std.h
364 * @param value value for the property.
365 *
366 * This function seeks for a property with the name specified by cmd and
367 * fills it with value. If the entry doesn't exist, it creates a new key.
368 *
369 * @return Returns 0 if success, or, if the entry has already DTV_MAX_COMMAND
370 * properties, it returns -1.
371 */
372 int dvb_store_entry_prop(struct dvb_entry *entry,
373 uint32_t cmd, uint32_t value);
374
375 /**
376 * @brief Retrieves the value associated witha key on a DVB file entry
377 * @ingroup file
378 *
379 * @param entry entry to be used
380 * @param cmd key for the property to be found. It be one of the DVBv5
381 * properties, plus the libdvbv5 ones, as defined at dvb-v5-std.h
382 * @param value pointer to store the value associated with the property.
383 *
384 * This function seeks for a property with the name specified by cmd and
385 * fills value with its contents.
386 *
387 * @return Returns 0 if success, or, -1 if the entry doesn't exist.
388 */
389 int dvb_retrieve_entry_prop(struct dvb_entry *entry,
390 uint32_t cmd, uint32_t *value);
391
392 /**
393 * @brief stored a new scanned channel into a dvb_file struct
394 * @ingroup file
395 *
396 * @param dvb_file file struct to be filled
397 * @param parms struct dvb_v5_fe_parms used by libdvbv5 frontend
398 * @param dvb_desc struct dvb_desc as described at descriptors.h, filled
399 * with the descriptors associated with a DVB channel.
400 * those descriptors can be filled by calling one of the
401 * scan functions defined at dvb-sat.h.
402 * @param get_detected if different than zero, uses the frontend parameters
403 * obtained from the device driver (such as modulation,
404 * FEC, etc)
405 * @param get_nit if true, uses the parameters obtained from the MPEG-TS
406 * NIT table to add newly detected transponders.
407 *
408 * This function should be used to store the services found on a scanned
409 * transponder. Initially, it copies the same parameters used to set the
410 * frontend, that came from a file where the Service ID and Elementary Stream
411 * PIDs are unknown. At tuning time, it is common to set the device to tune
412 * on auto-detection mode (e. g. using QAM/AUTO, for example, to autodetect
413 * the QAM modulation). The libdvbv5's logic will be to check the detected
414 * values. So, the modulation might, for example, have changed to QAM/256.
415 * In such case, if get_detected is 0, it will store QAM/AUTO at the struct.
416 * If get_detected is different than zero, it will store QAM/256.
417 * If get_nit is different than zero, and if the MPEG-TS has info about other
418 * physical channels/transponders, this function will add newer entries to
419 * dvb_file, for it to seek for new transponders. This is very useful especially
420 * for DVB-C, where all transponders belong to the same operator. Knowing one
421 * frequency is generally enough to get all DVB-C transponders.
422 *
423 * @return Returns 0 if success, or, -1 if error.
424 */
425 int dvb_store_channel(struct dvb_file **dvb_file,
426 struct dvb_v5_fe_parms *parms,
427 struct dvb_v5_descriptors *dvb_desc,
428 int get_detected, int get_nit);
429
430 /**
431 * @brief Ancillary function that seeks for a delivery system
432 * @ingroup file
433 *
434 * @param name string containing the name of the Delivery System to seek
435 *
436 * If the name is found, this function returns the DVBv5 property that
437 * corresponds to the string given. The function is case-insensitive, and
438 * it can check for alternate ways to write the name of a Delivery System.
439 * Currently, it supports: DVB-C, DVB-H, DVB-S, DVB-S2, DVB-T, DVB-T2,
440 * ISDB-C, ISDB-S, ISDB-T, ATSC-MH, DVBC/ANNEX_A, DVBC/ANNEX_B, DVBT, DSS,
441 * DVBS, DVBS2, DVBH, ISDBT, ISDBS, ISDBC, ATSC, ATSCMH, DTMB, CMMB, DAB,
442 * DVBT2, TURBO, DVBC/ANNEX_C.
443 * Please notice that this doesn't mean that all those standards are properly
444 * supported by the library.
445 *
446 * @return Returns the Delivery System property number if success, -1 if error.
447 */
448 int dvb_parse_delsys(const char *name);
449
450 /**
451 * @brief Ancillary function that parses the name of a file format
452 * @ingroup file
453 *
454 * @param name string containing the name of the format
455 * Current valid names are: ZAP, CHANNEL, VDR and DVBV5.
456 * The name is case-insensitive.
457 *
458 * @return It returns FILE_ZAP, FILE_CHANNEL, FILE_VDR or FILE_DVBV5
459 * if the name was translated. FILE_UNKNOWN otherwise.
460 */
461 enum dvb_file_formats dvb_parse_format(const char *name);
462
463 /*
464 * Routines to read a non-libdvbv5 format. They're called by
465 * dvb_read_file_format() or dvb_write_file_format()
466 */
467
468 /**
469 * @brief Read and parses a one line file format
470 * @ingroup file
471 *
472 * @param fname file name
473 * @param delsys delivery system
474 * @param parse_file pointer struct dvb_parse_file
475 *
476 * @return It a pointer to struct dvb_file on success, NULL otherwise.
477 *
478 * This function is called internally by dvb_read_file_format.
479 */
480 struct dvb_file *dvb_parse_format_oneline(const char *fname,
481 uint32_t delsys,
482 const struct dvb_parse_file *parse_file);
483
484 /**
485 * @brief Writes a file into an one line file format
486 * @ingroup file
487 *
488 * @param fname file name
489 * @param dvb_file contents of the file to be written
490 * @param delsys delivery system
491 * @param parse_file pointer struct dvb_parse_file
492 *
493 * @return It returns zero if success, or a positive error number if it fails.
494 *
495 * This function is called internally by dvb_write_file_format.
496 */
497 int dvb_write_format_oneline(const char *fname,
498 struct dvb_file *dvb_file,
499 uint32_t delsys,
500 const struct dvb_parse_file *parse_file);
501
502 /**
503 * @brief Writes a file into vdr format (compatible up to version 2.1)
504 * @ingroup file
505 *
506 * @param fname file name
507 * @param dvb_file contents of the file to be written
508 *
509 * @return It returns zero if success, or a positive error number if it fails.
510 *
511 * This function is called internally by dvb_write_file_format.
512 */
513 int dvb_write_format_vdr(const char *fname,
514 struct dvb_file *dvb_file);
515
516 #ifdef __cplusplus
517 }
518 #endif
519
520 #endif // _DVB_FILE_H
521