"Fossies" - the Fresh Open Source Software Archive 
Member "xorriso-1.5.4/libisoburn/libisoburn.h" (30 Jan 2021, 127913 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 "libisoburn.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 #ifndef LIBISOBURN_LIBISOBURN_H_
3 #define LIBISOBURN_LIBISOBURN_H_
4
5 /*
6 Lower level API definition of libisoburn.
7
8 Copyright 2007-2009 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
9 Copyright 2007-2021 Thomas Schmitt <scdbackup@gmx.net>
10 Provided under GPL version 2 or later.
11 */
12
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17 /** Overview
18
19 libisoburn is a frontend for libraries libburn and libisofs which enables
20 creation and expansion of ISO-9660 filesystems on all CD/DVD/BD media supported
21 by libburn. This includes media like DVD+RW, which do not support multi-session
22 management on media level and even plain disk files or block devices.
23
24 The price for that is thorough specialization on data files in ISO-9660
25 filesystem images. So libisoburn is not suitable for audio (CD-DA) or any
26 other CD layout which does not entirely consist of ISO-9660 sessions.
27
28 Note that there is a higher level of API: xorriso.h. One should not mix it
29 with the API calls of libisoburn.h, libisofs.h, and libburn.h.
30
31
32 Connector functions
33
34 libisofs and libburn do not depend on each other but share some interfaces
35 by which they can cooperate.
36 libisoburn establishes the connection between both modules by creating the
37 necessary interface objects and attaching them to the right places.
38
39
40 Wrapper functions
41
42 The principle of this frontend is that you may use any call of libisofs or
43 libburn unless it has a isoburn_*() wrapper listed in the following function
44 documentation.
45
46 E.g. call isoburn_initialize() rather than iso_init(); burn_initialize();
47 and call isoburn_drive_scan_and_grab() rather than burn_drive_scan_and_grab().
48 But you may call burn_disc_get_profile() directly if you want to display
49 the media type.
50
51 The wrappers will transparently provide the necessary emulations which
52 are appropriate for particular target drives and media states.
53 To learn about them you have to read both API descriptions: the one of
54 the wrapper and the one of the underlying libburn or libisofs call.
55
56 Macros BURN_* and functions burn_*() are documented in <libburn/libburn.h>
57 Macros ISO_* and functions iso_*() are documented in <libisofs/libisofs.h>
58
59
60 Usage model
61
62 There may be an input drive and an output drive. Either of them may be missing
63 with the consequence that no reading or no writing is possible.
64 Both drive roles can be fulfilled by the same drive.
65
66 Input can be a random access readable libburn drive:
67 optical media, regular files, block devices.
68 Output can be any writeable libburn drive:
69 writeable optical media in burner, writeable file objects (no directories).
70
71 libburn demands rw-permissions to drive device file or file object.
72
73 If the input drive provides a suitable ISO RockRidge image, then its tree
74 may be loaded into memory and can then be manipulated by libisofs API calls.
75 The loading is done by isoburn_read_image() under control of
76 struct isoburn_read_opts which the application obtains from libisoburn
77 and manipulates by the family of isoburn_ropt_set_*() functions.
78
79 Writing of result images is controlled by libisofs related parameters
80 in a struct isoburn_imgen_opts which the application obtains from libisoburn
81 and manipulates by the family of isoburn_igopt_set_*() functions.
82
83 All multi-session aspects are handled by libisoburn according to these
84 settings. The application does not have to analyze media state and write
85 job parameters. It rather states its desires which libisoburn tries to
86 fulfill, or else will refuse to start the write run.
87
88
89 Setup for Growing, Modifying or Blind Growing
90
91 The connector function family offers alternative API calls for performing
92 the setup for several alternative image generation strategies.
93
94 Growing:
95 If input and output drive are the same, then isoburn_prepare_disc() is to
96 be used. It will lead to an add-on session on appendable or overwritable
97 media with existing ISO image. With blank media it will produce a first
98 session.
99
100 Modifying:
101 If the output drive is not the input drive, and if it bears blank media
102 or overwritable without a valid ISO image, then one may produce a consolidated
103 image with old and new data. This will copy file data from an eventual input
104 drive with valid image, add any newly introduced data from the local
105 filesystem, and produce a first session on output media.
106 To prepare for such an image generation run, use isoburn_prepare_new_image().
107
108 Blind Growing:
109 This method reads the old image from one drive and writes the add-on session
110 to a different drive. That output drive is nevertheless supposed to
111 finally lead to the same medium from where the session was loaded. Usually it
112 will be stdio:/dev/fd/1 (i.e. stdout) being piped into some burn program
113 like with this classic gesture:
114 mkisofs -M $dev -C $msc1,$nwa | cdrecord -waiti dev=$dev
115 Blind growing is prepared by the call isoburn_prepare_blind_grow().
116 The input drive should be released immediately after this call in order
117 to allow the consumer of the output stream to access that drive for writing.
118
119 After either of these setups, some peripheral libburn drive parameter settings
120 like burn_write_opts_set_simulate(), burn_write_opts_set_multi(),
121 burn_drive_set_speed(), burn_write_opts_set_underrun_proof() should be made.
122 Do not set the write mode. It will be chosen by libisoburn so it matches job
123 and media state.
124
125 Writing the image
126
127 Then one may start image generation and write threads by isoburn_disc_write().
128 Progress may be watched at the output drive by burn_drive_get_status() and
129 isoburn_get_fifo_status().
130
131 At some time, the output drive will be BURN_DRIVE_IDLE indicating that
132 writing has ended.
133 One should inquire isoburn_drive_wrote_well() to learn about overall success.
134
135 Finally one must call isoburn_activate_session() which will complete any
136 eventual multi-session emulation.
137
138
139 Application Constraints
140
141 Applications shall include libisofs/libisofs.h , libburn/libburn.h and this
142 file itself: libisoburn/libisoburn.h .
143 They shall link with -lisofs -lburn -lisoburn or with the .o files emerging
144 from building those libraries from their sources.
145
146 Applications must use 64 bit off_t.
147 E.g. on 32-bit GNU/Linux by defining
148 #define _LARGEFILE_SOURCE
149 #define _FILE_OFFSET_BITS 64
150 The minimum requirement is to interface with the library by 64 bit signed
151 integers where libisofs.h or libisoburn.h prescribe off_t.
152 Failure to do so may result in surprising malfunction or memory faults.
153
154 Application files which include libisofs/libisofs.h or libisoburn/libisoburn.h
155 must provide definitions for uint32_t and uint8_t.
156 This can be achieved either:
157 - by using autotools which will define HAVE_STDINT_H or HAVE_INTTYPES_H
158 according to its ./configure tests,
159 - or by defining the macros HAVE_STDINT_H or HAVE_INTTYPES_H according
160 to the local situation,
161 - or by appropriately defining uint32_t and uint8_t by other means,
162 e.g. by including inttypes.h before including libisofs.h and libisoburn.h
163
164 */
165 #ifdef HAVE_STDINT_H
166 #include <stdint.h>
167 #else
168 #ifdef HAVE_INTTYPES_H
169 #include <inttypes.h>
170 #endif
171 #endif
172
173
174 /* Important: If you add a public API function then add its name to file
175 libisoburn/libisoburn.ver
176 */
177
178
179 /* API functions */
180
181
182 /** Initialize libisoburn, libisofs and libburn.
183 Wrapper for : iso_init() and burn_initialize()
184 @since 0.1.0
185 @param msg A character array for eventual messages (e.g. with errors)
186 @param flag Bitfield for control purposes (unused yet, submit 0)
187 @return 1 indicates success, 0 is failure
188 */
189 int isoburn_initialize(char msg[1024], int flag);
190
191
192 /** Check whether all features of header file libisoburn.h from the given
193 major.minor.micro revision triple can be delivered by the library version
194 which is performing this call.
195 An application of libisoburn can easily memorize the version of the
196 libisoburn.h header in its own code. Immediately after isoburn_initialize()
197 it should simply do this check:
198 if (! isoburn_is_compatible(isoburn_header_version_major,
199 isoburn_header_version_minor,
200 isoburn_header_version_micro, 0))
201 ...refuse to start the program with this dynamic library version...
202 @since 0.1.0
203 @param major obtained at build time
204 @param minor obtained at build time
205 @param micro obtained at build time
206 @param flag Bitfield for control purposes. Unused yet. Submit 0.
207 @return 1= library can work for caller
208 0= library is not usable in some aspects. Caller must restrict
209 itself to an earlier API version or must not use this library
210 at all.
211 */
212 int isoburn_is_compatible(int major, int minor, int micro, int flag);
213
214
215 /** Obtain the three release version numbers of the library. These are the
216 numbers encountered by the application when linking with libisoburn,
217 i.e. possibly not before run time.
218 Better do not base the fundamental compatibility decision of an application
219 on these numbers. For a reliable check use isoburn_is_compatible().
220 @since 0.1.0
221 @param major The maturity version (0 for now, as we are still learning)
222 @param minor The development goal version.
223 @param micro The development step version. This has an additional meaning:
224
225 Pare numbers indicate a version with frozen API. I.e. you can
226 rely on the same set of features to be present in all
227 published releases with that major.minor.micro combination.
228 Features of a pare release will stay available and ABI
229 compatible as long as the SONAME of libisoburn stays "1".
230 Currently there are no plans to ever change the SONAME.
231
232 Odd numbers indicate that API upgrades are in progress.
233 I.e. new features might be already present or they might
234 be still missing. Newly introduced features may be changed
235 incompatibly or even be revoked before release of a pare
236 version.
237 So micro revisions {1,3,5,7,9} should never be used for
238 dynamic linking unless the proper library match can be
239 guaranteed by external circumstances.
240
241 @return 1 success, <=0 might in future become an error indication
242 */
243 void isoburn_version(int *major, int *minor, int *micro);
244
245
246 /** The minimum version of libisofs to be used with this version of libisoburn
247 at compile time.
248 @since 0.1.0
249 */
250 #define isoburn_libisofs_req_major 1
251 #define isoburn_libisofs_req_minor 5
252 #define isoburn_libisofs_req_micro 4
253
254 /** The minimum version of libburn to be used with this version of libisoburn
255 at compile time.
256 @since 0.1.0
257 */
258 #define isoburn_libburn_req_major 1
259 #define isoburn_libburn_req_minor 5
260 #define isoburn_libburn_req_micro 4
261
262 /** The minimum compile time requirements of libisoburn towards libjte are
263 the same as of a suitable libisofs towards libjte.
264 So use these macros from libisofs.h :
265 iso_libjte_req_major
266 iso_libjte_req_minor
267 iso_libjte_req_micro
268 @since 0.6.4
269 */
270
271 /** The minimum version of libisofs to be used with this version of libisoburn
272 at runtime. This is checked already in isoburn_initialize() which will
273 refuse on outdated version. So this call is for information purposes after
274 successful startup only.
275 @since 0.1.0
276 @param major isoburn_libisofs_req_major as seen at build time
277 @param minor as seen at build time
278 @param micro as seen at build time
279 @return 1 success, <=0 might in future become an error indication
280 */
281 int isoburn_libisofs_req(int *major, int *minor, int *micro);
282
283
284 /** The minimum version of libjte to be used with this version of libisoburn
285 at runtime. The use of libjte is optional and depends on configure
286 tests. It can be prevented by ./configure option --disable-libjte .
287 This is checked already in isoburn_initialize() which will refuse on
288 outdated version. So this call is for information purposes after
289 successful startup only.
290 @since 0.6.4
291 */
292 int isoburn_libjte_req(int *major, int *minor, int *micro);
293
294
295 /** The minimum version of libburn to be used with this version of libisoburn
296 at runtime. This is checked already in isoburn_initialize() which will
297 refuse on outdated version. So this call is for information purposes after
298 successful startup only.
299 @since 0.1.0
300 @param major isoburn_libburn_req_major as seen at build time
301 @param minor as seen at build time
302 @param micro as seen at build time
303 @return 1 success, <=0 might in future become an error indication
304 */
305 int isoburn_libburn_req(int *major, int *minor, int *micro);
306
307
308 /** These three release version numbers tell the revision of this header file
309 and of the API it describes. They are memorized by applications at build
310 time.
311 @since 0.1.0
312 */
313 #define isoburn_header_version_major 1
314 #define isoburn_header_version_minor 5
315 #define isoburn_header_version_micro 4
316 /** Note:
317 Above version numbers are also recorded in configure.ac because libtool
318 wants them as parameters at build time.
319 For the library compatibility check, ISOBURN_*_VERSION in configure.ac
320 are not decisive. Only the three numbers here do matter.
321 */
322 /** Usage discussion:
323
324 Some developers of the libburnia project have differing
325 opinions how to ensure the compatibility of libraries
326 and applications.
327
328 It is about whether to use at compile time and at runtime
329 the version numbers isoburn_header_version_* provided here.
330 Thomas Schmitt advises to use them.
331 Vreixo Formoso advises to use other means.
332
333 At compile time:
334
335 Vreixo Formoso advises to leave proper version matching
336 to properly programmed checks in the the application's
337 build system, which will eventually refuse compilation.
338
339 Thomas Schmitt advises to use the macros defined here
340 for comparison with the application's requirements of
341 library revisions and to eventually break compilation.
342
343 Both advises are combinable. I.e. be master of your
344 build system and have #if checks in the source code
345 of your application, nevertheless.
346
347 At runtime (via *_is_compatible()):
348
349 Vreixo Formoso advises to compare the application's
350 requirements of library revisions with the runtime
351 library. This is to allow runtime libraries which are
352 young enough for the application but too old for
353 the lib*.h files seen at compile time.
354
355 Thomas Schmitt advises to compare the header
356 revisions defined here with the runtime library.
357 This is to enforce a strictly monotonous chain
358 of revisions from app to header to library,
359 at the cost of excluding some older libraries.
360
361 These two advises are mutually exclusive.
362
363 -----------------------------------------------------
364
365 For an implementation of the Thomas Schmitt approach,
366 see libisoburn/burn_wrap.c : isoburn_initialize()
367 This connects libisoburn as "application" with libisofs
368 as "library".
369
370 The compatible part of Vreixo Formoso's approach is implemented
371 in configure.ac LIBBURN_REQUIRED, LIBISOFS_REQUIRED.
372 In isoburn_initialize() it would rather test by
373 iso_lib_is_compatible(isoburn_libisofs_req_major,...
374 than by
375 iso_lib_is_compatible(iso_lib_header_version_major,...
376 and would leave out the ugly compile time traps.
377
378 */
379
380
381 /** Announce to the library an application provided method for immediate
382 delivery of messages. It is used when no drive is affected directly or
383 if the drive has no own msgs_submit() method attached by
384 isoburn_drive_set_msgs_submit.
385 If no method is preset or if the method is set to NULL then libisoburn
386 delivers its messages through the message queue of libburn.
387 @param msgs_submit The function call which implements the method
388 @param submit_handle Handle to be used as first argument of msgs_submit
389 @param submit_flag Flag to be used as last argument of msgs_submit
390 @param flag Unused yet, submit 0
391 @since 0.2.0
392 */
393 int isoburn_set_msgs_submit(int (*msgs_submit)(void *handle, int error_code,
394 char msg_text[], int os_errno,
395 char severity[], int flag),
396 void *submit_handle, int submit_flag, int flag);
397
398
399 /** Acquire a target drive by its filesystem path or libburn persistent
400 address.
401 Wrapper for: burn_drive_scan_and_grab()
402 @since 0.1.0
403 @param drive_infos On success returns a one element array with the drive
404 (cdrom/burner). Thus use with driveno 0 only. On failure
405 the array has no valid elements at all.
406 The returned array should be freed via burn_drive_info_free()
407 when the drive is no longer needed. But before this is done
408 one has to call isoburn_drive_release(drive_infos[0].drive).
409 @param adr The persistent address of the desired drive or the path
410 to a file object.
411 @param load 1 attempt to load the disc tray. 0 no attempt,rather failure.
412 @return 1 = success , 0 = drive not found , <0 = other error
413 */
414 int isoburn_drive_scan_and_grab(struct burn_drive_info *drive_infos[],
415 char* adr, int load);
416
417
418 /** Acquire a target drive by its filesystem path or libburn persistent
419 address. This is a modern successor of isoburn_drive_scan_and_grab().
420 Wrapper for: burn_drive_scan_and_grab()
421 @since 0.1.2
422 @param drive_infos On success returns a one element array with the drive
423 (cdrom/burner). Thus use with driveno 0 only. On failure
424 the array has no valid elements at all.
425 The returned array should be freed via burn_drive_info_free()
426 when the drive is no longer needed. But before this is done
427 one has to call isoburn_drive_release(drive_infos[0].drive).
428 @param adr The persistent address of the desired drive or the path
429 to a file object.
430 @param flag bit0= attempt to load the disc tray.
431 Else: failure if not loaded.
432 bit1= regard overwritable media as blank
433 bit2= if the drive is a regular disk file:
434 truncate it to the write start address when writing
435 begins
436 bit3= if the drive reports a read-only profile try to read
437 table of content by scanning for ISO image headers.
438 (depending on media type and drive this might
439 help or it might make the resulting toc even worse)
440 bit4= do not emulate table of content on overwritable media
441 bit5= ignore ACL from external filesystems
442 bit6= ignore POSIX Extended Attributes from external
443 filesystems (xattr)
444 bit7= pretend read-only profile and scan for table of content
445 bit8= re-assess already acquired (*drive_infos)[0] rather
446 than acquiring adr
447 @since 1.1.8
448 bit9= when scanning for ISO 9660 sessions by bit3:
449 Do not demand a valid superblock at LBA 0, ignore it in
450 favor of one at LBA 32, and scan until end of medium.
451 @since 1.2.6
452 bit10= if not bit6: accept all xattr namespaces from external
453 filesystems, not only "user.".
454 @since 1.5.0
455 @return 1 = success , 0 = drive not found , <0 = other error
456
457 Please excuse the typo "aquire" in the function name.
458 */
459 int isoburn_drive_aquire(struct burn_drive_info *drive_infos[],
460 char* adr, int flag);
461
462 /** Acquire a drive from the burn_drive_info[] array which was obtained by
463 a previous call of burn_drive_scan().
464 Wrapper for: burn_drive_grab()
465 @since 0.1.0
466 @param drive The drive to grab. E.g. drive_infos[1].drive .
467 Call isoburn_drive_release(drive) when it it no longer needed.
468 @param load 1 attempt to load the disc tray. 0 no attempt, rather failure.
469 @return 1 success, <=0 failure
470 */
471 int isoburn_drive_grab(struct burn_drive *drive, int load);
472
473
474 /** Attach to a drive an application provided method for immediate
475 delivery of messages.
476 If no method is set or if the method is set to NULL then libisoburn
477 delivers messages of the drive through the global msgs_submit() method
478 set by isoburn_set_msgs_submiti() or by the message queue of libburn.
479 @since 0.2.0
480 @param d The drive to which this function, handle and flag shall apply
481 @param msgs_submit The function call which implements the method
482 @param submit_handle Handle to be used as first argument of msgs_submit
483 @param submit_flag Flag to be used as last argument of msgs_submit
484 @param flag Unused yet, submit 0
485 */
486 int isoburn_drive_set_msgs_submit(struct burn_drive *d,
487 int (*msgs_submit)(void *handle, int error_code,
488 char msg_text[], int os_errno,
489 char severity[], int flag),
490 void *submit_handle, int submit_flag, int flag);
491
492
493 /** Inquire the medium status. Expect the whole spectrum of libburn BURN_DISC_*
494 with multi-session media. Emulated states with random access media are
495 BURN_DISC_BLANK and BURN_DISC_APPENDABLE.
496 Wrapper for: burn_disc_get_status()
497 @since 0.1.0
498 @param drive The drive to inquire.
499 @return The status of the drive, or what kind of disc is in it.
500 Note: BURN_DISC_UNGRABBED indicates wrong API usage
501 */
502 #ifdef __cplusplus
503 enum burn::burn_disc_status isoburn_disc_get_status(struct burn_drive *drive);
504 #else
505 enum burn_disc_status isoburn_disc_get_status(struct burn_drive *drive);
506 #endif
507
508
509 /** Sets the medium status to BURN_DISC_FULL unconditionally.
510 @since 1.3.8
511 @param drive The drive with the medium to be handled as if it was closed.
512 @
513 */
514 int isoburn_disc_pretend_full_uncond(struct burn_drive *drive);
515
516
517 /** Tells whether the medium can be treated by isoburn_disc_erase().
518 Wrapper for: burn_disc_erasable()
519 @since 0.1.0
520 @param d The drive to inquire.
521 @return 0=not erasable , else erasable
522 */
523 int isoburn_disc_erasable(struct burn_drive *d);
524
525
526 /** Mark the medium as blank. With multi-session media this will call
527 burn_disc_erase(). With random access media, an eventual ISO-9660
528 filesystem will get invalidated by altering its start blocks on the medium.
529 In case of success, the medium is in status BURN_DISC_BLANK afterwards.
530 Wrapper for: burn_disc_erase()
531 @since 0.1.0
532 @param drive The drive with the medium to erase.
533 @param fast 1=fast erase, 0=thorough erase
534 With DVD-RW, fast erase yields media incapable of multi-session.
535 */
536 void isoburn_disc_erase(struct burn_drive *drive, int fast);
537
538
539 /** Set up isoburn_disc_get_msc1() to return a fabricated value.
540 This makes only sense between acquiring the drive and reading the
541 image. After isoburn_read_image() it will confuse the coordination
542 of libisoburn and libisofs.
543 Note: Sessions and tracks are counted beginning with 1, not with 0.
544 @since 0.1.6
545 @param d The drive where msc1 is to be set
546 @param adr_mode Determines how to interpret adr_value and to set msc1.
547 If adr_value shall represent a number then decimal ASCII
548 digits are expected.
549 0= start lba of last session in TOC, ignore adr_value
550 1= start lba of session number given by adr_value
551 2= start lba of track number given by adr_value
552 3= adr_value itself is the lba to be used
553 4= start lba of last session with volume id
554 given by adr_value
555 @param adr_value A string describing the value to be eventually used.
556 @param flag Bitfield for control purposes.
557 bit0= @since 0.2.2
558 with adr_mode 3: adr_value might be 16 blocks too high
559 (e.g. -C stemming from growisofs). Probe for ISO head
560 at adr_value-16 and eventually adjust setting.
561 bit1= insist in seeing a disc object with at least one session
562 bit2= with adr_mode 4: use adr_value as regular expression
563 */
564 int isoburn_set_msc1(struct burn_drive *d, int adr_mode, char *adr_value,
565 int flag);
566
567
568 /* ----------------------------------------------------------------------- */
569 /*
570
571 Wrappers for emulation of TOC on overwritable media
572
573 Media which match the overwritable usage model lack of a history of sessions
574 and tracks. libburn will not even hand out a burn_disc object for them and
575 always declare them blank. libisoburn checks for a valid ISO filesystem
576 header at LBA 0 and eventually declares them appendable.
577 Nevertheless one can only determine an upper limit of the size of the overall
578 image (by isoburn_get_min_start_byte()) but not a list of stored sessions
579 and their LBAs, as it is possible with true multi-session media.
580
581 The following wrappers add the capability to obtain a session and track TOC
582 from emulated multi-session images on overwritables if the first session
583 was written by libisoburn-0.1.6 or later (i.e. with a header copy at LBA 32).
584
585 Be aware that the structs emitted by these isoburn calls are not compatible
586 with the libburn structs. I.e. you may use them only with isoburn_toc_*
587 calls.
588 isoburn_toc_disc needs to be freed after use. isoburn_toc_session and
589 isoburn_toc_track vanish together with their isoburn_toc_disc.
590 */
591
592 /* Opaque handles to media, session, track */
593 struct isoburn_toc_disc;
594 struct isoburn_toc_session;
595 struct isoburn_toc_track;
596
597
598 /** Obtain a master handle for the table of content.
599 This handle governs allocated resources which have to be released by
600 isoburn_toc_disc_free() when no longer needed.
601 Wrapper for: burn_drive_get_disc()
602 @since 0.1.6
603 @param d The drive with the medium to inspect
604 @return NULL in case there is no content info, else it is a valid handle
605 */
606 struct isoburn_toc_disc *isoburn_toc_drive_get_disc(struct burn_drive *d);
607
608
609 /** Tell the number of 2048 byte blocks covered by the table of content.
610 This number includes the eventual gaps between sessions and tracks.
611 So this call is not really a wrapper for burn_disc_get_sectors().
612 @since 0.1.6
613 @param disc The master handle of the medium
614 @return Number of blocks, <=0 indicates unknown or unreadable state
615 */
616 int isoburn_toc_disc_get_sectors(struct isoburn_toc_disc *disc);
617
618
619 /** Get the array of session handles and the number of complete sessions
620 from the table of content.
621 The result array contains *num + isoburn_toc_disc_get_incmpl_sess()
622 elements. All above *num are incomplete sessions.
623 Typically there is at most one incomplete session with no track.
624 Wrapper for: burn_disc_get_sessions()
625 @since 0.1.6
626 @param disc The master handle of the medium
627 @param num returns the number of sessions in the array
628 @return the address of the array of session handles
629 */
630 struct isoburn_toc_session **isoburn_toc_disc_get_sessions(
631 struct isoburn_toc_disc *disc, int *num);
632
633
634 /** Obtain the number of incomplete sessions which are recorded in the
635 result array of isoburn_toc_disc_get_sessions() after the complete
636 sessions. See above.
637 @since 1.2.8
638 @param disc The master handle of the medium
639 @return the number of incomplete sessions
640 */
641 int isoburn_toc_disc_get_incmpl_sess(struct isoburn_toc_disc *disc);
642
643
644 /** Tell the number of 2048 byte blocks covered by a particular session.
645 Wrapper for: burn_session_get_sectors()
646 @since 0.1.6
647 @param s The session handle
648 @return number of blocks, <=0 indicates unknown or unreadable state
649 */
650 int isoburn_toc_session_get_sectors(struct isoburn_toc_session *s);
651
652
653 /** Obtain a copy of the entry which describes the end of a particular session.
654 Wrapper for: burn_session_get_leadout_entry()
655 @since 0.1.6
656 @param s The session handle
657 @param entry A pointer to memory provided by the caller. It will be filled
658 with info according to struct burn_toc_entry as defined
659 in libburn.h
660 */
661 void isoburn_toc_session_get_leadout_entry(struct isoburn_toc_session *s,
662 struct burn_toc_entry *entry);
663
664
665 /** Get the array of track handles from a particular session.
666 Wrapper for: burn_session_get_tracks()
667 @since 0.1.6
668 @param s The session handle
669 @param num returns the number of tracks in the array
670 @return the address of the array of track handles,
671 NULL if no tracks are registered with session s
672 */
673 struct isoburn_toc_track **isoburn_toc_session_get_tracks(
674 struct isoburn_toc_session *s, int *num);
675
676
677 /** Obtain a copy of the entry which describes a particular track.
678 Wrapper for: burn_track_get_entry()
679 @since 0.1.6
680 @param t The track handle
681 @param entry A pointer to memory provided by the caller. It will be filled
682 with info according to struct burn_toc_entry as defined
683 in libburn.h
684 */
685 void isoburn_toc_track_get_entry(struct isoburn_toc_track *t,
686 struct burn_toc_entry *entry);
687
688
689 /** Obtain eventual ISO image parameters of an emulated track. This info was
690 gained with much effort and thus gets cached in the track object.
691 If this call returns 1 then one can save a call of isoburn_read_iso_head()
692 with return mode 1 which could cause an expensive read operation.
693 @since 0.4.0
694 @param t The track handle
695 @param start_lba Returns the start address of the ISO session
696 @param image_blocks Returns the number of 2048 bytes blocks
697 @param volid Caller provided memory for the volume id
698 @param flag unused yet, submit 0
699 @return 0= not an emulated ISO session , 1= reply is valid
700 */
701 int isoburn_toc_track_get_emul(struct isoburn_toc_track *t, int *start_lba,
702 int *image_blocks, char volid[33], int flag);
703
704
705
706 /** Release the memory associated with a master handle of a medium.
707 The handle is invalid afterwards and may not be used any more.
708 Wrapper for: burn_disc_free()
709 @since 0.1.6
710 @param disc The master handle of the medium
711 */
712 void isoburn_toc_disc_free(struct isoburn_toc_disc *disc);
713
714
715 /** Try whether the data at the given address look like a ISO 9660
716 image header and obtain its alleged size. Depending on the info mode
717 one other string of text information can be retrieved too.
718 @since 0.1.6
719 @param d The drive with the medium to inspect
720 @param lba The block number from where to read
721 @param image_blocks Returns the number of 2048 bytes blocks in the session
722 @param info Caller provided memory, enough to take possible info reply
723 @param flag bit0-7: info return mode
724 0= do not return anything in info (do not even touch it)
725 1= copy volume id to info (info needs 33 bytes)
726 2= @since 0.2.2 :
727 copy 64 kB header to info (needs 65536 bytes)
728 bit13= @since 0.2.2:
729 Do not read head from medium but use first 64 kB from
730 info.
731 In this case it is permissible to submit d == NULL.
732 bit14= check both half buffers (not only second)
733 return 2 if found in first block
734 bit15= return -1 on read error
735 @return >0 seems to be a valid ISO image, 0 format not recognized, <0 error
736 */
737 int isoburn_read_iso_head(struct burn_drive *d, int lba,
738 int *image_blocks, char *info, int flag);
739
740
741 /** Try to convert the given entity address into various entity addresses
742 which would describe it.
743 Note: Sessions and tracks are counted beginning with 1, not with 0.
744 @since 0.3.2
745 @param d The drive where msc1 is to be set
746 @param adr_mode Determines how to interpret the input adr_value.
747 If adr_value shall represent a number then decimal ASCII
748 digits are expected.
749 0= start lba of last session in TOC, ignore adr_value
750 1= start lba of session number given by adr_value
751 2= start lba of track given number by adr_value
752 3= adr_value itself is the lba to be used
753 4= start lba of last session with volume id
754 given by adr_value
755 @param adr_value A string describing the value to be eventually used.
756 @param lba returns the block address of the entity, -1 means invalid
757 @param track returns the track number of the entity, -1 means invalid
758 @param session returns the session number of the entity, -1 means invalid
759 @param volid returns the volume id of the entity if it is a ISO session
760 @param flag Bitfield for control purposes.
761 bit2= with adr_mode 4: use adr_value as regular expression
762 @return <=0 error , 1 ok, ISO session, 2 ok, not an ISO session
763 */
764 int isoburn_get_mount_params(struct burn_drive *d,
765 int adr_mode, char *adr_value,
766 int *lba, int *track, int *session,
767 char volid[33], int flag);
768
769
770 /* ----------------------------------------------------------------------- */
771 /*
772
773 Options for image reading.
774
775 An application shall create an option set object by isoburn_ropt_new(),
776 program it by isoburn_ropt_set_*(), use it with isoburn_read_image(),
777 and finally delete it by isoburn_ropt_destroy().
778
779 */
780 /* ----------------------------------------------------------------------- */
781
782 struct isoburn_read_opts;
783
784 /** Produces a set of image read options, initialized with default values.
785 @since 0.1.0
786 @param o the newly created option set object
787 @param flag Bitfield for control purposes. Submit 0 for now.
788 @return 1=ok , <0 = failure
789 */
790 int isoburn_ropt_new(struct isoburn_read_opts **o, int flag);
791
792
793 /** Deletes an option set which was created by isoburn_ropt_new().
794 @since 0.1.0
795 @param o The option set to work on
796 @param flag Bitfield for control purposes. Submit 0 for now.
797 @return 1= **o destroyed , 0= *o was already NULL (harmless)
798 */
799 int isoburn_ropt_destroy(struct isoburn_read_opts **o, int flag);
800
801 /** Sets the size and granularity of the cache which libisoburn provides to
802 libisofs for reading of ISO image data. This cache consists of several
803 tiles which are buffers of a given size. The ISO image is divided into
804 virtual tiles of that size. A cache tile may hold an in-memory copy
805 of such a virtual image tile.
806 When libisofs requests to read a block, then first the cache is inquired
807 whether it holds that block. If not, then the block is read via libburn
808 together with its neighbors in their virtual image tile into a free
809 cache tile. If no cache tile is free, then the one will be re-used which
810 has the longest time of not being hit by a read attempt.
811
812 A larger cache might speed up image loading by reducing the number of
813 libburn read calls on the directory tree. It might also help with
814 reading the content of many small files, if for some reason it is not an
815 option to sort access by LBA.
816 Caching will not provide much benefit with libburn "stdio:" drives,
817 because the operating system is supposed to provide the same speed-up
818 in a more flexible way.
819
820 @since 1.2.2
821 @param o The option set to work on.
822 It is permissible to submit NULL in order to just
823 have the parameters tested.
824 @param cache_tiles Number of tiles in the cache. Not less than 1.
825 Default is 32.
826 @param tile_blocks Number of blocks per tile. Must be a power of 2.
827 Default is 32.
828 cache_tiles * tile_blocks * 2048 must not exceed
829 1073741824 (= 1 GiB).
830 @param flag Bitfield for control purposes. Unused yet. Submit 0.
831 @return <=0 error , >0 ok
832 */
833 int isoburn_ropt_set_data_cache(struct isoburn_read_opts *o,
834 int cache_tiles, int tile_blocks, int flag);
835
836 /** Inquire the current settings of isoburn_set_data_cache().
837 @since 1.2.2
838 @param o The option set to work on.
839 NULL has the same effect as flag bit0.
840 @param cache_tiles Will return the number of tiles in the cache.
841 @param tile_blocks Will return the number of blocks per tile.
842 @param set_flag Will return control bits. None are defined yet.
843 @param flag Bitfield for control purposes
844 bit0= return default values rather than current ones
845 @return <=0 error , >0 reply is valid
846 */
847 int isoburn_ropt_get_data_cache(struct isoburn_read_opts *o,
848 int *cache_tiles, int *tile_blocks,
849 int *set_flag, int flag);
850
851
852 /** Which existing ISO 9660 extensions in the image to read or not to read.
853 Whether to read the content of an existing image at all.
854 The bits can be combined by | and inquired by &.
855 @since 0.1.0
856 @param ext Bitfield:
857 bit0= norock
858 Do not read Rock Ridge extensions
859 bit1= nojoliet
860 Do not read Joliet extensions
861 bit2= noiso1999
862 Do not read ISO 9660:1999 enhanced tree
863 bit3= preferjoliet
864 When both Joliet and RR extensions are present, the RR
865 tree is used. If you prefer using Joliet, set this to 1.
866 bit4= pretend_blank
867 Always create empty image.Ignore any image on input drive.
868 bit5= noaaip
869 @since 0.3.4
870 Do not load AAIP information from image. This information
871 eventually contains ACL or XFS-style Extended Attributes.
872 bit6= noacl
873 @since 0.3.4
874 Do not obtain ACL from external filesystem objects (e.g.
875 local filesystem files).
876 bit7= noea
877 @since 0.3.4
878 Do not obtain XFS-style Extended Attributes from external
879 filesystem objects (e.g. local filesystem files).
880 bit8= noino
881 @since 0.4.0
882 Do not load eventual inode numbers from RRIP entry PX,
883 but generate a new unique inode number for each imported
884 IsoNode object.
885 PX inode numbers mark families of hardlinks by giving all
886 family members the same inode number. libisofs keeps the
887 PX inode numbers unaltered when IsoNode objects get
888 written into an ISO image.
889 bit9= nomd5
890 @since 0.4.2
891 Do not load the possibly present MD5 checksum array.
892 Do not check possibly present session_md5 tags.
893 bit10= nomd5tag
894 @since 1.0.4
895 Do not check session_md5 tags although bit9
896 is not set.
897 bit11= do_ecma119_map
898 @since 1.4.2
899 Set iso_read_opts_set_ecma119_map() to map_mode rather
900 than relying on the default setting of libisofs.
901 bit12 - bit13= map_mode
902 @since 1.4.2
903 How to convert file names if neither Rock Ridge nor
904 Joliet names are present and acceptable.
905 0 = unmapped: Take name as recorded in ECMA-119 directory
906 record (not suitable for writing them to
907 a new ISO filesystem)
908 1 = stripped: Like unmapped, but strip off trailing ";1"
909 or ".;1"
910 2 = uppercase: Like stripped, but map {a-z} to {A-Z}
911 3 = lowercase: Like stripped, but map {A-Z} to {a-z}
912 bit14= do_joliet_map
913 @since 1.5.4
914 Set iso_read_opts_set_joliet_map() to joliet_map_mode
915 rather than relying on the default setting of libisofs.
916 bit15= joliet_map_mode
917 @since 1.5.4
918 How to convert Joliet file names.
919 0 = unmapped: Take name as recorded in Joliet directory
920 record (not suitable for writing them to
921 a new ISO filesystem)
922 1 = stripped: strip off trailing ";1" or ".;1"
923
924 @return 1 success, <=0 failure
925 */
926 #define isoburn_ropt_norock 1
927 #define isoburn_ropt_nojoliet 2
928 #define isoburn_ropt_noiso1999 4
929 #define isoburn_ropt_preferjoliet 8
930 #define isoburn_ropt_pretend_blank 16
931 #define isoburn_ropt_noaaip 32
932 #define isoburn_ropt_noacl 64
933 #define isoburn_ropt_noea 128
934 #define isoburn_ropt_noino 256
935 #define isoburn_ropt_nomd5 512
936 #define isoburn_ropt_nomd5tag 1024
937 #define isoburn_ropt_map_unmapped ( 2048 | 0 )
938 #define isoburn_ropt_map_stripped ( 2048 | 4096 )
939 #define isoburn_ropt_map_uppercase ( 2048 | 8192 )
940 #define isoburn_ropt_map_lowercase ( 2048 | 12288 )
941 #define isoburn_ropt_joliet_unmapped ( 16384 | 0)
942 #define isoburn_ropt_joliet_stripped ( 16384 | 32768)
943
944 int isoburn_ropt_set_extensions(struct isoburn_read_opts *o, int ext);
945 int isoburn_ropt_get_extensions(struct isoburn_read_opts *o, int *ext);
946
947
948 /** Default attributes to use if no RockRidge extension gets loaded.
949 @since 0.1.0
950 @param o The option set to work on
951 @param uid user id number (see /etc/passwd)
952 @param gid group id number (see /etc/group)
953 @param mode permissions (not file type) as of man 2 stat.
954 With directories, r-permissions will automatically imply
955 x-permissions. See isoburn_ropt_set_default_dirperms() below.
956 @return 1 success, <=0 failure
957 */
958 int isoburn_ropt_set_default_perms(struct isoburn_read_opts *o,
959 uid_t uid, gid_t gid, mode_t mode);
960 int isoburn_ropt_get_default_perms(struct isoburn_read_opts *o,
961 uid_t *uid, gid_t *gid, mode_t *mode);
962
963 /** Default attributes to use on directories if no RockRidge extension
964 gets loaded.
965 Above call isoburn_ropt_set_default_perms() automatically adds
966 x-permissions to r-permissions for directories. This call here may
967 be done afterwards to set independent permissions for directories,
968 especially to override the automatically added x-permissions.
969 @since 0.1.0
970 @param o The option set to work on
971 @param mode permissions (not file type) as of man 2 stat.
972 @return 1 success, <=0 failure
973 */
974 int isoburn_ropt_set_default_dirperms(struct isoburn_read_opts *o,
975 mode_t mode);
976 int isoburn_ropt_get_default_dirperms(struct isoburn_read_opts *o,
977 mode_t *mode);
978
979
980 /** Set the character set for reading RR file names from ISO images.
981 @since 0.1.0
982 @param o The option set to work on
983 @param input_charset Set this to NULL to use the default locale charset
984 For selecting a particular character set, submit its
985 name, e.g. as listed by program iconv -l.
986 Example: "UTF-8".
987 @return 1 success, <=0 failure
988 */
989 int isoburn_ropt_set_input_charset(struct isoburn_read_opts *o,
990 char *input_charset);
991 int isoburn_ropt_get_input_charset(struct isoburn_read_opts *o,
992 char **input_charset);
993
994
995 /**
996 Enable or disable methods to automatically choose an input charset.
997 This eventually overrides the name set via isoburn_ropt_set_input_charset()
998 @since 0.3.8
999 @param o The option set to work on
1000 @param mode Bitfield for control purposes:
1001 bit0= set the input character set automatically from
1002 attribute "isofs.cs" of root directory.
1003 Submit any other bits with value 0.
1004 @return 1 success, <=0 failure
1005 */
1006 int isoburn_ropt_set_auto_incharset(struct isoburn_read_opts *o, int mode);
1007 int isoburn_ropt_get_auto_incharset(struct isoburn_read_opts *o, int *mode);
1008
1009
1010 /** Control an offset to be applied to all block address pointers in the ISO
1011 image in order to compensate for an eventual displacement of the image
1012 relative to the start block address for which it was produced.
1013 E.g. if track number 2 from CD gets copied into a disk file and shall then
1014 be loaded as ISO filesystem, then the directory tree and all data file
1015 content of the track copy will become readable by setting the track start
1016 address as displacement and -1 as displacement_sign.
1017 Data file content outside the track will of course not be accessible and
1018 eventually produce read errors.
1019 @since 0.6.6
1020 @param o The option set to work on
1021 @param displacement 0 or a positive number
1022 @param displacement_sign Determines whether to add or subtract
1023 displacement to block addresses before applying
1024 them to the storage object for reading:
1025 +1 = add , -1= subtract , else keep unaltered
1026 */
1027 int isoburn_ropt_set_displacement(struct isoburn_read_opts *o,
1028 uint32_t displacement, int displacement_sign);
1029 int isoburn_ropt_get_displacement(struct isoburn_read_opts *o,
1030 uint32_t *displacement, int *displacement_sign);
1031
1032 /* If you get here because of a compilation error like
1033
1034 /usr/include/libisoburn/libisoburn.h:895: error:
1035 expected declaration specifiers or '...' before 'uint32_t'
1036
1037 then see above paragraph "Application Constraints" about the definition
1038 of uint32_t.
1039 */
1040
1041 /** Set the name truncation mode and the maximum name length for imported
1042 file objects.
1043 @since 1.4.2
1044 @param o The option set to work on
1045 @param mode 0= Do not truncate but throw error
1046 ISO_RR_NAME_TOO_LONG if a file name
1047 is longer than parameter length.
1048 1= Truncate to length and overwrite the last
1049 32 bytes of that length by the hex
1050 representation of the MD5 of the whole
1051 oversized name.
1052 Potential incomplete UTF-8 characters will
1053 get their leading bytes replaced by '_'.
1054 This is the default.
1055 @param length Maximum byte count of a file name. Permissible
1056 values are 64 to 255. Default is 255.
1057
1058 */
1059 int isoburn_ropt_set_truncate_mode(struct isoburn_read_opts *o,
1060 int mode, int length);
1061 int isoburn_ropt_get_truncate_mode(struct isoburn_read_opts *o,
1062 int *mode, int *length);
1063
1064
1065 /** After calling function isoburn_read_image() there are information
1066 available in the option set about the size and the available extra trees
1067 and extensions in the ISO filesystem.
1068 This info can be obtained as bits in parameter has_what. Like:
1069 joliet_available = (has_what & isoburn_ropt_has_joliet);
1070 @since 0.1.0
1071 @param o The option set to work on
1072 @param size Number of image data blocks, 2048 bytes each.
1073 @param has_what Bitfield:
1074 bit0= has_rockridge
1075 RockRidge extension info is available in the ISO 9660 tree
1076 (POSIX filesystem)
1077 bit1= has_joliet
1078 Joliet tree is available (suitable for MS-Windows)
1079 bit2= has_iso1999
1080 ISO version 2 Enhanced Volume Descriptor aka ISO 9660:1999
1081 and its tree is available. This is rather exotic.
1082 bit3= has_el_torito
1083 El-Torito boot record is present
1084 @return 1 success, <=0 failure
1085 */
1086 #define isoburn_ropt_has_rockridge 1
1087 #define isoburn_ropt_has_joliet 2
1088 #define isoburn_ropt_has_iso1999 4
1089 #define isoburn_ropt_has_el_torito 8
1090
1091 int isoburn_ropt_get_size_what(struct isoburn_read_opts *o,
1092 uint32_t *size, int *has_what);
1093
1094 /* ts A90122 */
1095 /* >>> to be implemented:
1096 #define isoburn_ropt_has_acl 64
1097 #define isoburn_ropt_has_ea 128
1098 */
1099
1100
1101 /** After calling function isoburn_read_image() there are information
1102 available in the option set about which tree was used for image loading
1103 and whether Rock Ridge information was actually used.
1104 @since 1.5.4
1105 @param o The option set to work on
1106 @param tree The tree which was loaded:
1107 0= ISO 9660 , 1 = Joliet , 2 = ISO 9660:1999
1108 @param rr 1= Rock Ridge information was used, 0 = No Rock Ridge was used
1109 @return 1 success, <=0 failure
1110 */
1111 int isoburn_ropt_get_tree_loaded(struct isoburn_read_opts *o,
1112 int *tree, int *rr);
1113
1114
1115 /* ----------------------------------------------------------------------- */
1116 /* End of Options for image reading */
1117 /* ----------------------------------------------------------------------- */
1118
1119 /* ----------------------------------------------------------------------- */
1120 /*
1121
1122 Options for image generation by libisofs and image transport to libburn.
1123
1124 An application shall create an option set by isoburn_igopt_new(),
1125 program it by isoburn_igopt_set_*(), use it with either
1126 isoburn_prepare_new_image() or isoburn_prepare_disc(), and finally delete
1127 it by isoburn_igopt_destroy().
1128
1129 */
1130 /* ----------------------------------------------------------------------- */
1131
1132 struct isoburn_imgen_opts;
1133
1134 /** Produces a set of generation and transfer options, initialized with default
1135 values.
1136 @since 0.1.0
1137 @param o the newly created option set object
1138 @param flag Bitfield for control purposes. Submit 0 for now.
1139 @return 1=ok , <0 = failure
1140 */
1141 int isoburn_igopt_new(struct isoburn_imgen_opts **o, int flag);
1142
1143
1144 /** Deletes an option set which was created by isoburn_igopt_new().
1145 @since 0.1.0
1146 @param o The option set to give up
1147 @param flag Bitfield for control purposes. Submit 0 for now.
1148 @return 1= **o destroyed , 0= *o was already NULL (harmless)
1149 */
1150 int isoburn_igopt_destroy(struct isoburn_imgen_opts **o, int flag);
1151
1152
1153 /** ISO level to write at.
1154 @since 0.1.0
1155 @param o The option set to work on
1156 @param level is a term of the ISO 9660 standard. It should be one of:
1157 1= filenames restricted to form 8.3
1158 2= filenames allowed up to 31 characters
1159 3= file content may be larger than 4 GB - 1.
1160 @return 1 success, <=0 failure
1161 */
1162 int isoburn_igopt_set_level(struct isoburn_imgen_opts *o, int level);
1163 int isoburn_igopt_get_level(struct isoburn_imgen_opts *o, int *level);
1164
1165
1166 /** Which extensions to support.
1167 @since 0.1.0
1168 @param o The option set to work on
1169 @param ext Bitfield:
1170 bit0= rockridge
1171 Rock Ridge extensions add POSIX file attributes like
1172 owner, group, access permissions, long filenames. Very
1173 advisable if the designed audience has Unix style systems.
1174 bit1= joliet
1175 Longer filenames for Windows systems.
1176 Weaker than RockRidge, but also readable with GNU/Linux.
1177 bit2= iso1999
1178 This is rather exotic. Better do not surprise the readers.
1179 bit3= hardlinks
1180 Enable hardlink consolidation. IsoNodes which refer to the
1181 same source object and have the same properties will get
1182 the same ISO image inode numbers.
1183 If combined with isoburn_igopt_rrip_version_1_10 below,
1184 then the PX entry layout of RRIP-1.12 will be used within
1185 RRIP-1.10 (mkisofs does this without causing visible trouble).
1186 bit5= aaip
1187 The libisofs specific SUSP based extension of ECMA-119 which
1188 can encode ACL and XFS-style Extended Attributes.
1189 bit6= session_md5
1190 @since 0.4.2
1191 Produce and write MD5 checksum tags of superblock, directory
1192 tree, and the whole session stream.
1193 bit7= file_md5
1194 @since 0.4.2
1195 Produce and write MD5 checksums for each single IsoFile.
1196 bit8= file_stability (only together with file_md5)
1197 @since 0.4.2
1198 Compute MD5 of each file before copying it into the image and
1199 compare this with the MD5 of the actual copying. If they do
1200 not match then issue MISHAP event.
1201 See also libisofs.h iso_write_opts_set_record_md5()
1202 bit9= no_emul_toc
1203 @since 0.5.8
1204 On overwritable media or random access files do not write
1205 the first session to LBA 32 and do not copy the first 64kB
1206 of the first session to LBA 0, but rather write the first
1207 session to LBA 0 directly.
1208 bit10= will_cancel
1209 @since 0.6.6
1210 Announce to libisofs that only the image size is desired
1211 and that the write thread will be cancelled by
1212 isoburn_cancel_prepared_write() before actual image writing
1213 occurs. Without this, cancellation can cause a MISHAP event.
1214 bit11= old_empty
1215 @since 1.0.2
1216 Let symbolic links and device files point to block 0, and let
1217 empty data files point to the address of the Volume Descriptor
1218 Set Terminator. This was done by libisofs in the past.
1219 By default there is now a single dedicated block of zero bytes
1220 after the end of the directory trees, of which the address
1221 is used for all files without own content.
1222 bit12= hfsplus
1223 @since 1.2.4
1224 Produce a HFS+ partition inside the ISO image and announce it
1225 by an Apple Partition Map in the System Area.
1226 >>> GPT production ?
1227 Caution: Interferes with isoburn_igopt_set_system_area() by
1228 overwriting the first 8 bytes of the data, and
1229 several blocks of 2 KiB after the first one.
1230 bit13= fat
1231 @since 1.2.4
1232 >>> Not yet implemented. Planned to co-exist with hfsplus.
1233 Produce a FAT32 partition inside the ISO image and announce it
1234 by an MBR partition entry in the System Area.
1235 Caution: Interferes with isoburn_igopt_set_system_area() by
1236 >>> what impact ?
1237
1238 @return 1 success, <=0 failure
1239 */
1240 #define isoburn_igopt_rockridge 1
1241 #define isoburn_igopt_joliet 2
1242 #define isoburn_igopt_iso1999 4
1243 #define isoburn_igopt_hardlinks 8
1244 #define isoburn_igopt_aaip 32
1245 #define isoburn_igopt_session_md5 64
1246 #define isoburn_igopt_file_md5 128
1247 #define isoburn_igopt_file_stability 256
1248 #define isoburn_igopt_no_emul_toc 512
1249 #define isoburn_igopt_will_cancel 1024
1250 #define isoburn_igopt_old_empty 2048
1251 #define isoburn_igopt_hfsplus 4096
1252 #define isoburn_igopt_fat 8192
1253 int isoburn_igopt_set_extensions(struct isoburn_imgen_opts *o, int ext);
1254 int isoburn_igopt_get_extensions(struct isoburn_imgen_opts *o, int *ext);
1255
1256 /** Relaxed constraints. Setting any of the bits to 1 break the specifications,
1257 but it is supposed to work on most moderns systems. Use with caution.
1258 @since 0.1.0
1259 @param o The option set to work on
1260 @param relax Bitfield:
1261 bit0= omit_version_numbers
1262 Omit the version number (";1") at the end of the
1263 ISO-9660 and Joliet identifiers.
1264 Version numbers are usually not used by readers.
1265 bit1= allow_deep_paths
1266 Allow ISO-9660 directory hierarchy to be deeper
1267 than 8 levels.
1268 bit2= allow_longer_paths
1269 Allow path in the ISO-9660 tree to have more than
1270 255 characters.
1271 bit3= max_37_char_filenames
1272 Allow a single file or directory hierarchy to have
1273 up to 37 characters. This is larger than the 31
1274 characters allowed by ISO level 2, and the extra space
1275 is taken from the version number, so this also forces
1276 omit_version_numbers.
1277 bit4= no_force_dots
1278 ISO-9660 forces filenames to have a ".", that separates
1279 file name from extension. libisofs adds it if original
1280 filename has none. Set this to 1 to prevent this
1281 behavior.
1282 bit5= allow_lowercase
1283 Allow lowercase characters in ISO-9660 filenames.
1284 By default, only uppercase characters, numbers and
1285 a few other characters are allowed.
1286 bit6= allow_full_ascii
1287 Allow all ASCII characters to be appear on an ISO-9660
1288 filename. Note that "/" and "\0" characters are never
1289 allowed, even in RR names.
1290 bit7= joliet_longer_paths
1291 Allow paths in the Joliet tree to have more than
1292 240 characters.
1293 bit8= always_gmt
1294 Write timestamps as GMT although the specs prescribe local
1295 time with eventual non-zero timezone offset. Negative
1296 timezones (west of GMT) can trigger bugs in some operating
1297 systems which typically appear in mounted ISO images as if
1298 the timezone shift from GMT was applied twice
1299 (e.g. in New York 22:36 becomes 17:36).
1300 bit9= rrip_version_1_10
1301 Write Rock Ridge info as of specification RRIP-1.10 rather
1302 than RRIP-1.12: signature "RRIP_1991A" rather than
1303 "IEEE_1282", field PX without file serial number.
1304 bit10= dir_rec_mtime
1305 Store as ECMA-119 Directory Record timestamp the mtime
1306 of the source rather than the image creation time.
1307 bit11= aaip_susp_1_10
1308 Write AAIP fields without announcing AAIP by an ER field and
1309 without distinguishing RRIP fields from the AAIP field by
1310 prefixed ES fields. This saves 5 to 10 bytes per file and
1311 might avoid problems with readers which only accept RRIP.
1312 SUSP-1.10 allows it, SUSP-1.12 frowns on it.
1313 bit12= only_iso_numbers
1314 Same as bit1 omit_version_number but restricted to the names
1315 in the eventual Joliet tree.
1316 @since 0.5.4
1317 For reasons of backward compatibility it is not possible yet
1318 to disable version numbers for ISO 9660 while enabling them
1319 for Joliet.
1320 bit13= no_j_force_dots
1321 Same as no_force_dots but affecting the names in the eventual
1322 Joliet tree rather than the ISO 9660 / ECMA-119 names.
1323 @since 0.5.4
1324 Previous versions added dots to Joliet names unconditionally.
1325 bit14= allow_dir_id_ext
1326 Convert directory names for ECMA-119 similar to other file
1327 names, but do not force a dot or add a version number.
1328 This violates ECMA-119 by allowing one "." and especially
1329 ISO level 1 by allowing DOS style 8.3 names rather than
1330 only 8 characters.
1331 (mkisofs and its clones obviously do this violation.)
1332 @since 1.0.0
1333 bit15= joliet_long_names
1334 Allow for Joliet leaf names up to 103 characters rather than
1335 up to 64.
1336 @since 1.0.6
1337 bit16= joliet_rec_mtime
1338 Like dir_rec_mtime, but for the Joliet tree.
1339 @since 1.2.0
1340 bit17= iso1999_rec_mtime
1341 Like dir_rec_mtime, but for the ISO 9660:1999 tree.
1342 @since 1.2.0
1343 bit18= allow_7bit_ascii
1344 Like allow_full_ascii, but only allowing 7-bit characters.
1345 Lowercase letters get mapped to uppercase if not
1346 allow_lowercase is set.
1347 Gets overridden if allow_full_ascii is enabled.
1348 bit19= joliet_utf16
1349 Encode Joliet names by character set UTF-16BE rather than
1350 UCS-2. The difference is with characters which are not present
1351 in UCS-2 and get encoded in UTF-16 by 2 words of 16 bit each.
1352 Both words then stem from a reserved subset of UCS-2.
1353 @since 1.3.6
1354 @return 1 success, <=0 failure
1355 */
1356 #define isoburn_igopt_omit_version_numbers 1
1357 #define isoburn_igopt_allow_deep_paths 2
1358 #define isoburn_igopt_allow_longer_paths 4
1359 #define isoburn_igopt_max_37_char_filenames 8
1360 #define isoburn_igopt_no_force_dots 16
1361 #define isoburn_igopt_allow_lowercase 32
1362 #define isoburn_igopt_allow_full_ascii 64
1363 #define isoburn_igopt_joliet_longer_paths 128
1364 #define isoburn_igopt_always_gmt 256
1365 #define isoburn_igopt_rrip_version_1_10 512
1366 #define isoburn_igopt_dir_rec_mtime 1024
1367 #define isoburn_igopt_aaip_susp_1_10 2048
1368 #define isoburn_igopt_only_iso_versions 4096
1369 #define isoburn_igopt_no_j_force_dots 8192
1370 #define isoburn_igopt_allow_dir_id_ext 16384
1371 #define isoburn_igopt_joliet_long_names 32768
1372 #define isoburn_igopt_joliet_rec_mtime 0x10000
1373 #define isoburn_igopt_iso1999_rec_mtime 0x20000
1374 #define isoburn_igopt_allow_7bit_ascii 0x40000
1375 #define isoburn_igopt_joliet_utf16 0x80000
1376 int isoburn_igopt_set_relaxed(struct isoburn_imgen_opts *o, int relax);
1377 int isoburn_igopt_get_relaxed(struct isoburn_imgen_opts *o, int *relax);
1378
1379
1380 /** If not isoburn_igopt_allow_deep_paths is in effect, then it may become
1381 necessary to relocate directories so that no ECMA-119 file path
1382 has more than 8 components. These directories are grafted into either
1383 the root directory of the ISO image or into a dedicated relocation
1384 directory. For details see libisofs.h.
1385 Wrapper for: iso_write_opts_set_rr_reloc()
1386 @since 1.2.2
1387 @param o The option set to work on
1388 @param name The name of the relocation directory in the root directory.
1389 Do not prepend "/". An empty name or NULL will direct
1390 relocated directories into the root directory. This is the
1391 default.
1392 If the given name does not exist in the root directory when
1393 isoburn_disc_write() is called, and if there are directories
1394 at path level 8, then directory /name will be created
1395 automatically.
1396 @param flags Bitfield for control purposes.
1397 bit0= Mark the relocation directory by a Rock Ridge RE entry,
1398 if it gets created during isoburn_disc_write(). This
1399 will make it invisible for most Rock Ridge readers.
1400 bit1= not settable via API (used internally)
1401 @return > 0 success, <= 0 failure
1402 */
1403 int isoburn_igopt_set_rr_reloc(struct isoburn_imgen_opts *o, char *name,
1404 int flags);
1405
1406 /** Obtain the settings of isoburn_igopt_set_rr_reloc().
1407 @since 1.2.2
1408 @param o The option set to work on
1409 @param name Will return NULL or a pointer to the name of the relocation
1410 directory in the root directory. Do not alter or dispose the
1411 memory which holds this name.
1412 @param flags Will return the flags bitfield.
1413 @return > 0 success, <= 0 failure
1414 */
1415 int isoburn_igopt_get_rr_reloc(struct isoburn_imgen_opts *o, char **name,
1416 int *flags);
1417
1418
1419 /** Caution: This option breaks any assumptions about names that
1420 are supported by ECMA-119 specifications.
1421 Try to omit any translation which would make a file name compliant to the
1422 ECMA-119 rules. This includes and exceeds omit_version_numbers,
1423 max_37_char_filenames, no_force_dots bit0, allow_full_ascii. Further it
1424 prevents the conversion from local character set to ASCII.
1425 The maximum name length is given by this call. If a filename exceeds
1426 this length or cannot be recorded untranslated for other reasons, then
1427 image production gets aborted.
1428 Currently the length limit is 96 characters, because an ECMA-119 directory
1429 record may at most have 254 bytes and up to 158 other bytes must fit into
1430 the record. Probably 96 more bytes can be made free for the name in future.
1431 @since 1.0.0
1432 @param o The option set to work on
1433 @param len 0 = disable this feature and perform name translation
1434 according to other settings.
1435 >0 = Omit any translation. Eventually abort image production
1436 if a name is longer than the given value.
1437 -1 = Like >0. Allow maximum possible length.
1438 isoburn_igopt_get_untranslated_name_len() will tell the
1439 effectively resulting value.
1440 @return >0 success, <=0 failure
1441 */
1442 int isoburn_igopt_set_untranslated_name_len(struct isoburn_imgen_opts *o,
1443 int len);
1444 int isoburn_igopt_get_untranslated_name_len(struct isoburn_imgen_opts *o,
1445 int *len);
1446
1447
1448 /** Whether and how files should be sorted.
1449 @since 0.1.0
1450 @param o The option set to work on
1451 @param value Bitfield: bit0= sort_files_by_weight
1452 files should be sorted based on their weight.
1453 Weight is attributed to files in the image
1454 by libisofs call iso_node_set_sort_weight().
1455 @return 1 success, <=0 failure
1456 */
1457 #define isoburn_igopt_sort_files_by_weight 1
1458 int isoburn_igopt_set_sort_files(struct isoburn_imgen_opts *o, int value);
1459 int isoburn_igopt_get_sort_files(struct isoburn_imgen_opts *o, int *value);
1460
1461
1462 /** Set the override values for files and directory permissions.
1463 The parameters replace_* these take one of three values: 0, 1 or 2.
1464 If 0, the corresponding attribute will be kept as set in the IsoNode
1465 at the time of image generation.
1466 If set to 1, the corresponding attrib. will be changed by a default
1467 suitable value.
1468 With value 2, the attrib. will be changed with the value specified
1469 in the corresponding *_mode options. Note that only the permissions
1470 are set, the file type remains unchanged.
1471 @since 0.1.0
1472 @param o The option set to work on
1473 @param replace_dir_mode whether and how to override directories
1474 @param replace_file_mode whether and how to override files of other type
1475 @param dir_mode Mode to use on dirs with replace_dir_mode == 2.
1476 @param file_mode; Mode to use on files with replace_file_mode == 2.
1477 @return 1 success, <=0 failure
1478 */
1479 int isoburn_igopt_set_over_mode(struct isoburn_imgen_opts *o,
1480 int replace_dir_mode, int replace_file_mode,
1481 mode_t dir_mode, mode_t file_mode);
1482 int isoburn_igopt_get_over_mode(struct isoburn_imgen_opts *o,
1483 int *replace_dir_mode, int *replace_file_mode,
1484 mode_t *dir_mode, mode_t *file_mode);
1485
1486 /** Set the override values values for group id and user id.
1487 The rules are like with above overriding of mode values. replace_* controls
1488 whether and how. The other two parameters provide values for eventual use.
1489 @since 0.1.0
1490 @param o The option set to work on
1491 @param replace_uid whether and how to override user ids
1492 @param replace_gid whether and how to override group ids
1493 @param uid User id to use with replace_uid == 2.
1494 @param gid Group id to use on files with replace_gid == 2.
1495 @return 1 success, <=0 failure
1496 */
1497 int isoburn_igopt_set_over_ugid(struct isoburn_imgen_opts *o,
1498 int replace_uid, int replace_gid,
1499 uid_t uid, gid_t gid);
1500 int isoburn_igopt_get_over_ugid(struct isoburn_imgen_opts *o,
1501 int *replace_uid, int *replace_gid,
1502 uid_t *uid, gid_t *gid);
1503
1504 /** Set the character set to use for representing RR filenames in the image.
1505 @since 0.1.0
1506 @param o The option set to work on
1507 @param output_charset Set this to NULL to use the default output charset.
1508 For selecting a particular character set, submit its
1509 name, e.g. as listed by program iconv -l.
1510 Example: "UTF-8".
1511 @return 1 success, <=0 failure
1512 */
1513 int isoburn_igopt_set_out_charset(struct isoburn_imgen_opts *o,
1514 char *output_charset);
1515 int isoburn_igopt_get_out_charset(struct isoburn_imgen_opts *o,
1516 char **output_charset);
1517
1518
1519 /** The number of bytes to be used for the fifo which decouples libisofs
1520 and libburn for better throughput and for reducing the risk of
1521 interrupting signals hitting the libburn thread which operates the
1522 MMC drive.
1523 The size will be rounded up to the next full 2048.
1524 Minimum is 64kiB, maximum is 1 GiB (but that is too much anyway).
1525 @since 0.1.0
1526 @param o The option set to work on
1527 @param fifo_size Number of bytes to use
1528 @return 1 success, <=0 failure
1529 */
1530 int isoburn_igopt_set_fifo_size(struct isoburn_imgen_opts *o, int fifo_size);
1531 int isoburn_igopt_get_fifo_size(struct isoburn_imgen_opts *o, int *fifo_size);
1532
1533
1534 /** Obtain after image preparation the block address where the session will
1535 start on the medium.
1536 This value cannot be set by the application but only be inquired.
1537 @since 0.1.4
1538 @param o The option set to work on
1539 @param lba The block number of the session start on the medium.
1540 <0 means that no address has been determined yet.
1541 @return 1 success, <=0 failure
1542 */
1543 int isoburn_igopt_get_effective_lba(struct isoburn_imgen_opts *o, int *lba);
1544
1545
1546 /** Obtain after image preparation the lowest block address of file content
1547 data. Failure can occur if libisofs is too old to provide this information,
1548 if the result exceeds 31 bit, or if the call is made before image
1549 preparation.
1550 This value cannot be set by the application but only be inquired.
1551 @since 0.3.6
1552 @param o The option set to work on
1553 @param lba The block number of the session start on the medium.
1554 <0 means that no address has been determined yet.
1555 @return 1 success, <=0 failure
1556 */
1557 int isoburn_igopt_get_data_start(struct isoburn_imgen_opts *o, int *lba);
1558
1559
1560 /** Set or get parameters "name" and "timestamp" for a scdbackup checksum
1561 tag. It will be appended to the libisofs session tag if the image starts at
1562 LBA 0. See isoburn_disc_track_lba_nwa. The scdbackup tag can be used
1563 to verify the image by command scdbackup_verify $device -auto_end.
1564 See scdbackup/README appendix VERIFY for its inner details.
1565 @since 0.4.4
1566 @param o The option set to work on
1567 @param name The tag name. 80 characters max.
1568 An empty name disables production of an scdbackup tag.
1569 @param timestamp A string of up to 13 characters YYMMDD.hhmmss
1570 A9 = 2009, B0 = 2010, B1 = 2011, ... C0 = 2020, ...
1571 @param tag_written Either NULL or the address of an array with at least 512
1572 characters. In the latter case the eventually produced
1573 scdbackup tag will be copied to this array when the image
1574 gets written. This call sets scdbackup_tag_written[0] = 0
1575 to mark its preliminary invalidity.
1576 @return 1 success, <=0 failure
1577 */
1578 int isoburn_igopt_set_scdbackup_tag(struct isoburn_imgen_opts *o, char *name,
1579 char *timestamp, char *tag_written);
1580 int isoburn_igopt_get_scdbackup_tag(struct isoburn_imgen_opts *o,
1581 char name[81], char timestamp[19],
1582 char **tag_written);
1583
1584
1585 /** Attach 32 kB of binary data which shall get written to the first 32 kB
1586 of the ISO image, the System Area.
1587 options can cause manipulations of these data before writing happens.
1588 If system area data are giveni or options bit0 is set, then bit1 of
1589 el_torito_set_isolinux_options() is automatically disabled.
1590 @since 0.5.4
1591 @param o The option set to work on
1592 @param data Either NULL or 32 kB of data. Do not submit less bytes !
1593 @param options Can cause manipulations of submitted data before they
1594 get written:
1595 bit0= apply a --protective-msdos-label as of grub-mkisofs.
1596 This means to patch bytes 446 to 512 of the system
1597 area so that one partition is defined which begins
1598 at the second 512-byte block of the image and ends
1599 where the image ends.
1600 This works with and without system_area_data.
1601 bit1= apply isohybrid MBR patching to the system area.
1602 This works only with system area data from
1603 SYSLINUX plus an ISOLINUX boot image (see
1604 iso_image_set_boot_image()) and only if not bit0
1605 is set.
1606 bit2-7= System area type
1607 0= with bit0 or bit1: MBR
1608 else: unspecified type
1609 @since 0.6.4
1610 1= MIPS Big Endian Volume Header
1611 Submit up to 15 MIPS Big Endian boot files by
1612 iso_image_add_mips_boot_file() of libisofs.
1613 This will overwrite the first 512 bytes of
1614 the submitted data.
1615 2= DEC Boot Block for MIPS Little Endian
1616 The first boot file submitted by
1617 iso_image_add_mips_boot_file() will be activated.
1618 This will overwrite the first 512 bytes of
1619 the submitted data.
1620 @since 0.6.6
1621 3= SUN Disk Label for SUN SPARC
1622 Submit up to 7 SPARC boot images by
1623 isoburn_igopt_set_partition_img() for partition
1624 numbers 2 to 8.
1625 This will overwrite the first 512 bytes of
1626 the submitted data.
1627 @since 1.3.8
1628 4= HP-PA PALO boot sector header version 4
1629 Submit all five parameters of
1630 iso_image_set_hppa_palo() as non-NULL texts.
1631 5= HP-PA PALO boot sector header version 5
1632 Submit all five parameters of
1633 iso_image_set_hppa_palo() as non-NULL texts.
1634 bit8-9= Only with System area type 0 = MBR
1635 @since 1.0.4
1636 Cylinder alignment mode eventually pads the image
1637 to make it end at a cylinder boundary.
1638 0 = auto (align if bit1)
1639 1 = always align to cylinder boundary
1640 2 = never align to cylinder boundary
1641 bit10-13= System area sub type
1642 @since 1.2.4
1643 With type 0 = MBR:
1644 Gets overridden by bit0 and bit1.
1645 0 = no particular sub type
1646 1 = CHRP: A single MBR partition of type 0x96
1647 covers the ISO image. Not compatible with
1648 any other feature which needs to have own
1649 MBR partition entries.
1650 bit14= Only with System area type 0 = MBR
1651 GRUB2 boot provisions:
1652 @since 1.3.0
1653 Patch system area at byte 0x1b0 to 0x1b7 with
1654 (512-block address + 4) of the first boot image file.
1655 Little-endian 8-byte.
1656 Should be combined with options bit0.
1657 Will not be in effect if options bit1 is set.
1658 @return 1 success, 0 no data to get, <0 failure
1659 */
1660 int isoburn_igopt_set_system_area(struct isoburn_imgen_opts *o,
1661 char data[32768], int options);
1662 int isoburn_igopt_get_system_area(struct isoburn_imgen_opts *o,
1663 char data[32768], int *options);
1664
1665 /** Control production of a second set of volume descriptors (superblock)
1666 and directory trees, together with a partition table in the MBR where the
1667 first partition has non-zero start address and the others are zeroed.
1668 The first partition stretches to the end of the whole ISO image.
1669 The additional volume descriptor set and trees can be used to mount the
1670 ISO image at the start of the first partition, while it is still possible
1671 to mount it via the normal first volume descriptor set and tree at the
1672 start of the image or storage device.
1673 This makes few sense on optical media. But on USB sticks it creates a
1674 conventional partition table which makes it mountable on e.g. Linux via
1675 /dev/sdb and /dev/sdb1 alike.
1676 @since 0.6.2
1677 @param opts
1678 The option set to be manipulated.
1679 @param block_offset_2k
1680 The offset of the partition start relative to device start.
1681 This is counted in 2 kB blocks. The partition table will show the
1682 according number of 512 byte sectors.
1683 Default is 0 which causes no second set and trees.
1684 If it is not 0 then it must not be smaller than 16.
1685 @param secs_512_per_head
1686 Number of 512 byte sectors per head. 1 to 63. 0=automatic.
1687 @param heads_per_cyl
1688 Number of heads per cylinder. 1 to 255. 0=automatic.
1689 @return 1 success, <=0 failure
1690 */
1691 int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts *opts,
1692 uint32_t block_offset_2k,
1693 int secs_512_per_head, int heads_per_cyl);
1694 int isoburn_igopt_get_part_offset(struct isoburn_imgen_opts *opts,
1695 uint32_t *block_offset_2k,
1696 int *secs_512_per_head, int *heads_per_cyl);
1697
1698
1699 /** Explicitly set the four timestamps of the emerging ISO image.
1700 Default with all parameters is 0.
1701 @since 0.5.4
1702 @param opts
1703 The option set to work on
1704 @param creation_time
1705 ECMA-119 Volume Creation Date and Time
1706 When "the information in the volume was created."
1707 A value of 0 means that the timepoint of write start is to be used.
1708 @param modification_time
1709 ECMA-119 Volume Modification Date and Time
1710 When "the informationin the volume was last modified."
1711 A value of 0 means that the timepoint of write start is to be used.
1712 @param expiration_time
1713 ECMA-119 Volume Expiration Date and Time
1714 When "the information in the volume may be regarded as obsolete."
1715 A value of 0 means that the information never shall expire.
1716 @param effective_time
1717 ECMA-119 Volume Effective Date and Time
1718 When "the information in the volume may be used."
1719 A value of 0 means that not such retention is intended.
1720 @param uuid
1721 If this text is not empty, then it overrides vol_modification_time
1722 by copying the first 16 decimal digits from uuid, eventually
1723 padding up with decimal '1', and writing a NUL-byte as timezone GMT.
1724 It should express a reasonable time in form YYYYMMDDhhmmsscc
1725 E.g.: 2010040711405800 = 7 Apr 2010 11:40:58 (+0 centiseconds)
1726 @return 1 success, <=0 failure
1727 */
1728 int isoburn_igopt_set_pvd_times(struct isoburn_imgen_opts *opts,
1729 time_t creation_time, time_t modification_time,
1730 time_t expiration_time, time_t effective_time,
1731 char *uuid);
1732 int isoburn_igopt_get_pvd_times(struct isoburn_imgen_opts *opts,
1733 time_t *creation_time, time_t *modification_time,
1734 time_t *expiration_time, time_t *effective_time,
1735 char uuid[17]);
1736
1737
1738 /** Associate a libjte environment object to the upcoming write run.
1739 libjte implements Jigdo Template Extraction as of Steve McIntyre and
1740 Richard Atterer.
1741 A non-NULL libjte_handle will cause failure to write if libjte was not
1742 enabled in libisofs at compile time.
1743 @since 0.6.4
1744 @param opts
1745 The option set to work on
1746 @param libjte_handle
1747 Pointer to a struct libjte_env e.g. created by libjte_new().
1748 It must stay existent from the start of image writing by
1749 isoburn_prepare_*() until the write thread has ended.
1750 E.g. until libburn indicates the end of its write run.
1751 @return 1 success, <=0 failure
1752 */
1753 int isoburn_igopt_attach_jte(struct isoburn_imgen_opts *opts,
1754 void *libjte_handle);
1755
1756 /** Remove eventual association to a libjte environment handle.
1757 @since 0.6.4
1758 @param opts
1759 The option set to work on
1760 @param libjte_handle
1761 If not submitted as NULL, this will return the previously set
1762 libjte handle.
1763 @return 1 success, <=0 failure
1764 */
1765 int isoburn_igopt_detach_jte(struct isoburn_imgen_opts *opts,
1766 void **libjte_handle);
1767
1768
1769 /** Set or get the number of trailing zero byte blocks to be written by
1770 libisofs. The image size counter of the emerging ISO image will include
1771 them. Eventual checksums will take them into respect.
1772 They will be written immediately before the eventual image checksum area
1773 which is at the very end of the image.
1774 For a motivation see iso_write_opts_set_tail_blocks() in libisofs.h .
1775 @since 0.6.4
1776 @param opts
1777 The option set to work on
1778 @param num_blocks
1779 Number of extra 2 kB blocks to be written by libisofs.
1780 @return 1 success, <=0 failure
1781 */
1782 int isoburn_igopt_set_tail_blocks(struct isoburn_imgen_opts *opts,
1783 uint32_t num_blocks);
1784 int isoburn_igopt_get_tail_blocks(struct isoburn_imgen_opts *opts,
1785 uint32_t *num_blocks);
1786
1787
1788 /** Copy a data file from the local filesystem into the emerging ISO image.
1789 Mark it by an MBR partition entry as PreP partition and also cause
1790 protective MBR partition entries before and after this partition.
1791 See libisofs.h iso_write_opts_set_prep_img().
1792 @since 1.2.4
1793 @param opts
1794 The option set to be manipulated.
1795 @param path
1796 File address in the local file system.
1797 @param flag
1798 With isoburn_igopt_set_prep_partition():
1799 Control bits as of iso_write_opts_set_efi_bootp()
1800 bit0= The path contains instructions for the interval libisofs
1801 reader. See libisofs.h.
1802 @since 1.4.0
1803 With isoburn_igopt_get_prep_partition():
1804 bit0= add the current flag setting & 0x3fffffff to return value 1.
1805 @return 1 success, <=0 failure
1806 */
1807 int isoburn_igopt_set_prep_partition(struct isoburn_imgen_opts *opts,
1808 char *path, int flag);
1809 int isoburn_igopt_get_prep_partition(struct isoburn_imgen_opts *opts,
1810 char **path, int flag);
1811
1812 /** Copy a data file from the local filesystem into the emerging ISO image
1813 and mark it by a GPT entry as EFI system partition.
1814 @since 1.2.4
1815 @param opts
1816 The option set to be manipulated.
1817 @param path
1818 File address in the local file system.
1819 Instead of a disk path, the word --efi-boot-image may be given.
1820 It exposes in GPT the content of the first El Torito EFI boot image
1821 as EFI system partition.
1822 @param flag
1823 With isoburn_igopt_get_efi_bootp():
1824 Control bits as of iso_write_opts_set_efi_bootp()
1825 bit0= The path contains instructions for the interval libisofs
1826 reader. See libisofs.h.
1827 @since 1.4.0
1828 With isoburn_igopt_set_efi_bootp():
1829 bit0= add the current flag setting & 0x3fffffff to return value 1.
1830 @return 1 success, <=0 failure
1831 */
1832 int isoburn_igopt_set_efi_bootp(struct isoburn_imgen_opts *opts,
1833 char *path, int flag);
1834 int isoburn_igopt_get_efi_bootp(struct isoburn_imgen_opts *opts,
1835 char **path, int flag);
1836
1837
1838 /** Cause an arbitrary data file to be appended to the ISO image and to be
1839 described by a partition table entry in an MBR or SUN Disk Label at the
1840 start of the ISO image.
1841 The partition entry will bear the size of the image file rounded up to
1842 the next multiple of 2048 bytes.
1843 MBR or SUN Disk Label are selected by isoburn_igopt_set_system_area()
1844 system area type: 0 selects MBR partition table. 3 selects a SUN partition
1845 table with 320 kB start alignment.
1846 @since 0.6.4
1847 @param opts
1848 The option set to be manipulated.
1849 @param partition_number
1850 Depicts the partition table entry which shall describe the
1851 appended image.
1852 Range with MBR: 1 to 4. 1 will cause the whole ISO image to be
1853 unclaimable space before partition 1.
1854 @since 0.6.6
1855 Range with SUN Disk Label: 2 to 8.
1856 @param image_path
1857 File address in the local file system.
1858 With SUN Disk Label: an empty name causes the partition to become
1859 a copy of the next lower partition.
1860 @param partition_type
1861 The MBR partition type. E.g. FAT12 = 0x01 , FAT16 = 0x06,
1862 Linux Native Partition = 0x83. See fdisk command L.
1863 This parameter is ignored with SUN Disk Label.
1864 @return
1865 <=0 = error, 1 = success
1866 */
1867 int isoburn_igopt_set_partition_img(struct isoburn_imgen_opts *opts,
1868 int partition_number, uint8_t partition_type,
1869 char *image_path);
1870
1871 /** Inquire the current settings made by isoburn_igopt_set_partition_img().
1872 @since 0.6.4
1873 @param opts
1874 The option set to be inquired.
1875 @param num_entries
1876 Number of array elements in partition_types[] and image_paths[].
1877 @param partition_types
1878 The partition type associated with the partition. Valid only if
1879 image_paths[] of the same index is not NULL.
1880 @param image_paths
1881 Its elements get filled with either NULL or a pointer to a string
1882 with a file address or an empty text.
1883 @return
1884 <0 = error
1885 0 = no partition image set
1886 >0 highest used partition number
1887 */
1888 int isoburn_igopt_get_partition_img(struct isoburn_imgen_opts *opts,
1889 int num_entries,
1890 uint8_t partition_types[],
1891 char *image_paths[]);
1892
1893
1894 /** Set flag bits for a partition defined by isoburn_igopt_set_partition_img().
1895 The bits will be forwarded to libisofs iso_write_opts_set_partition_img().
1896 @since 1.4.0
1897 @param opts
1898 The option set to be manipulated.
1899 @param partition_number
1900 Depicts the partition table entry to which shall the flags bits
1901 shall apply.
1902 @param flag
1903 Control bits as of iso_write_opts_set_partition_img()
1904 bit0= The path contains instructions for the interval libisofs
1905 reader. See libisofs.h.
1906 @since 1.4.0
1907 @return
1908 <=0 = error, 1 = success
1909 */
1910 int isoburn_igopt_set_part_flag(struct isoburn_imgen_opts *opts,
1911 int partition_number, int flag);
1912
1913 /** Inquire the current settings made by isoburn_igopt_set_part_flags().
1914 @since 1.4.0
1915 @param opts
1916 The option set to be inquired.
1917 @param num_entries
1918 Number of array elements in part_flags[].
1919 @param part_flags
1920 The array elements 0 to num_entries - 1 will get filled by the
1921 flag bits of the images of the corresponding partition.
1922 @return
1923 <0 = error
1924 0 = no partition image set
1925 >0 highest used partition number
1926 */
1927 int isoburn_igopt_get_part_flags(struct isoburn_imgen_opts *opts,
1928 int num_entries, int part_flags[]);
1929
1930 /** Control whether partitions created by iso_write_opts_set_partition_img()
1931 are to be represented in MBR or as GPT partitions.
1932 @since 1.4.0
1933 @param opts
1934 The option set to be manipulated.
1935 @param gpt
1936 0= represent as MBR partition; as GPT only if other GPT partitions
1937 are present
1938 1= represent as GPT partition and cause protective MBR with a single
1939 partition which covers the whole output data.
1940 This may fail if other settings demand MBR partitions.
1941 Do not use other values for now.
1942 @return
1943 <=0 = error, 1 = success
1944 */
1945 int isoburn_igopt_set_appended_as_gpt(struct isoburn_imgen_opts *opts,
1946 int gpt);
1947
1948 /** Inquire the current setting made by isoburn_igopt_set_appended_as_gpt().
1949 @since 1.4.0
1950 @param opts
1951 The option set to be inquired.
1952 @param gpt
1953 Returns the current value.
1954 @return
1955 <=0 = error, 1 = success
1956 */
1957 int isoburn_igopt_get_appended_as_gpt(struct isoburn_imgen_opts *opts,
1958 int *gpt);
1959
1960 /** Set the GPT Type GUID for a partition defined by
1961 isoburn_igopt_set_partition_img().
1962 @since 1.5.2
1963 @param opts
1964 The option set to be manipulated.
1965 @param partition_number
1966 Depicts the partition table entry which shall get the Type GUID.
1967 @param guid
1968 16 bytes of user supplied GUID. Readily byte-swapped from the text
1969 form as prescribed by UEFI specs:
1970 4 byte, 2 byte, 2 byte as little-endian.
1971 2 byte, 6 byte as big-endian.
1972 @param valid
1973 Set to 1 to make this Type GUID valid.
1974 Set to 0 in order to invalidate a previously made setting. In this
1975 case MBR type 0xEF will become the EFI Type GUID. All others will
1976 become the Basic Data Partition Type GUID.
1977 @return
1978 <=0 = error, 1 = success
1979 */
1980 int isoburn_igopt_set_part_type_guid(struct isoburn_imgen_opts *opts,
1981 int partition_number, uint8_t guid[16],
1982 int valid);
1983
1984 /** Inquire the current settings made by isoburn_igopt_set_part_type_guid().
1985 @since 1.5.2
1986 @param opts
1987 The option set to be inquired.
1988 @param num_entries
1989 Number of array elements in part_flags[].
1990 @param type_guids
1991 The array elements 0 to num_entries - 1 will get filled by the
1992 16 flag bits of the images of the corresponding partition.
1993 @param valids
1994 The array elements 0 to num_entries - 1 will get filled by 1 or 0
1995 to indicate whether the corresponding type_guids element is valid.
1996 @return
1997 <0 = error
1998 0 = no partition image set
1999 >0 highest used partition number
2000 */
2001 int isoburn_igopt_get_part_type_guid(struct isoburn_imgen_opts *opts,
2002 int num_entries, uint8_t guids[][16],
2003 int valids[]);
2004
2005 /** Control whether partitions created by iso_write_opts_set_partition_img()
2006 are to be represented in Apple Partition Map.
2007 @since 1.4.4
2008 @param opts
2009 The option set to be manipulated.
2010 @param apm
2011 0= do not represent appended partitions in APM
2012 1= represent in APM, even if not
2013 iso_write_opts_set_part_like_isohybrid() enables it and no
2014 other APM partitions emerge.
2015 Do not use other values for now.
2016 @return
2017 <=0 = error, 1 = success
2018 */
2019 int isoburn_igopt_set_appended_as_apm(struct isoburn_imgen_opts *opts,
2020 int apm);
2021
2022 /** Inquire the current setting made by isoburn_igopt_set_appended_as_apm().
2023 @since 1.4.4
2024 @param opts
2025 The option set to be inquired.
2026 @param apm
2027 Returns the current value.
2028 @return
2029 <=0 = error, 1 = success
2030 */
2031 int isoburn_igopt_get_appended_as_apm(struct isoburn_imgen_opts *opts,
2032 int *apm);
2033
2034
2035 /** Control whether bits 2 to 8 of el_torito_set_isolinux_options()
2036 shall apply even if not isohybrid MBR patching is enabled (bit1 of
2037 parameter options of isoburn_igopt_set_system_area()).
2038 For details see iso_write_opts_set_part_like_isohybrid() in libisofs.h.
2039 @since 1.4.4
2040 @param opts
2041 The option set to be manipulated.
2042 @param alike
2043 0= Apply isohybrid behavior only with ISOLINUX isohybrid.
2044 Do not mention appended partitions in APM unless
2045 isoburn_igopt_set_appended_as_apm() is enabled.
2046 1= Apply isohybrid behavior even without ISOLINUX isohybrid.
2047 @return
2048 <=0 = error, 1 = success
2049 */
2050 int isoburn_igopt_set_part_like_isohybrid(struct isoburn_imgen_opts *opts,
2051 int alike);
2052
2053 /** Inquire the current setting of isoburn_igopt_set_part_like_isohybrid().
2054 @since 1.4.4
2055 @param opts
2056 The option set to be inquired.
2057 @param alike
2058 Returns the current value.
2059 @return
2060 <=0 = error, 1 = success
2061 */
2062 int isoburn_igopt_get_part_like_isohybrid(struct isoburn_imgen_opts *opts,
2063 int *alike);
2064
2065 /** Set the partition type of the MBR partition which represents the ISO
2066 filesystem or at least protects it.
2067 This is without effect if no such partition emerges by other settings or
2068 if the partition type is prescribed mandatorily like 0xee for
2069 GPT protective MBR or 0x96 for CHRP.
2070 @since 1.4.8
2071 @param opts
2072 The option set to be manipulated.
2073 @param part_type
2074 0x00 to 0xff as desired partition type.
2075 Any other value (e.g. -1) enables the default types of the various
2076 occasions.
2077 */
2078 int isoburn_igopt_set_iso_mbr_part_type(struct isoburn_imgen_opts *opts,
2079 int part_type);
2080
2081 /** Inquire the current setting of isoburn_igopt_set_iso_mbr_part_type().
2082 @since 1.4.8
2083 @param opts
2084 The option set to be inquired.
2085 @param part_type
2086 Returns the current value: -1, 0x00 to 0xff.
2087 @return
2088 <=0 = error, 1 = success
2089 */
2090 int isoburn_igopt_get_iso_mbr_part_type(struct isoburn_imgen_opts *opts,
2091 int *part_type);
2092
2093 /** Set the GPT Type GUID for the partition which represents the ISO 9660
2094 filesystem, if such a partition emerges in GPT.
2095 @since 1.5.2
2096 @param opts
2097 The option set to be manipulated.
2098 @param guid
2099 16 bytes of user supplied GUID. Readily byte-swapped from the text
2100 form as prescribed by UEFI specs:
2101 4 byte, 2 byte, 2 byte as little-endian.
2102 2 byte, 6 byte as big-endian.
2103 @param valid
2104 Set to 1 to make this Type GUID valid.
2105 Set to 0 in order to invalidate a previously made setting. In this
2106 case the setting of isoburn_igopt_set_iso_mbr_part_type() or its
2107 default gets into effect.
2108 @return
2109 <=0 = error, 1 = success
2110 */
2111 int isoburn_igopt_set_iso_type_guid(struct isoburn_imgen_opts *opts,
2112 uint8_t guid[16], int valid);
2113
2114 /** Inquire the current setting of isoburn_igopt_set_iso_type_guid().
2115 @since 1.5.2
2116 @param opts
2117 The option set to be inquired.
2118 @param guid
2119 Gets filled with the 16 bytes of GUID.
2120 @return
2121 <= error, 0= guid is invalid, 1 = guid is valid
2122 */
2123 int isoburn_igopt_get_iso_type_guid(struct isoburn_imgen_opts *opts,
2124 uint8_t guid[16]);
2125
2126 /** Control whether the emerging GPT gets a pseudo-randomly generated disk GUID
2127 or whether it gets a user supplied GUID.
2128 The partition GUIDs will be generated in a reproducible way by exoring a
2129 little-endian 32 bit counter with the disk GUID beginning at byte offset 9.
2130 @since 1.4.6
2131 @param opts
2132 The option set to be manipulated.
2133 @param guid
2134 16 bytes of user supplied GUID. Readily byte-swapped from the text
2135 form as prescribed by UEFI specs:
2136 4 byte, 2 byte, 2 byte as little-endian.
2137 2 byte, 6 byte as big-endian.
2138 The upper 4 bit of guid[6] and guid[7] should bear the value 4 to
2139 express the version 4 in both endiannesses. Bit 7 of byte[8] should
2140 be set to 1 and bit 6 be set to 0, in order to express the RFC 4122
2141 variant of GUID, where version 4 means "random".
2142 @param mode
2143 0 = ignore parameter guid and produce the GPT disk GUID by a
2144 pseudo-random algorithm. This is the default setting.
2145 1 = use parameter guid as GPT disk GUID
2146 2 = ignore parameter guid and derive the GPT disk GUID from
2147 parameter uuid of isoburn_igopt_set_pvd_times().
2148 The 16 bytes of uuid get copied and bytes 6, 7, 8 get their
2149 upper bits changed to comply to RFC 4122.
2150 If no such uuid is given when ISO production starts, then
2151 mode 2 defaults to mode 0.
2152 */
2153 int isoburn_igopt_set_gpt_guid(struct isoburn_imgen_opts *opts,
2154 uint8_t guid[16], int mode);
2155
2156 /** Inquire the current setting of isoburn_igopt_set_gpt_guid().
2157 @since 1.4.6
2158 @param opts
2159 The option set to be inquired.
2160 @param guid
2161 Returns the current guid if current mode is 1.
2162 @param mode
2163 Returns the current value.
2164 @return
2165 <=0 = error, 1 = success
2166 */
2167 int isoburn_igopt_get_gpt_guid(struct isoburn_imgen_opts *opts,
2168 uint8_t guid[16], int *mode);
2169
2170
2171 /** Set a name for the system area. This setting is ignored unless system area
2172 type 3 "SUN Disk Label" is in effect by iso_write_opts_set_system_area().
2173 In this case it will replace the default text at the start of the image:
2174 "CD-ROM Disc with Sun sparc boot created by libisofs"
2175 @since 0.6.6
2176 @param opts
2177 The option set to be manipulated.
2178 @param label
2179 A text of up to 128 characters.
2180 @return
2181 <=0 = error, 1 = success
2182 */
2183 int isoburn_igopt_set_disc_label(struct isoburn_imgen_opts *opts, char *label);
2184
2185 /** Inquire the current setting made by isoburn_igopt_set_disc_label().
2186 @since 0.6.6
2187 @param opts
2188 The option set to be inquired.
2189 @param label
2190 Returns a pointer to the currently set label string.
2191 Do not alter this string.
2192 Use only as long as the opts object exists.
2193 @return
2194 <=0 = error, 1 = success
2195 */
2196 int isoburn_igopt_get_disc_label(struct isoburn_imgen_opts *opts,
2197 char **label);
2198
2199 /** Set a serial number for the HFS+ extension of the emerging ISO image.
2200 @since 1.2.4
2201 @param opts
2202 The option set to be manipulated.
2203 @param serial_number
2204 8 bytes which should be unique to the image.
2205 If all bytes are 0, then the serial number will be generated as
2206 random number by libisofs. This is the default setting.
2207 @return
2208 <=0 = error, 1 = success
2209 */
2210 int isoburn_igopt_set_hfsp_serial_number(struct isoburn_imgen_opts *opts,
2211 uint8_t serial_number[8]);
2212
2213
2214 /** Inquire the current setting made by isoburn_igopt_set_disc_label()
2215 @since 1.2.4
2216 @param opts
2217 The option set to be inquired.
2218 @param serial_number
2219 Will get filled with the current setting.
2220 @return
2221 <=0 = error, 1 = success
2222 */
2223 int isoburn_igopt_get_hfsp_serial_number(struct isoburn_imgen_opts *opts,
2224 uint8_t serial_number[8]);
2225
2226 /** Set the allocation block size for HFS+ production and the block size
2227 for layout and address unit of Apple Partition map.
2228 @since 1.2.4
2229 @param opts
2230 The option set to be manipulated.
2231 @param hfsp_block_size
2232 -1 means that this setting shall be left unchanged
2233 0 allows the automatic default setting
2234 512 and 2048 enforce a size.
2235 @param apm_block_size
2236 -1 means that this setting shall be left unchanged
2237 0 allows the automatic default setting
2238 512 and 2048 enforce a size.
2239 Size 512 cannot be combined with GPT production.
2240 Size 2048 cannot be mounted -t hfsplus by Linux kernels at least up
2241 to 2.6.32.
2242 @return
2243 <=0 = error, 1 = success
2244 */
2245 int isoburn_igopt_set_hfsp_block_size(struct isoburn_imgen_opts *opts,
2246 int hfsp_block_size, int apm_block_size);
2247
2248 /** Inquire the current setting made by isoburn_igopt_set_hfsp_block_size
2249 @since 1.2.4
2250 @param opts
2251 The option set to be inquired.
2252 @param hfsp_block_size
2253 Will be set to a value as described above. Except -1.
2254 @param apm_block_size
2255 Will be set to a value as described above. Except -1.
2256 @return
2257 <=0 = error, 1 = success
2258 */
2259 int isoburn_igopt_get_hfsp_block_size(struct isoburn_imgen_opts *opts,
2260 int *hfsp_block_size, int *apm_block_size);
2261
2262
2263 /** Set or inquire the write type for the next write run on optical media.
2264 @since 1.2.4
2265 @param opts
2266 The option set to be manipulated or inquired.
2267 @param do_tao
2268 The value to be set or the variable where to return the current
2269 setting:
2270 0 = Let libburn choose according to other write parameters.
2271 This is advisable unless there are particular reasons not to
2272 use one of the two write types. Be aware that 1 and -1 can
2273 lead to failure if the write type is not appropriate for
2274 the given media situation.
2275 1 = Use BURN_WRITE_TAO which does
2276 TAO on CD, Incremental on DVD-R,
2277 no track reservation on DVD+R and BD-R
2278 -1 = Use BURN_WRITE_SAO which does
2279 SAO on CD, DAO on DVD-R,
2280 track reservation on DVD+R and BD-R
2281 @return
2282 <=0 = error, 1 = success
2283 */
2284 int isoburn_igopt_set_write_type(struct isoburn_imgen_opts *opts, int do_tao);
2285 int isoburn_igopt_get_write_type(struct isoburn_imgen_opts *opts, int *do_tao);
2286
2287 /** Set or inquire whether a final fsync(2) is performed when updating the
2288 multi-session information of libburn stdio pseudo-drives by
2289 isoburn_activate_session().
2290 Note:
2291 fsync(2) calls during and at the end of isoburn_disc_write() are controlled
2292 by libburn call burn_write_opts_set_stdio_fsync().
2293 @since 1.2.4
2294 @param opts
2295 The option set to be manipulated or inquired.
2296 @param do_sync
2297 1= call fsync(2) with stdio drives in isoburn_activate_session()
2298 0= do not
2299 @return
2300 <=0 = error, 1 = success
2301 */
2302 int isoburn_igopt_set_stdio_endsync(struct isoburn_imgen_opts *opts,
2303 int do_sync);
2304 int isoburn_igopt_get_stdio_endsync(struct isoburn_imgen_opts *opts,
2305 int *do_sync);
2306
2307 /* ----------------------------------------------------------------------- */
2308 /* End of Options for image generation */
2309 /* ----------------------------------------------------------------------- */
2310
2311
2312 /** Frontend of libisofs call iso_conv_name_chars() controlled by
2313 struct isoburn_imgen_opts rather than IsoWriteOpts.
2314 See libisofs.h for a more detailed description.
2315 @since 1.3.6
2316 @param opts
2317 Defines options like output charset, UCS-2 versus UTF-16 for Joliet,
2318 and naming restrictions.
2319 @param name
2320 The input text which shall be converted.
2321 @param name_len
2322 The number of bytes in input text.
2323 @param result
2324 Will return the conversion result in case of success. Terminated by
2325 a trailing zero byte.
2326 Use free() to dispose it when no longer needed.
2327 @param result_len
2328 Will return the number of bytes in result (excluding trailing zero)
2329 @param flag
2330 Bitfield for control purposes.
2331 bit0-bit7= Name space
2332 0= generic (to_charset is valid,
2333 no reserved characters, no length limits)
2334 1= Rock Ridge (to_charset is valid)
2335 2= Joliet (to_charset gets overridden by UCS-2 or UTF-16)
2336 3= ECMA-119 (to_charset gets overridden by the
2337 dull ISO 9660 subset of ASCII)
2338 4= HFS+ (to_charset gets overridden by UTF-16BE)
2339 bit8= Treat input text as directory name
2340 (matters for Joliet and ECMA-119)
2341 bit9= Do not issue error messages
2342 bit15= Reverse operation (best to be done only with results of
2343 previous conversions)
2344 @return
2345 1 means success, <=0 means error
2346 */
2347 int isoburn_conv_name_chars(struct isoburn_imgen_opts *opts,
2348 char *name, size_t name_len,
2349 char **result, size_t *result_len, int flag);
2350
2351
2352 /** Get the image attached to a drive, if any.
2353 @since 0.1.0
2354 @param d The drive to inquire
2355 @return A reference to attached image, or NULL if the drive has no image
2356 attached. This reference needs to be released via iso_image_unref()
2357 when it is not longer needed.
2358 */
2359 IsoImage *isoburn_get_attached_image(struct burn_drive *d);
2360
2361 /** Get the start address of the image that is attached to the drive, if any.
2362 @since 1.2.2
2363 @param d The drive to inquire
2364 @return The logical block address where the System Area of the image
2365 starts. <0 means that the address is invalid.
2366 */
2367 int isoburn_get_attached_start_lba(struct burn_drive *d);
2368
2369
2370 /** Load the ISO filesystem directory tree from the medium in the given drive.
2371 This will give libisoburn the base on which it can let libisofs perform
2372 image growing or image modification. The loaded volset gets attached
2373 to the drive object and handed out to the application.
2374 Not a wrapper, but peculiar to libisoburn.
2375 @since 0.1.0
2376 @param d The drive which holds an existing ISO filesystem or blank media.
2377 d is allowed to be NULL which produces an empty ISO image. In
2378 this case one has to call before writing isoburn_attach_volset()
2379 with the volset from this call and with the intended output
2380 drive.
2381 @param read_opts The read options which can be chosen by the application
2382 @param image the image read, if the disc is blank it will have no files.
2383 This reference needs to be released via iso_image_unref() when
2384 it is not longer needed. The drive, if not NULL, will hold an
2385 own reference which it will release when it gets a new volset
2386 or when it gets released via isoburn_drive_release().
2387 You can pass NULL if you already have a reference or you plan to
2388 obtain it later with isoburn_get_attached_image(). Of course, if
2389 you haven't specified a valid drive (i.e., if d == NULL), this
2390 parameter can't be NULL.
2391 @return <=0 error , 1 = success
2392 */
2393 int isoburn_read_image(struct burn_drive *d,
2394 struct isoburn_read_opts *read_opts,
2395 IsoImage **image);
2396
2397 /** Set a callback function for producing pacifier messages during the lengthy
2398 process of image reading. The callback function and the application handle
2399 are stored until they are needed for the underlying call to libisofs.
2400 Other than with libisofs the handle is managed entirely by the application.
2401 An idle .free() function is exposed to libisofs. The handle has to stay
2402 valid until isoburn_read_image() is done. It has to be detached by
2403 isoburn_set_read_pacifier(drive, NULL, NULL);
2404 before it may be removed from memory.
2405 @since 0.1.0
2406 @param drive The drive which will be used with isoburn_read_image()
2407 It has to be acquired by an isoburn_* wrapper call.
2408 @param read_pacifier The callback function
2409 @param app_handle The app handle which the callback function can obtain
2410 via iso_image_get_attached_data() from its IsoImage*
2411 @return 1 success, <=0 failure
2412 */
2413 int isoburn_set_read_pacifier(struct burn_drive *drive,
2414 int (*read_pacifier)(IsoImage*, IsoFileSource*),
2415 void *app_handle);
2416
2417 /** Inquire the partition offset of the loaded image. The first 512 bytes of
2418 the image get examined whether they bear an MBR signature and a first
2419 partition table entry which matches the size of the image. In this case
2420 the start address is recorded as partition offset and internal buffers
2421 get adjusted.
2422 See also isoburn_igopt_set_part_offset().
2423 @since 0.6.2
2424 @param drive The drive with the loaded image
2425 @param block_offset_2k returns the recognized partition offset
2426 @return <0 = error
2427 0 = no partition offset recognized
2428 1 = acceptable non-zero offset, buffers are adjusted
2429 2 = offset is credible but not acceptable for buffer size
2430 */
2431 int isoburn_get_img_partition_offset(struct burn_drive *drive,
2432 uint32_t *block_offset_2k);
2433
2434
2435 /** Set the IsoImage to be used with a drive. This eventually releases
2436 the reference to the old IsoImage attached to the drive.
2437 Caution: Use with care. It hardly makes sense to replace an image that
2438 reflects a valid ISO image on the medium.
2439 This call is rather intended for writing a newly created and populated
2440 image to blank media. The use case in xorriso is to let an image survive
2441 the change or demise of the outdev target drive.
2442 @since 0.1.0
2443 @param d The drive which shall be write target of the volset.
2444 @param image The image that represents the image to be written.
2445 This image pointer MUST already be a valid reference suitable
2446 for iso_image_unref().
2447 It may have been obtained by appropriate libisofs calls or by
2448 isoburn_read_image() with d==NULL.
2449 @return <=0 error , 1 = success
2450 */
2451 int isoburn_attach_image(struct burn_drive *d, IsoImage *image);
2452
2453
2454 /** Set the start address of the image that is attached to the drive, if any.
2455 @since 1.2.2
2456 @param d The drive to inquire
2457 @param lba The logical block address where the System Area of the image
2458 starts. <0 means that the address is invalid.
2459 @param flag Bitfield, submit 0 for now.
2460 @return <=0 error (e.g. because no image is attached), 1 = success
2461 */
2462 int isoburn_attach_start_lba(struct burn_drive *d, int lba, int flag);
2463
2464
2465 /** Return the best possible estimation of the currently available capacity of
2466 the medium. This might depend on particular write option settings and on
2467 drive state.
2468 An eventual start address for emulated multi-session will be subtracted
2469 from the capacity estimation given by burn_disc_available_space().
2470 Negative results get defaulted to 0.
2471 Wrapper for: burn_disc_available_space()
2472 @since 0.1.0
2473 @param d The drive to query.
2474 @param o If not NULL: write parameters to be set on drive before query
2475 @return number of most probably available free bytes
2476 */
2477 off_t isoburn_disc_available_space(struct burn_drive *d,
2478 struct burn_write_opts *o);
2479
2480
2481 /** Obtain the start block number of the most recent session on the medium. In
2482 case of random access media this will normally be 0. Successful return is
2483 not a guarantee that there is a ISO-9660 image at all. The call will fail,
2484 nevertheless,if isoburn_disc_get_status() returns not BURN_DISC_APPENDABLE
2485 or BURN_DISC_FULL.
2486 Note: The result of this call may be fabricated by a previous call of
2487 isoburn_set_msc1() which can override the rule to load the most recent
2488 session.
2489 Wrapper for: burn_disc_get_msc1()
2490 @since 0.1.0
2491 @param d The drive to inquire
2492 @param start_lba Contains on success the start address in 2048 byte blocks
2493 @return <=0 error , 1 = success
2494 */
2495 int isoburn_disc_get_msc1(struct burn_drive *d, int *start_lba);
2496
2497
2498 /** Use this with trackno==0 to obtain the predicted start block number of the
2499 new session. The interesting number is returned in parameter nwa.
2500 Wrapper for: burn_disc_track_lba_nwa()
2501 @since 0.1.0
2502 @param d The drive to inquire
2503 @param o If not NULL: write parameters to be set on drive before query
2504 @param trackno Submit 0.
2505 @param lba return value: start lba
2506 @param nwa return value: Next Writeable Address
2507 @return 1=nwa is valid , 0=nwa is not valid , -1=error
2508 */
2509 int isoburn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o,
2510 int trackno, int *lba, int *nwa);
2511
2512
2513 /** Obtain the size which was attributed to an emulated appendable on actually
2514 overwritable media. This value is supposed to be <= 2048 * nwa as of
2515 isoburn_disc_track_lba_nwa().
2516 @since 0.1.0
2517 @param d The drive holding the medium.
2518 @param start_byte The reply value counted in bytes, not in sectors.
2519 @param flag Unused yet. Submit 0.
2520 @return 1=stat_byte is valid, 0=not an emulated appendable, -1=error
2521 */
2522 int isoburn_get_min_start_byte(struct burn_drive *d, off_t *start_byte,
2523 int flag);
2524
2525
2526 /** Start production of an ISO 9660 image using the method of Growing:
2527 Create a disc object for writing the new session from the created or loaded
2528 iso_volset which has been manipulated via libisofs, to the same medium from
2529 where the image was eventually loaded.
2530 This call starts a libisofs thread which begins to produce the image.
2531 It has to be revoked by isoburn_cancel_prepared_write() if for some reason
2532 this image data stream shall not be consumed.
2533 The returned struct burn_disc is ready for use by a subsequent call to
2534 isoburn_disc_write(). After this asynchronous writing has ended and the
2535 drive is BURN_DRIVE_IDLE again, the burn_disc object has to be disposed
2536 by burn_disc_free().
2537 @since 0.1.0
2538 @param drive The combined source and target drive, grabbed with
2539 isoburn_drive_scan_and_grab(). .
2540 @param disc Returns the newly created burn_disc object.
2541 @param opts Image generation options, see isoburn_igopt_*()
2542 @return <=0 error , 1 = success
2543 */
2544 int isoburn_prepare_disc(struct burn_drive *drive, struct burn_disc **disc,
2545 struct isoburn_imgen_opts *opts);
2546
2547
2548 /** Start production of an ISO 9660 image using the method of Modifying:
2549 Create a disc object for producing a new image from a previous image
2550 plus the changes made by user. The generated burn_disc is suitable
2551 to be written to a grabbed drive with blank writeable medium.
2552 But you must not use the same drive for input and output, because data
2553 will be read from the source drive while at the same time the target
2554 drive is already writing.
2555 This call starts a libisofs thread which begins to produce the image.
2556 It has to be revoked by isoburn_cancel_prepared_write() if for some reason
2557 this image data stream shall not be consumed.
2558 The resulting burn_disc object has to be disposed when all its writing
2559 is done and the drive is BURN_DRIVE_IDLE again after asynchronous
2560 burn_disc_write().
2561 @since 0.1.0
2562 @param in_drive The input drive, grabbed with isoburn_drive_aquire() or
2563 one of its alternatives.
2564 @param disc Returns the newly created burn_disc object.
2565 @param opts Options for image generation and data transport to the
2566 medium.
2567 @param out_drive The output drive, from isoburn_drive_aquire() et.al..
2568 @return <=0 error , 1 = success
2569 */
2570 int isoburn_prepare_new_image(struct burn_drive *in_drive,
2571 struct burn_disc **disc,
2572 struct isoburn_imgen_opts *opts,
2573 struct burn_drive *out_drive);
2574
2575
2576 /** Start production of an ISO 9660 image using the method of Blind Growing:
2577 Create a disc object for writing an add-on session from the created or
2578 loaded IsoImage which has been manipulated via libisofs, to a different
2579 drive than the one from where it was loaded.
2580 Usually output will be stdio:/dev/fd/1 (i.e. stdout) being piped
2581 into some burn program like with this classic gesture:
2582 mkisofs -M $dev -C $msc1,$nwa | cdrecord -waiti dev=$dev
2583 Parameter translation into libisoburn:
2584 $dev is the address by which parameter in_drive of this call was
2585 acquired $msc1 was set by isoburn_set_msc1() before image reading
2586 or was detected from the in_drive medium
2587 $nwa is a parameter of this call
2588 or can be used as detected from the in_drive medium
2589
2590 This call starts a libisofs thread which begins to produce the image.
2591 It has to be revoked by isoburn_cancel_prepared_write() if for some reason
2592 this image data stream shall not be consumed.
2593 This call waits for libisofs output to become available and then detaches
2594 the input drive object from the data source object by which libisofs was
2595 reading from the input drive.
2596 So, as far as libisofs is concerned, that drive may be released immediately
2597 after this call in order to allow the consumer to access the drive for
2598 writing.
2599 The consumer should wait for input to become available and only then open
2600 its burn drive. With cdrecord this is caused by option -waiti.
2601
2602 The resulting burn_disc object has to be disposed when all its writing
2603 is done and the drive is BURN_DRIVE_IDLE again after asynchronous
2604 burn_disc_write().
2605 @since 0.2.2
2606 @param in_drive The input drive,grabbed with isoburn_drive_scan_and_grab().
2607 @param disc Returns the newly created burn_disc object.
2608 @param opts Options for image generation and data transport to media.
2609 @param out_drive The output drive, from isoburn_drive_aquire() et.al..
2610 typically stdio:/dev/fd/1 .
2611 @param nwa The address (2048 byte block count) where the add-on
2612 session will be finally stored on a mountable medium
2613 or in a mountable file.
2614 If nwa is -1 then the address is used as determined from
2615 the in_drive medium.
2616 @return <=0 error , 1 = success
2617 */
2618 int isoburn_prepare_blind_grow(struct burn_drive *in_drive,
2619 struct burn_disc **disc,
2620 struct isoburn_imgen_opts *opts,
2621 struct burn_drive *out_drive, int nwa);
2622
2623
2624 /**
2625 Revoke isoburn_prepare_*() instead of running isoburn_disc_write().
2626 libisofs reserves resources and maybe already starts generating the
2627 image stream when one of above three calls is performed. It is mandatory to
2628 either run isoburn_disc_write() or to revoke the preparations by the
2629 call described here.
2630 If this call returns 0 or 1 then the write thread of libisofs has ended.
2631 @since 0.1.0
2632 @param input_drive The drive or in_drive which was used with the
2633 preparation call.
2634 @param output_drive The out_drive used with isoburn_prepare_new_image(),
2635 NULL if none.
2636 @param flag Bitfield, submit 0 for now.
2637 bit0= -reserved for internal use-
2638 @return <0 error, 0= no pending preparations detectable, 1 = canceled
2639 */
2640 int isoburn_cancel_prepared_write(struct burn_drive *input_drive,
2641 struct burn_drive *output_drive, int flag);
2642
2643
2644 /**
2645 Override the truncation setting that was made with flag bit2 during the
2646 call of isoburn_drive_aquire. This applies only to stdio pseudo drives.
2647 @since 0.1.6
2648 @param drive The drive which was acquired and shall be used for writing.
2649 @param flag Bitfield controlling the setting:
2650 bit0= truncate (else do not truncate)
2651 bit1= do not warn if call is inappropriate to drive
2652 bit2= only set if truncation is currently enabled
2653 do not warn if call is inappropriate to drive
2654 @return 1 success, 0 inappropriate drive, <0 severe error
2655 */
2656 int isoburn_set_truncate(struct burn_drive *drive, int flag);
2657
2658
2659 /** Start writing of the new session.
2660 This call is asynchronous. I.e. it returns quite soon and the progress has
2661 to be watched by a loop with call burn_drive_get_status() until
2662 BURN_DRIVE_IDLE is returned.
2663 Wrapper for: burn_disc_write()
2664 @since 0.1.0
2665 @param o Options which control the burn process. See burnwrite_opts_*()
2666 in libburn.h.
2667 @param disc Disc object created either by isoburn_prepare_disc() or by
2668 isoburn_prepare_new_image().
2669 */
2670 void isoburn_disc_write(struct burn_write_opts *o, struct burn_disc *disc);
2671
2672
2673 /** Inquire state and fill parameters of the fifo which is attached to
2674 the emerging track. This should be done in the pacifier loop while
2675 isoburn_disc_write() or burn_disc_write() are active.
2676 This works only with drives obtained by isoburn_drive_scan_and_grab()
2677 or isoburn_drive_grab(). If isoburn_prepare_new_image() was used, then
2678 parameter out_drive must have announced the track output drive.
2679 Hint: If only burn_write_opts and not burn_drive is known, then the drive
2680 can be obtained by burn_write_opts_get_drive().
2681 @since 0.1.0
2682 @param d The drive to which the track with the fifo gets burned.
2683 @param size The total size of the fifo
2684 @param free_bytes The current free capacity of the fifo
2685 @param status_text Returns a pointer to a constant text, see below
2686 @return <0 reply invalid, >=0 fifo status code:
2687 bit0+1=input status, bit2=consumption status, i.e:
2688 0="standby" : data processing not started yet
2689 1="active" : input and consumption are active
2690 2="ending" : input has ended without error
2691 3="failing" : input had error and ended,
2692 4="unused" : ( consumption has ended before processing start )
2693 5="abandoned" : consumption has ended prematurely
2694 6="ended" : consumption has ended without input error
2695 7="aborted" : consumption has ended after input error
2696 */
2697 int isoburn_get_fifo_status(struct burn_drive *d, int *size, int *free_bytes,
2698 char **status_text);
2699
2700
2701 /** Inquire whether the most recent write run was successful.
2702 Wrapper for: burn_drive_wrote_well()
2703 @since 0.1.0
2704 @param d The drive to inquire
2705 @return 1=burn seems to have went well, 0=burn failed
2706 */
2707 int isoburn_drive_wrote_well(struct burn_drive *d);
2708
2709
2710 /** Call this after isoburn_disc_write has finished and burn_drive_wrote_well()
2711 indicates success. It will eventually complete the emulation of
2712 multi-session functionality, if needed at all. Let libisoburn decide.
2713 Not a wrapper, but peculiar to libisoburn.
2714 @since 0.1.0
2715 @param d The output drive to which the session was written
2716 @return 1 success , <=0 failure
2717 */
2718 int isoburn_activate_session(struct burn_drive *d);
2719
2720
2721 /** Wait after normal end of operations until libisofs ended all write
2722 threads and freed resource reservations.
2723 This call is not mandatory. But without it, messages from the ending
2724 threads might appear after the application ended its write procedure.
2725 @since 0.1.0
2726 @param input_drive The drive or in_drive which was used with the
2727 preparation call.
2728 @param output_drive The out_drive used with isoburn_prepare_new_image(),
2729 NULL if none.
2730 @param flag Bitfield, submit 0 for now.
2731 @return <=0 error , 1 = success
2732 */
2733 int isoburn_sync_after_write(struct burn_drive *input_drive,
2734 struct burn_drive *output_drive, int flag);
2735
2736
2737 /** Release an acquired drive.
2738 Wrapper for: burn_drive_release()
2739 @since 0.1.0
2740 @param drive The drive to be released
2741 @param eject 1= eject medium from drive , 0= do not eject
2742 */
2743 void isoburn_drive_release(struct burn_drive *drive, int eject);
2744
2745
2746 /** Shutdown all three libraries.
2747 Wrapper for : iso_finish() and burn_finish().
2748 @since 0.1.0
2749 */
2750 void isoburn_finish(void);
2751
2752
2753 /*
2754 The following calls are for expert applications only.
2755 An application should have a special reason to use them.
2756 */
2757
2758
2759 /** Inquire whether the medium needs emulation or would be suitable for
2760 generic multi-session via libburn.
2761 @since 0.1.0
2762 @param d The drive to inquire
2763 @return 0 is generic multi-session
2764 1 is emulated multi-session
2765 -1 is not suitable for isoburn
2766 */
2767 int isoburn_needs_emulation(struct burn_drive *d);
2768
2769
2770 /* ---------------------------- Test area ----------------------------- */
2771
2772 /* no tests active, currently */
2773
2774 #ifdef __cplusplus
2775 } /* extern "C" */
2776 #endif
2777
2778 #endif /* LIBISOBURN_LIBISOBURN_H_ */
2779