"Fossies" - the Fresh Open Source Software Archive 
Member "xorriso-1.5.4/libjte/libjte.h" (30 Jan 2021, 23734 Bytes) of package /linux/misc/xorriso-1.5.4.pl02.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style:
standard) with prefixed line numbers and
code folding option.
Alternatively you can here
view or
download the uninterpreted source code file.
For more information about "libjte.h" see the
Fossies "Dox" file reference documentation and the last
Fossies "Diffs" side-by-side code changes report:
1.5.2_vs_1.5.4.
1 /*
2 * libjte.h
3 *
4 * Copyright (c) 2010 Thomas Schmitt <scdbackup@gmx.net>
5 *
6 * API definition of libjte, to be included as <libjte/libjte.h>
7 *
8 * GNU LGPL v2.1 (including option for GPL v2 or later)
9 *
10 */
11
12 #ifndef LIBJTE_H_INCLUDED
13 #define LIBJTE_H_INCLUDED 1
14
15 #include <sys/types.h>
16
17 /* The common environment handle */
18
19 struct libjte_env;
20
21
22 /* --------------------------- Version Inquiry --------------------------- */
23
24 /** These three release version numbers tell the revision of this header file
25 and of the API which it describes. They shall be memorized by applications
26 at build time.
27 @since 0.1.0
28 */
29 #define LIBJTE_VERSION_MAJOR 2
30 #define LIBJTE_VERSION_MINOR 0
31 #define LIBJTE_VERSION_MICRO 0
32
33 /** Obtain the three release version numbers of the library. These are the
34 numbers encountered by the application when linking with libjte
35 i.e. possibly not before run time.
36 Better do not base the fundamental compatibility decision of an application
37 on these numbers. For a reliable check use libjte__is_compatible().
38 @since 0.1.0
39 @param major The maturity version (0 for now, as we are still learning)
40 @param minor The development goal version.
41 @param micro The development step version.
42 */
43 void libjte__version(int *major, int *minor, int *micro);
44
45 /** Check whether all features of header file libjte.h from the given
46 major.minor.micro revision triple can be delivered by the library version
47 which is performing this call.
48 if (! libjte__is_compatible(LIBJTE_VERSION_MAJOR, LIBJTE_VERSION_MINOR,
49 LIBJTE_VERSION_MICRO, 0))
50 ...refuse to start the program with this dynamic library version...
51 @since 0.1.0
52 @param major obtained at build time
53 @param minor obtained at build time
54 @param micro obtained at build time
55 @param flag Bitfield for control purposes. Unused yet. Submit 0.
56 @return 1= library can work for caller
57 0= library is not usable in some aspects. Caller must restrict
58 itself to an earlier API version or must not use this library
59 at all.
60 */
61 int libjte__is_compatible(int major, int minor, int micro, int flag);
62
63
64 /* ------------------------------- Life Cycle ----------------------------- */
65
66 /** Create a libjte environment object. It is to be used with most of the
67 calls of this API for storing parameters and for memorizing the state
68 of its libjte operations.
69 @since 0.1.0
70 @param jte_handle Returns an opaque handle to the allocated environment
71 @param flag Bitfield for control purposes. Unused yet. Submit 0.
72 @return >0 means success, <=0 indicates failure
73 */
74 int libjte_new(struct libjte_env **jte_handle, int flag);
75
76
77 /** Dispose a libjte environment and free the system facilities which it uses.
78 @since 0.1.0
79 @param jte_handle The environment to be disposed.
80 *jte_handle will be set to NULL
81 @return >0 means success, <=0 indicates failure
82 */
83 int libjte_destroy(struct libjte_env **jte_handle);
84
85
86 /* ----------------------------- Parameter Setup ------------------------- */
87
88 /** Tell libjte the name that will become value of "Filename=" in the "[Image]"
89 section of the jigdo file.
90 @since 0.1.0
91 @param jte_handle The environment to be manipulated.
92 @param outfile The value
93 @return >0 means success, <=0 indicates failure
94 */
95 int libjte_set_outfile(struct libjte_env *jte_handle, char *outfile);
96
97 /** Enable or disable debugging verbosity.
98 @since 0.1.0
99 @param jte_handle The environment to be manipulated.
100 @param verbose If not 0 : cause verbosity
101 @return >0 means success, <=0 indicates failure
102 */
103 int libjte_set_verbose(struct libjte_env *jte_handle, int verbose);
104
105 /** Choose the checksum algorithm that libjte will use in its checksum
106 calculations and expectations. Supported algorithms are "md5" and
107 "sha256". If this function is *not* called explicitly, libjte will
108 default to "md5" for backwards compatibility with older versions
109 of the library that only supported md5.
110 Choice of the checksum algorithm here is important elsewhere in
111 terms of sizes of buffers, formats of input, etc.:
112 - libjte_set_md5_path()
113 - libjte_set_checksum_path()
114 - libjte_decide_file_jigdo{,2}()
115 - libjte_write_match_record{,2}()
116 It also affects the compatibility of the jigdo and template files
117 created. Choosing "md5" will modify the format of the template
118 file, and declare the "Version" in the [Jigdo] field to be
119 1.2. Choosing "sha256" will declare the "Version" in the [Jigdo]
120 field to be 2.0 and the output will *NOT* work with older jigdo
121 client tools.
122 @since 2.0.0
123 @param jte_handle The environment to be manipulated.
124 @param algorithm If not 0 : cause verbosity
125 @param size Pointer to storage; if no errors, will be filled
126 with the size in bytes of the checksum output for
127 future function calls to use
128 @return >0 means success, <=0 indicates failure
129 */
130 int libjte_set_checksum_algorithm(struct libjte_env *jte_handle,
131 char *algorithm, int *size);
132
133 /** Define the file address on hard disk for the template file.
134 @since 0.1.0
135 @param jte_handle The environment to be manipulated.
136 @param path Will be used with fopen(path, "w")
137 @return >0 means success, <=0 indicates failure
138 */
139 int libjte_set_template_path(struct libjte_env *jte_handle, char *path);
140
141 /** Define the file address on hard disk for the jigdo file.
142 @since 0.1.0
143 @param jte_handle The environment to be manipulated.
144 @param path Will be used with fopen(path, "w")
145 @return >0 means success, <=0 indicates failure
146 */
147 int libjte_set_jigdo_path(struct libjte_env *jte_handle, char *path);
148
149 /** Tell libjte the hard disk address of the .md5 file, which lists the
150 data files which might get extracted and referred in the jigdo file.
151 Still supported in 2.0.0, but is now just an alias for
152 libjte_set_checksums_path(handle, path) below
153 \deprecated since 2.0.0
154 @since 0.1.0
155 @param jte_handle The environment to be manipulated.
156 @param path Will be used with fopen(path, "r")
157 @return >0 means success, <=0 indicates failure
158 */
159 int libjte_set_md5_path(struct libjte_env *jte_handle, char *path);
160
161 /** Tell libjte the hard disk address of the .checksum file, which
162 lists the data files which might get extracted and referred in the
163 jigdo file.
164 @since 2.0.0
165 @param jte_handle The environment to be manipulated.
166 @param path Will be used with fopen(path, "r")
167 @return >0 means success, <=0 indicates failure
168 */
169 int libjte_set_checksum_path(struct libjte_env *jte_handle, char *path);
170
171 /** Define a minimum size for data files to get extracted and referred in
172 the jigdo file.
173 @since 0.1.0
174 @param jte_handle The environment to be manipulated.
175 @param min_size Lower size limit in bytes
176 @return >0 means success, <=0 indicates failure
177 */
178 int libjte_set_min_size(struct libjte_env *jte_handle, int min_size);
179
180 /** Choose one or more checksum algorithms to be applied to the emerging
181 payload image. The resulting sums will be written into the jigdo file
182 as lines "# Image Hex ...".
183 Supported algorithms are "md5", "sha1", "sha256", "sha512" which may be
184 combined in a comma separated list like "md5,sha1,sha512".
185 Checksum_code "all" chooses all available algorithms.
186 @since 0.1.0
187 @param jte_handle The environment to be manipulated.
188 @param checksum_code Comma separated list string or "all".
189 @return >0 means success, <=0 indicates failure
190 */
191 int libjte_set_checksum_iso(struct libjte_env *jte_handle,
192 char *checksum_code);
193
194 /** Choose one or more checksum algorithms to be applied to the emerging
195 template file. The resulting sums will be written into the jigdo file
196 as lines "# Template Hex ...".
197 Supported algorithms are "md5", "sha1", "sha256", "sha512" which may be
198 combined in a comma separated list like "md5,sha1,sha512".
199 Checksum_code "all" chooses all available algorithms.
200 @since 0.1.0
201 @param jte_handle The environment to be manipulated.
202 @param checksum_code Comma separated list string or "all".
203 @return >0 means success, <=0 indicates failure
204 */
205 int libjte_set_checksum_template(struct libjte_env *jte_handle,
206 char *checksum_code);
207
208 /** Choose a compression algorithm for the template file.
209 @since 0.1.0
210 @param jte_handle The environment to be manipulated.
211 @param compression_code Either "gzip" or "bzip2".
212 @return >0 means success, <=0 indicates failure
213 */
214 int libjte_set_compression(struct libjte_env *jte_handle,
215 char *compression_code);
216
217 /** Add a regular expression pattern to the list of excluded filenames.
218 The pattern will be tested against the filenames that are handed to
219 libjte_decide_file_jigdo() or libjte_begin_data_file().
220 @since 0.1.0
221 @param jte_handle The environment to be manipulated.
222 @param String for regcomp(3)
223 @return >0 means success, <=0 indicates failure
224 */
225 int libjte_add_exclude(struct libjte_env *jte_handle, char *pattern);
226
227 /** Add a regular expression pattern to the list of files which must be
228 found matching in the .md5 file.
229 The pattern will be tested against the filenames that are handed to
230 libjte_decide_file_jigdo() or libjte_begin_data_file() and do not find
231 a matching entry in the .md5 file. If it matches, then said two functions
232 will return error resp. perform exit() if this is enabled by
233 libjte_set_error_behavior().
234 Still supported in 2.0.0, but is now just an alias for
235 libjte_add_checksum_demand(handle, path) below
236 \deprecated since 2.0.0
237 @since 0.1.0
238 @param jte_handle The environment to be manipulated.
239 @param String for regcomp(3)
240 @return >0 means success, <=0 indicates failure
241 */
242 int libjte_add_md5_demand(struct libjte_env *jte_handle, char *pattern);
243
244 /** Add a regular expression pattern to the list of files which must be
245 found matching in the .checksum file.
246 The pattern will be tested against the filenames that are handed
247 to libjte_decide_file_jigdo() or libjte_begin_data_file() and do
248 not find a matching entry in the .checksum file. If it matches,
249 then said two functions will return error resp. perform exit() if
250 this is enabled by libjte_set_error_behavior().
251 @since 2.0.0
252 @param jte_handle The environment to be manipulated.
253 @param String for regcomp(3)
254 @return >0 means success, <=0 indicates failure
255 */
256 int libjte_add_checksum_demand(struct libjte_env *jte_handle, char *pattern);
257
258 /** Add a To=From pair to the list of mirror name mapping.
259 The pair will be split at the '=' character. The mirror_name submitted to
260 libjte_write_match_record() will be tested whether it begins by the From
261 string. If so, then this string will be replaced by the To string and a ':' character.
262 The resulting string will be used as data file name in the jigdo file.
263
264 libjte_decide_file_jigdo() gets the mirror_name from the matching line
265 in the .checksum file and hands it to the application.
266 libjte_begin_data_file() obtains the mirror name and processes it without
267 bothering the application.
268
269 @since 0.1.0
270 @param jte_handle The environment to be manipulated.
271 @param arg String of the form To=From
272 @return >0 means success, <=0 indicates failure
273 */
274 int libjte_add_mapping(struct libjte_env *jte_handle, char *arg);
275
276
277 /* ----------------------------- Operation --------------------------------- */
278
279 /** Start the production of jigdo and template file.
280 This is to be done after all parameters are set and before any payload
281 data are produced by the application.
282 @since 0.1.0
283 @param jte_handle The environment to be started.
284 @return >0 = ok
285 0 = error
286 -1 = would have called exit(1) if enabled
287 */
288 int libjte_write_header(struct libjte_env *jte_handle);
289
290
291 /** Finish the production of jigdo and template file.
292 This is to be done after all payload has been produced by the application
293 and processed by libjte, and before the libjte environment gets disposed.
294 @since 0.1.0
295 @param jte_handle The environment to be finished.
296 @return >0 = ok
297 0 = error
298 -1 = would have called exit(1) if enabled
299 */
300 int libjte_write_footer(struct libjte_env *jte_handle);
301
302
303 /* --------------------------- Data File APIs ---------------------------- */
304
305 /* There are two alternative ways how to process a single data file and its
306 content: Traditional and Simplified.
307 Choose either one.
308
309 CAUTION: Do not mix them !
310
311 */
312
313 /* ---------------------- Traditional Data File API ----------------------- */
314
315 /* This implements the way how genisoimage deals with single data files when
316 showing them to its built-in JTE.
317
318 When processing of a data file begins :
319
320 if (libjte_decide_file_jigdo(..., &mirror_name, md5) == 1) {
321 libjte_write_match_record(..., mirror_name, ..., md5);
322 write_unmatched_data = 0;
323 } else
324 write_unmatched_data = 1;
325
326 When a chunk of data content is written to the payload image :
327
328 if (write_unmatched_data)
329 libjte_write_unmatched(...);
330
331 Before calling libjte_write_footer() :
332
333 libjte_set_image_size(...);
334
335 */
336
337 /** Decide whether a data file shall be extracted, i.e. referred in the
338 template file and listed in the jigdo file, or whether its content
339 shall be written compressed into the template file.
340 \deprecated since 2.0.0, use libjte_decide_file_jigdo2() in preference.
341 @since 0.1.0
342 @param jte_handle The environment to be used.
343 @param filename The address to be used with fopen(filename, "r")
344 @param size Number of bytes in the data file
345 @param mirror_name Returns the name which shall be listed in the jigdo
346 file. This is NULL or allocated memory that has to
347 be disposed by free(3).
348 @param md5 May get filled by MD5 for libjte_write_match_record().
349 @return 0= use libjte_write_unmatched(),
350 1= use libjte_write_match_record()
351 -1= would have called exit(1) if enabled, e.g. if called
352 after saying "sha256" in
353 libjte_set_checksum_algorithm().
354 */
355 int libjte_decide_file_jigdo(struct libjte_env *jte_handle,
356 char *filename, off_t size, char **mirror_name,
357 unsigned char md5[16]);
358
359 /** Decide whether a data file shall be extracted, i.e. referred in the
360 template file and listed in the jigdo file, or whether its content
361 shall be written compressed into the template file.
362 @since 2.0.0
363 @param jte_handle The environment to be used.
364 @param filename The address to be used with fopen(filename, "r")
365 @param size Number of bytes in the data file
366 @param mirror_name Returns the name which shall be listed in the jigdo
367 file. This is NULL or allocated memory that has to
368 be disposed by free(3).
369 @param checksum May get filled by a checksum for libjte_write_match_record2().
370 The size of the needed buffer here varies
371 depending on the checksum chosen in
372 libjte_set_checksum_algorithm() and is passed
373 back by that function.
374 @return 0= use libjte_write_unmatched(),
375 1= use libjte_write_match_record()
376 -1= would have called exit(1) if enabled
377 */
378 int libjte_decide_file_jigdo2(struct libjte_env *jte_handle,
379 char *filename, off_t size, char **mirror_name,
380 unsigned char *checksum);
381
382 /** Register a list entry in the jigdo file and write a reference tag into
383 the template file. This is to be called if libjte_decide_file_jigdo()
384 returned 1.
385 \deprecated since 2.0.0, use libjte_write_match_record2() in preference.
386 @since 0.1.0
387 @param jte_handle The environment to be used.
388 @param filename The address to be used with fopen(filename, "r").
389 @param mirror_name The mirror_name returned by libjte_decide_file_jigdo().
390 @param sector_size An eventual byte address alignment which is achieved
391 in the payload image by padding file ends with zeros.
392 Submit 1 if no alignment is done. For ISO images: 2048.
393 @param size The number of bytes in the data file.
394 @param md5 The md5 buffer submitted to libjte_decide_file_jigdo().
395 @return >0 = ok
396 0 = error
397 -1 = would have called exit(1) if enabled, e.g. if called
398 after saying "sha256" in
399 libjte_set_checksum_algorithm().
400 */
401 int libjte_write_match_record(struct libjte_env *jte_handle,
402 char *filename, char *mirror_name, int sector_size,
403 off_t size, unsigned char md5[16]);
404
405 /** Register a list entry in the jigdo file and write a reference tag into
406 the template file. This is to be called if libjte_decide_file_jigdo()
407 returned 1.
408 @since 2.0.0
409 @param jte_handle The environment to be used.
410 @param filename The address to be used with fopen(filename, "r").
411 @param mirror_name The mirror_name returned by libjte_decide_file_jigdo().
412 @param sector_size An eventual byte address alignment which is achieved
413 in the payload image by padding file ends with zeros.
414 Submit 1 if no alignment is done. For ISO images: 2048.
415 @param size The number of bytes in the data file.
416 @param checksum The checksum buffer submitted to libjte_decide_file_jigdo2().
417 @return >0 = ok
418 0 = error
419 -1 = would have called exit(1) if enabled
420 */
421 int libjte_write_match_record2(struct libjte_env *jte_handle,
422 char *filename, char *mirror_name, int sector_size,
423 off_t size, unsigned char *checksum);
424
425 /** Write a payload data chunk into the template file. This is to be called
426 with any data file bytes if libjte_decide_file_jigdo{,2}() returned 0.
427 It is also to be called with any payload image bytes which are not content
428 of a data file.
429 @since 0.1.0
430 @param jte_handle The environment to be used.
431 @param buffer The memory buffer containing the payload bytes
432 @param size The block size within buffer. (1 is well ok.)
433 @param count The number of blocks of the given size within buffer.
434 @return >0 means success, <=0 indicates failure
435 */
436 /* @return >0 = ok
437 0 = error
438 -1 = would have called exit(1) if enabled
439 */
440 int libjte_write_unmatched(struct libjte_env *jte_handle, void *buffer,
441 int size, int count);
442
443 /** Before calling libjte_footer() submit the number of written payload bytes.
444 The Traditional Data File API does not keep track of this count.
445 @since 0.1.0
446 @param jte_handle The environment to be used.
447 @param image_size Number of bytes in the image.
448 @return >0 means success, <=0 indicates failure
449 */
450 int libjte_set_image_size(struct libjte_env *o, off_t image_size);
451
452
453 /* ------------------------- Simplified Data File API ---------------------- */
454
455 /* This implements the way how libisofs deals with single data files when
456 showing them to libjte. It does not demand from the application to memorize
457 the state of libjte decisions and parameters.
458 It rather shows any payload data to libjte and only marks the begin and
459 end of data file content.
460
461 When a chunk of bytes is written to the payload image :
462
463 libjte_show_data_chunk();
464
465 When processing of a data file begins :
466
467 libjte_begin_data_file();
468
469 When the content of a data file has been shown completely :
470
471 libjte_end_data_file();
472 */
473
474 /** Show a chunk of payload data to libjte which will decide whether to write
475 it into the template file or whether to ignore it, because it belongs to
476 a Jigdo extracted file.
477 @since 0.1.0
478 @param jte_handle The environment to be used.
479 @param buffer The memory buffer containing the payload bytes
480 @param size The block size within buffer. (1 is well ok.)
481 @param count The number of blocks of the given size within buffer.
482 @return >0 means success, <=0 indicates failure
483 */
484 int libjte_show_data_chunk(struct libjte_env *jte_handle,
485 void *buffer, int size, int count);
486
487 /** Tell libjte that the content of a data file is to be processed next.
488 libjte will decide whether to extract the file and list it in the jigdo
489 file, or whether to direct subsequent calls of libjte_show_data_chunk()
490 into the template file.
491 @param jte_handle The environment to be used.
492 @param filename The address to be used with fopen(filename, "r").
493 @param sector_size An eventual byte address alignment which is achieved
494 in the payload image by padding file ends with zeros.
495 Submit 1 if no alignment is done. For ISO images: 2048.
496 @param size The number of bytes in the data file.
497 @return >0 = ok
498 0 = error
499 -1 = would have called exit(1) if enabled
500 E.g. because a libjte_add_md5_demand() pattern matched
501 a file that shall not get extracted.
502 */
503 int libjte_begin_data_file(struct libjte_env *jte_handle, char *filename,
504 int sector_size, off_t size);
505
506 /** Tell libjte that all content of the previously announced data file has
507 been submitted to libjte_show_data_chunk().
508 libjte will direct the following calls of libjte_show_data_chunk() into
509 the template file.
510 @since 0.1.0
511 @param jte_handle The environment to be used.
512 @return >0 means success, <=0 indicates failure
513 */
514 int libjte_end_data_file(struct libjte_env *jte_handle);
515
516
517 /* ----------------- Message Reporting and Error Behavior ----------------- */
518
519 /** Define how libjte shall deliver its messages and whether it is allowed
520 to call exit() in hopeless situations.
521 @since 0.1.0
522 @param jte_handle The environment to be manipulated.
523 @param to_stderr If 0, append messages to the message list of the libjte
524 environment.
525 If 1 print messages directly to stderr. This is the
526 default.
527 @param with_exit If 1 perform exit(1); when encountering severe errors.
528 If 0 return -1 in such situations. This is the default.
529 @return >0 means success, <=0 indicates failure
530 */
531 int libjte_set_error_behavior(struct libjte_env *o,
532 int to_stderr, int with_exit);
533
534 /** Get the oldest pending message from the message list.
535 @since 0.1.0
536 @param jte_handle The environment to be manipulated.
537 @return Pointer to alloceted memory. Apply free() when no longer needed.
538 NULL means that no more message is available
539 */
540 char *libjte_get_next_message(struct libjte_env *o);
541
542 /** Dispose all pending messages after eventually printing them to stderr.
543 @since 0.1.0
544 @param jte_handle The environment to be manipulated.
545 @param flag bit0= print pending messages to stderr
546 bit1= eventually complain before printing messages
547 @return >0 means success, <=0 indicates failure
548 */
549 int libjte_clear_msg_list(struct libjte_env *o, int flag);
550
551 #endif /* LIBJTE_H_INCLUDED */
552