00001 /* -*- indent-tabs-mode: t; tab-width: 8; c-basic-offset: 8; -*- */ 00002 00003 #ifndef LIBBURN_H 00004 #define LIBBURN_H 00005 00006 /* Needed for off_t which is the (POSIX-ly) appropriate type for 00007 expressing a file or stream size. 00008 00009 XXX we should enforce 64-bitness for off_t 00010 ts A61101 : this is usually done by the build system (if it is not broken) 00011 */ 00012 #include <sys/types.h> 00013 00014 #ifndef DOXYGEN 00015 00016 #if defined(__cplusplus) 00017 #define BURN_BEGIN_DECLS \ 00018 namespace burn { \ 00019 extern "C" { 00020 #define BURN_END_DECLS \ 00021 } \ 00022 } 00023 #else 00024 #define BURN_BEGIN_DECLS 00025 #define BURN_END_DECLS 00026 #endif 00027 00028 BURN_BEGIN_DECLS 00029 00030 #endif 00031 00032 /** References a physical drive in the system */ 00033 struct burn_drive; 00034 00035 /** References a whole disc */ 00036 struct burn_disc; 00037 00038 /** References a single session on a disc */ 00039 struct burn_session; 00040 00041 /** References a single track on a disc */ 00042 struct burn_track; 00043 00044 /* ts A61111 */ 00045 /** References a set of write parameters */ 00046 struct burn_write_opts; 00047 00048 /** Session format for normal audio or data discs */ 00049 #define BURN_CDROM 0 00050 /** Session format for obsolete CD-I discs */ 00051 #define BURN_CDI 0x10 00052 /** Session format for CDROM-XA discs */ 00053 #define BURN_CDXA 0x20 00054 00055 #define BURN_POS_END 100 00056 00057 /** Mask for mode bits */ 00058 #define BURN_MODE_BITS 127 00059 00060 /** Track mode - mode 0 data 00061 0 bytes of user data. it's all 0s. mode 0. get it? HAH 00062 */ 00063 #define BURN_MODE0 (1 << 0) 00064 /** Track mode - mode "raw" - all 2352 bytes supplied by app 00065 FOR DATA TRACKS ONLY! 00066 */ 00067 #define BURN_MODE_RAW (1 << 1) 00068 /** Track mode - mode 1 data 00069 2048 bytes user data, and all the LEC money can buy 00070 */ 00071 #define BURN_MODE1 (1 << 2) 00072 /** Track mode - mode 2 data 00073 defaults to formless, 2336 bytes of user data, unprotected 00074 | with a data form if required. 00075 */ 00076 #define BURN_MODE2 (1 << 3) 00077 /** Track mode modifier - Form 1, | with MODE2 for reasonable results 00078 2048 bytes of user data, 4 bytes of subheader 00079 */ 00080 #define BURN_FORM1 (1 << 4) 00081 /** Track mode modifier - Form 2, | with MODE2 for reasonable results 00082 lots of user data. not much LEC. 00083 */ 00084 #define BURN_FORM2 (1 << 5) 00085 /** Track mode - audio 00086 2352 bytes per sector. may be | with 4ch or preemphasis. 00087 NOT TO BE CONFUSED WITH BURN_MODE_RAW 00088 Audio data must be 44100Hz 16bit stereo with no riff or other header at 00089 beginning. Extra header data will cause pops or clicks. Audio data should 00090 also be in little-endian byte order. Big-endian audio data causes static. 00091 */ 00092 #define BURN_AUDIO (1 << 6) 00093 /** Track mode modifier - 4 channel audio. */ 00094 #define BURN_4CH (1 << 7) 00095 /** Track mode modifier - Digital copy permitted, can be set on any track.*/ 00096 #define BURN_COPY (1 << 8) 00097 /** Track mode modifier - 50/15uS pre-emphasis */ 00098 #define BURN_PREEMPHASIS (1 << 9) 00099 /** Input mode modifier - subcodes present packed 16 */ 00100 #define BURN_SUBCODE_P16 (1 << 10) 00101 /** Input mode modifier - subcodes present packed 96 */ 00102 #define BURN_SUBCODE_P96 (1 << 11) 00103 /** Input mode modifier - subcodes present raw 96 */ 00104 #define BURN_SUBCODE_R96 (1 << 12) 00105 00106 /** Possible disc writing style/modes */ 00107 enum burn_write_types 00108 { 00109 /** Packet writing. 00110 currently unsupported, (for DVD Incremental Streaming use TAO) 00111 */ 00112 BURN_WRITE_PACKET, 00113 00114 /** With CD: Track At Once recording 00115 2s gaps between tracks, no fonky lead-ins 00116 00117 With sequential DVD-R[W]: Incremental Streaming 00118 With DVD-RAM/+RW: Random Writeable (used sequentially) 00119 With overwriteable DVD-RW: Rigid Restricted Overwrite 00120 */ 00121 BURN_WRITE_TAO, 00122 00123 /** With CD: Session At Once 00124 Block type MUST be BURN_BLOCK_SAO 00125 ts A70122: Currently not capable of mixing data and audio tracks. 00126 00127 With sequential DVD-R[W]: Disc-at-once, DAO 00128 Single session, single track, fixed size mandatory, (-dvd-compat) 00129 */ 00130 BURN_WRITE_SAO, 00131 00132 /** With CD: Raw disc at once recording. 00133 all subcodes must be provided by lib or user 00134 only raw block types are supported 00135 */ 00136 BURN_WRITE_RAW, 00137 00138 /** In replies this indicates that not any writing will work. 00139 As parameter for inquiries it indicates that no particular write 00140 mode shall is specified. 00141 Do not use for setting a write mode for burning. It won't work. 00142 */ 00143 BURN_WRITE_NONE 00144 }; 00145 00146 /** Data format to send to the drive */ 00147 enum burn_block_types 00148 { 00149 /** sync, headers, edc/ecc provided by lib/user */ 00150 BURN_BLOCK_RAW0 = 1, 00151 /** sync, headers, edc/ecc and p/q subs provided by lib/user */ 00152 BURN_BLOCK_RAW16 = 2, 00153 /** sync, headers, edc/ecc and packed p-w subs provided by lib/user */ 00154 BURN_BLOCK_RAW96P = 4, 00155 /** sync, headers, edc/ecc and raw p-w subs provided by lib/user */ 00156 BURN_BLOCK_RAW96R = 8, 00157 /** only 2048 bytes of user data provided by lib/user */ 00158 BURN_BLOCK_MODE1 = 256, 00159 /** 2336 bytes of user data provided by lib/user */ 00160 BURN_BLOCK_MODE2R = 512, 00161 /** 2048 bytes of user data provided by lib/user 00162 subheader provided in write parameters 00163 are we ever going to support this shit? I vote no. 00164 (supposed to be supported on all drives...) 00165 */ 00166 BURN_BLOCK_MODE2_PATHETIC = 1024, 00167 /** 2048 bytes of data + 8 byte subheader provided by lib/user 00168 hey, this is also dumb 00169 */ 00170 BURN_BLOCK_MODE2_LAME = 2048, 00171 /** 2324 bytes of data provided by lib/user 00172 subheader provided in write parameters 00173 no sir, I don't like it. 00174 */ 00175 BURN_BLOCK_MODE2_OBSCURE = 4096, 00176 /** 2332 bytes of data supplied by lib/user 00177 8 bytes sub header provided in write parameters 00178 this is the second least suck mode2, and is mandatory for 00179 all drives to support. 00180 */ 00181 BURN_BLOCK_MODE2_OK = 8192, 00182 /** SAO block sizes are based on cue sheet, so use this. */ 00183 BURN_BLOCK_SAO = 16384 00184 }; 00185 00186 /** Possible status' of the drive in regard to the disc in it. */ 00187 enum burn_disc_status 00188 { 00189 /** The current status is not yet known */ 00190 BURN_DISC_UNREADY, 00191 /** The drive holds a blank disc */ 00192 BURN_DISC_BLANK, 00193 /** There is no disc at all in the drive */ 00194 BURN_DISC_EMPTY, 00195 /** There is an incomplete disc in the drive */ 00196 BURN_DISC_APPENDABLE, 00197 /** There is a disc with data on it in the drive */ 00198 BURN_DISC_FULL, 00199 00200 /* ts A61007 */ 00201 /** The drive was not grabbed when the status was inquired */ 00202 BURN_DISC_UNGRABBED, 00203 00204 /* ts A61020 */ 00205 /** The media seems not to be suitable for burning */ 00206 BURN_DISC_UNSUITABLE 00207 }; 00208 00209 00210 /** Possible data source return values */ 00211 enum burn_source_status 00212 { 00213 /** The source is ok */ 00214 BURN_SOURCE_OK, 00215 /** The source is at end of file */ 00216 BURN_SOURCE_EOF, 00217 /** The source is unusable */ 00218 BURN_SOURCE_FAILED 00219 }; 00220 00221 00222 /** Possible busy states for a drive */ 00223 enum burn_drive_status 00224 { 00225 /** The drive is not in an operation */ 00226 BURN_DRIVE_IDLE, 00227 /** The library is spawning the processes to handle a pending 00228 operation (A read/write/etc is about to start but hasn't quite 00229 yet) */ 00230 BURN_DRIVE_SPAWNING, 00231 /** The drive is reading data from a disc */ 00232 BURN_DRIVE_READING, 00233 /** The drive is writing data to a disc */ 00234 BURN_DRIVE_WRITING, 00235 /** The drive is writing Lead-In */ 00236 BURN_DRIVE_WRITING_LEADIN, 00237 /** The drive is writing Lead-Out */ 00238 BURN_DRIVE_WRITING_LEADOUT, 00239 /** The drive is erasing a disc */ 00240 BURN_DRIVE_ERASING, 00241 /** The drive is being grabbed */ 00242 BURN_DRIVE_GRABBING, 00243 00244 /* ts A61102 */ 00245 /** The drive gets written zeroes before the track payload data */ 00246 BURN_DRIVE_WRITING_PREGAP, 00247 /** The drive is told to close a track (TAO only) */ 00248 BURN_DRIVE_CLOSING_TRACK, 00249 /** The drive is told to close a session (TAO only) */ 00250 BURN_DRIVE_CLOSING_SESSION, 00251 00252 /* ts A61223 */ 00253 /** The drive is formatting media */ 00254 BURN_DRIVE_FORMATTING 00255 00256 }; 00257 00258 00259 /** Information about a track on a disc - this is from the q sub channel of the 00260 lead-in area of a disc. The documentation here is very terse. 00261 See a document such as mmc3 for proper information. 00262 00263 CAUTION : This structure is prone to future extension ! 00264 00265 Do not restrict your application to unsigned char with any counter like 00266 "session", "point", "pmin", ... 00267 Do not rely on the current size of a burn_toc_entry. 00268 00269 ts A70201 : DVD extension, see below 00270 */ 00271 struct burn_toc_entry 00272 { 00273 /** Session the track is in */ 00274 unsigned char session; 00275 /** Type of data. for this struct to be valid, it must be 1 */ 00276 unsigned char adr; 00277 /** Type of data in the track */ 00278 unsigned char control; 00279 /** Zero. Always. Really. */ 00280 unsigned char tno; 00281 /** Track number or special information */ 00282 unsigned char point; 00283 unsigned char min; 00284 unsigned char sec; 00285 unsigned char frame; 00286 unsigned char zero; 00287 /** Track start time minutes for normal tracks */ 00288 unsigned char pmin; 00289 /** Track start time seconds for normal tracks */ 00290 unsigned char psec; 00291 /** Track start time frames for normal tracks */ 00292 unsigned char pframe; 00293 00294 /* Indicates wether extension data are valid and eventually override 00295 older elements in this structure: 00296 bit0= DVD extension is valid 00297 */ 00298 unsigned char extensions_valid; 00299 00300 /* ts A70201 : DVD extension. 00301 If invalid the members are guaranteed to be 0. */ 00302 /* Tracks and session numbers are 16 bit. Here are the high bytes. */ 00303 unsigned char session_msb; 00304 unsigned char point_msb; 00305 /* pmin, psec, and pframe may be too small if DVD extension is valid */ 00306 int start_lba; 00307 /* min, sec, and frame may be too small if DVD extension is valid */ 00308 int track_blocks; 00309 00310 }; 00311 00312 00313 /** Data source for tracks */ 00314 struct burn_source { 00315 /** Reference count for the data source. Should be 1 when a new source 00316 is created. Increment it to take a reference for yourself. Use 00317 burn_source_free to destroy your reference to it. */ 00318 int refcount; 00319 00320 /** Read data from the source */ 00321 int (*read)(struct burn_source *, 00322 unsigned char *buffer, 00323 int size); 00324 00325 /** Read subchannel data from the source (NULL if lib generated) */ 00326 int (*read_sub)(struct burn_source *, 00327 unsigned char *buffer, 00328 int size); 00329 00330 /** Get the size of the source's data */ 00331 off_t (*get_size)(struct burn_source *); 00332 00333 /** Set the size of the source's data */ 00334 int (*set_size)(struct burn_source *source, off_t size); 00335 00336 /** Clean up the source specific data */ 00337 void (*free_data)(struct burn_source *); 00338 00339 /** Next source, for when a source runs dry and padding is disabled 00340 THIS IS AUTOMATICALLY HANDLED, DO NOT TOUCH 00341 */ 00342 struct burn_source *next; 00343 00344 /** Source specific data */ 00345 void *data; 00346 }; 00347 00348 00349 /** Information on a drive in the system */ 00350 struct burn_drive_info 00351 { 00352 /** Name of the vendor of the drive */ 00353 char vendor[9]; 00354 /** Name of the drive */ 00355 char product[17]; 00356 /** Revision of the drive */ 00357 char revision[5]; 00358 /** Location of the drive in the filesystem. */ 00359 char location[17]; 00360 /** This is currently the string which is used as persistent 00361 drive address. But be warned: there is NO GUARANTEE that this 00362 will stay so. Always use function burn_drive_get_adr() to 00363 inquire a persistent address. ^^^^^^ ALWAYS ^^^^^^ */ 00364 00365 /** Can the drive read DVD-RAM discs */ 00366 unsigned int read_dvdram:1; 00367 /** Can the drive read DVD-R discs */ 00368 unsigned int read_dvdr:1; 00369 /** Can the drive read DVD-ROM discs */ 00370 unsigned int read_dvdrom:1; 00371 /** Can the drive read CD-R discs */ 00372 unsigned int read_cdr:1; 00373 /** Can the drive read CD-RW discs */ 00374 unsigned int read_cdrw:1; 00375 00376 /** Can the drive write DVD-RAM discs */ 00377 unsigned int write_dvdram:1; 00378 /** Can the drive write DVD-R discs */ 00379 unsigned int write_dvdr:1; 00380 /** Can the drive write CD-R discs */ 00381 unsigned int write_cdr:1; 00382 /** Can the drive write CD-RW discs */ 00383 unsigned int write_cdrw:1; 00384 00385 /** Can the drive simulate a write */ 00386 unsigned int write_simulate:1; 00387 00388 /** Can the drive report C2 errors */ 00389 unsigned int c2_errors:1; 00390 00391 /** The size of the drive's buffer (in kilobytes) */ 00392 int buffer_size; 00393 /** 00394 * The supported block types in tao mode. 00395 * They should be tested with the desired block type. 00396 * See also burn_block_types. 00397 */ 00398 int tao_block_types; 00399 /** 00400 * The supported block types in sao mode. 00401 * They should be tested with the desired block type. 00402 * See also burn_block_types. 00403 */ 00404 int sao_block_types; 00405 /** 00406 * The supported block types in raw mode. 00407 * They should be tested with the desired block type. 00408 * See also burn_block_types. 00409 */ 00410 int raw_block_types; 00411 /** 00412 * The supported block types in packet mode. 00413 * They should be tested with the desired block type. 00414 * See also burn_block_types. 00415 */ 00416 int packet_block_types; 00417 00418 /** The value by which this drive can be indexed when using functions 00419 in the library. This is the value to pass to all libbburn functions 00420 that operate on a drive. */ 00421 struct burn_drive *drive; 00422 }; 00423 00424 00425 /** Operation progress report. All values are 0 based indices. 00426 * */ 00427 struct burn_progress { 00428 /** The total number of sessions */ 00429 int sessions; 00430 /** Current session.*/ 00431 int session; 00432 /** The total number of tracks */ 00433 int tracks; 00434 /** Current track. */ 00435 int track; 00436 /** The total number of indices */ 00437 int indices; 00438 /** Curent index. */ 00439 int index; 00440 /** The starting logical block address */ 00441 int start_sector; 00442 /** On write: The number of sectors. 00443 On blank: 0x10000 as upper limit for relative progress steps */ 00444 int sectors; 00445 /** On write: The current sector being processed. 00446 On blank: Relative progress steps 0 to 0x10000 */ 00447 int sector; 00448 00449 /* ts A61023 */ 00450 /** The capacity of the drive buffer */ 00451 unsigned buffer_capacity; 00452 /** The free space in the drive buffer (might be slightly outdated) */ 00453 unsigned buffer_available; 00454 00455 /* ts A61119 */ 00456 /** The number of bytes sent to the drive buffer */ 00457 off_t buffered_bytes; 00458 /** The minimum number of bytes stored in buffer during write. 00459 (Caution: Before surely one buffer size of bytes was processed, 00460 this value is 0xffffffff.) 00461 */ 00462 unsigned buffer_min_fill; 00463 }; 00464 00465 00466 /* ts A61226 */ 00467 /** Description of a speed capability as reported by the drive in conjunction 00468 with eventually loaded media. There can be more than one such object per 00469 drive. So they are chained via .next and .prev , where NULL marks the end 00470 of the chain. This list is set up by burn_drive_scan() and gets updated 00471 by burn_drive_grab(). 00472 A copy may be obtained by burn_drive_get_speedlist() and disposed by 00473 burn_drive_free_speedlist(). 00474 For technical background info see SCSI specs MMC and SPC: 00475 mode page 2Ah (from SPC 5Ah MODE SENSE) , mmc3r10g.pdf , 6.3.11 Table 364 00476 ACh GET PERFORMANCE, Type 03h , mmc5r03c.pdf , 6.8.5.3 Table 312 00477 */ 00478 struct burn_speed_descriptor { 00479 00480 /** Where this info comes from : 00481 0 = misc , 1 = mode page 2Ah , 2 = ACh GET PERFORMANCE */ 00482 int source; 00483 00484 /** The media type that was current at the time of report 00485 -2 = state unknown, -1 = no media was loaded , else see 00486 burn_disc_get_profile() */ 00487 int profile_loaded; 00488 char profile_name[80]; 00489 00490 /** The attributed capacity of appropriate media in logical block units 00491 i.e. 2352 raw bytes or 2048 data bytes. -1 = capacity unknown. */ 00492 int end_lba; 00493 00494 /** Speed is given in 1000 bytes/s , 0 = invalid. The numbers 00495 are supposed to be usable with burn_drive_set_speed() */ 00496 int write_speed; 00497 int read_speed; 00498 00499 /** Expert info from ACh GET PERFORMANCE and/or mode page 2Ah. 00500 Expect values other than 0 or 1 to get a meaning in future.*/ 00501 /* Rotational control: 0 = CLV/default , 1 = CAV */ 00502 int wrc; 00503 /* 1 = drive promises reported performance over full media */ 00504 int exact; 00505 /* 1 = suitable for mixture of read and write */ 00506 int mrw; 00507 00508 /** List chaining. Use .next until NULL to iterate over the list */ 00509 struct burn_speed_descriptor *prev; 00510 struct burn_speed_descriptor *next; 00511 }; 00512 00513 00514 /** Initialize the library. 00515 This must be called before using any other functions in the library. It 00516 may be called more than once with no effect. 00517 It is possible to 'restart' the library by shutting it down and 00518 re-initializing it. This is necessary if you follow the older and 00519 more general way of accessing a drive via burn_drive_scan() and 00520 burn_drive_grab(). See burn_drive_scan_and_grab() with its strong 00521 urges and its explanations. 00522 @return Nonzero if the library was able to initialize; zero if 00523 initialization failed. 00524 */ 00525 int burn_initialize(void); 00526 00527 /** Shutdown the library. 00528 This should be called before exiting your application. Make sure that all 00529 drives you have grabbed are released <i>before</i> calling this. 00530 */ 00531 void burn_finish(void); 00532 00533 00534 /* ts A61002 */ 00535 /** Abort any running drive operation and finally call burn_finish(). 00536 You MUST calm down the busy drive if an aborting event occurs during a 00537 burn run. For that you may call this function either from your own signal 00538 handling code or indirectly by activating the builtin signal handling: 00539 burn_set_signal_handling("my_app_name : ", NULL, 0); 00540 Else you may eventually call burn_drive_cancel() on the active drive and 00541 wait for it to assume state BURN_DRIVE_IDLE. 00542 @param patience Maximum number of seconds to wait for drives to finish 00543 @param pacifier_func If not NULL: a function to produce appeasing messages. 00544 See burn_abort_pacifier() for an example. 00545 @param handle Opaque handle to be used with pacifier_func 00546 @return 1 ok, all went well 00547 0 had to leave a drive in unclean state 00548 <0 severe error, do no use libburn again 00549 */ 00550 int burn_abort(int patience, 00551 int (*pacifier_func)(void *handle, int patience, int elapsed), 00552 void *handle); 00553 00554 /** A pacifier function suitable for burn_abort. 00555 @param handle If not NULL, a pointer to a text suitable for printf("%s") 00556 @param patience Maximum number of seconds to wait 00557 @param elapsed Elapsed number of seconds 00558 */ 00559 int burn_abort_pacifier(void *handle, int patience, int elapsed); 00560 00561 00562 /** ts A61006 : This is for development only. Not suitable for applications. 00563 Set the verbosity level of the library. The default value is 0, which means 00564 that nothing is output on stderr. The more you increase this, the more 00565 debug output should be displayed on stderr for you. 00566 @param level The verbosity level desired. 0 for nothing, higher positive 00567 values for more information output. 00568 */ 00569 void burn_set_verbosity(int level); 00570 00571 /* ts A60813 */ 00572 /** Set parameters for behavior on opening device files. To be called early 00573 after burn_initialize() and before any bus scan. But not mandatory at all. 00574 Parameter value 1 enables a feature, 0 disables. 00575 Default is (1,0,0). Have a good reason before you change it. 00576 @param exclusive Linux only: 00577 0 = no attempt to make drive access exclusive. 00578 1 = Try to open only devices which are not marked as busy 00579 and try to mark them busy if opened sucessfully. (O_EXCL) 00580 There are kernels which simply don't care about O_EXCL. 00581 Some have it off, some have it on, some are switchable. 00582 2 = in case of a SCSI device, also try to open exclusively 00583 the matching /dev/sr, /dev/scd and /dev/st . 00584 One may select a device SCSI file family by adding 00585 0 = default family 00586 4 = /dev/sr%d 00587 8 = /dev/scd%d 00588 16 = /dev/sg%d 00589 Do not use other values ! 00590 Add 32 to demand an exclusive lock by fcntl(,F_SETLK,) 00591 after open() has succeeded. 00592 @param blocking Try to wait for drives which do not open immediately but 00593 also do not return an error as well. (O_NONBLOCK) 00594 This might stall indefinitely with /dev/hdX hard disks. 00595 @param abort_on_busy Unconditionally abort process when a non blocking 00596 exclusive opening attempt indicates a busy drive. 00597 Use this only after thorough tests with your app. 00598 */ 00599 void burn_preset_device_open(int exclusive, int blocking, int abort_on_busy); 00600 00601 00602 /* ts A70223 */ 00603 /** Allows the use of media types which are implemented in libburn but not yet 00604 tested. The list of those untested profiles is subject to change. 00605 Currently it contains: 0x15 "DVD-R/DL Sequential". 00606 If you really test such media, then please report the outcome on 00607 libburn-hackers@pykix.org 00608 If ever then this call should be done soon after burn_initialize() before 00609 any drive scanning. 00610 @param yes 1=allow all implemented profiles, 0=only tested media (default) 00611 */ 00612 void burn_allow_untested_profiles(int yes); 00613 00614 00615 /* ts A60823 */ 00616 /** Aquire a drive with known persistent address.This is the sysadmin friendly 00617 way to open one drive and to leave all others untouched. It bundles 00618 the following API calls to form a non-obtrusive way to use libburn: 00619 burn_drive_add_whitelist() , burn_drive_scan() , burn_drive_grab() 00620 You are *strongly urged* to use this call whenever you know the drive 00621 address in advance. 00622 If not, then you have to use directly above calls. In that case, you are 00623 *strongly urged* to drop any unintended drive which will be exclusively 00624 occupied and not closed by burn_drive_scan(). 00625 This can be done by shutting down the library including a call to 00626 burn_finish(). You may later start a new libburn session and should then 00627 use the function described here with an address obtained after 00628 burn_drive_scan() via burn_drive_get_adr(&(drive_infos[driveno]), adr) . 00629 Another way is to drop the unwanted drives by burn_drive_info_forget(). 00630 @param drive_infos On success returns a one element array with the drive 00631 (cdrom/burner). Thus use with driveno 0 only. On failure 00632 the array has no valid elements at all. 00633 The returned array should be freed via burn_drive_info_free() 00634 when it is no longer needed, and before calling a scan 00635 function again. 00636 This is a result from call burn_drive_scan(). See there. 00637 Use with driveno 0 only. 00638 @param adr The persistent address of the desired drive. Either obtained 00639 by burn_drive_get_adr() or guessed skillfully by application 00640 resp. its user. 00641 @param load Nonzero to make the drive attempt to load a disc (close its 00642 tray door, etc). 00643 @return 1 = success , 0 = drive not found , -1 = other error 00644 */ 00645 int burn_drive_scan_and_grab(struct burn_drive_info *drive_infos[], 00646 char* adr, int load); 00647 00648 00649 /* ts A51221 */ 00650 /** Maximum number of particularly permissible drive addresses */ 00651 #define BURN_DRIVE_WHITELIST_LEN 255 00652 /** Add a device to the list of permissible drives. As soon as some entry is in 00653 the whitelist all non-listed drives are banned from scanning. 00654 @return 1 success, <=0 failure 00655 */ 00656 int burn_drive_add_whitelist(char *device_address); 00657 00658 /** Remove all drives from whitelist. This enables all possible drives. */ 00659 void burn_drive_clear_whitelist(void); 00660 00661 00662 /** Scan for drives. This function MUST be called until it returns nonzero. 00663 No drives may be in use when this is called. 00664 All drive pointers are invalidated by using this function. Do NOT store 00665 drive pointers across calls to this function or death AND pain will ensue. 00666 After this call all drives depicted by the returned array are subject 00667 to eventual (O_EXCL) locking. See burn_preset_device_open(). This state 00668 ends either with burn_drive_info_forget() or with burn_drive_release(). 00669 It is unfriendly to other processes on the system to hold drives locked 00670 which one does not definitely plan to use soon. 00671 @param drive_infos Returns an array of drive info items (cdroms/burners). 00672 The returned array must be freed by burn_drive_info_free() 00673 before burn_finish(), and also before calling this function 00674 burn_drive_scan() again. 00675 @param n_drives Returns the number of drive items in drive_infos. 00676 @return 0 while scanning is not complete 00677 >0 when it is finished sucessfully, 00678 <0 when finished but failed. 00679 */ 00680 int burn_drive_scan(struct burn_drive_info *drive_infos[], 00681 unsigned int *n_drives); 00682 00683 /* ts A60904 : ticket 62, contribution by elmom */ 00684 /** Release memory about a single drive and any exclusive lock on it. 00685 Become unable to inquire or grab it. Expect FATAL consequences if you try. 00686 @param drive_info pointer to a single element out of the array 00687 obtained from burn_drive_scan() : &(drive_infos[driveno]) 00688 @param force controls degree of permissible drive usage at the moment this 00689 function is called, and the amount of automatically provided 00690 drive shutdown : 00691 0= drive must be ungrabbed and BURN_DRIVE_IDLE 00692 1= try to release drive resp. accept BURN_DRIVE_GRABBING 00693 Use these two only. Further values are to be defined. 00694 @return 1 on success, 2 if drive was already forgotten, 00695 0 if not permissible, <0 on other failures, 00696 */ 00697 int burn_drive_info_forget(struct burn_drive_info *drive_info, int force); 00698 00699 00700 /** When no longer needed, free a whole burn_drive_info array which was 00701 returned by burn_drive_scan(). 00702 For freeing single drive array elements use burn_drive_info_forget(). 00703 */ 00704 void burn_drive_info_free(struct burn_drive_info drive_infos[]); 00705 00706 00707 /* ts A60823 */ 00708 /** Maximum length+1 to expect with a persistent drive address string */ 00709 #define BURN_DRIVE_ADR_LEN 1024 00710 00711 /** Inquire the persistent address of the given drive. 00712 @param drive_info The drive to inquire. Usually some &(drive_infos[driveno]) 00713 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00714 characters size. The persistent address gets copied to it. 00715 @return >0 success , <=0 error (due to libburn internal problem) 00716 */ 00717 int burn_drive_get_adr(struct burn_drive_info *drive_info, char adr[]); 00718 00719 /* ts A60922 ticket 33 */ 00720 /** Evaluate wether the given address would be a possible persistent drive 00721 address of libburn. 00722 @return 1 means yes, 0 means no 00723 */ 00724 int burn_drive_is_enumerable_adr(char *adr); 00725 00726 /* ts A60922 ticket 33 */ 00727 /** Try to convert a given existing filesystem address into a persistent drive 00728 address. This succeeds with symbolic links or if a hint about the drive's 00729 system address can be read from the filesystem object and a matching drive 00730 is found. 00731 @param path The address of an existing file system object 00732 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00733 characters size. The persistent address gets copied to it. 00734 @return 1 = success , 0 = failure , -1 = severe error 00735 */ 00736 int burn_drive_convert_fs_adr(char *path, char adr[]); 00737 00738 /* ts A60923 */ 00739 /** Try to convert a given SCSI address of bus,host,channel,target,lun into 00740 a persistent drive address. If a SCSI address component parameter is < 0 00741 then it is not decisive and the first enumerated address which matches 00742 the >= 0 parameters is taken as result. 00743 Note: bus and (host,channel) are supposed to be redundant. 00744 @param bus_no "Bus Number" (something like a virtual controller) 00745 @param host_no "Host Number" (something like half a virtual controller) 00746 @param channel_no "Channel Number" (other half of "Host Number") 00747 @param target_no "Target Number" or "SCSI Id" (a device) 00748 @param lun_no "Logical Unit Number" (a sub device) 00749 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00750 characters size. The persistent address gets copied to it. 00751 @return 1 = success , 0 = failure , -1 = severe error 00752 */ 00753 int burn_drive_convert_scsi_adr(int bus_no, int host_no, int channel_no, 00754 int target_no, int lun_no, char adr[]); 00755 00756 /* ts A60923 - A61005 */ 00757 /** Try to obtain bus,host,channel,target,lun from path. If there is an SCSI 00758 address at all, then this call should succeed with a persistent 00759 drive address obtained via burn_drive_get_adr(). It is also supposed to 00760 succeed with any device file of a (possibly emulated) SCSI device. 00761 @return 1 = success , 0 = failure , -1 = severe error 00762 */ 00763 int burn_drive_obtain_scsi_adr(char *path, int *bus_no, int *host_no, 00764 int *channel_no, int *target_no, int *lun_no); 00765 00766 /** Grab a drive. This must be done before the drive can be used (for reading, 00767 writing, etc). 00768 @param drive The drive to grab. This is found in a returned 00769 burn_drive_info struct. 00770 @param load Nonzero to make the drive attempt to load a disc (close its 00771 tray door, etc). 00772 @return 1 if it was possible to grab the drive, else 0 00773 */ 00774 int burn_drive_grab(struct burn_drive *drive, int load); 00775 00776 00777 /** Release a drive. This should not be done until the drive is no longer 00778 busy (see burn_drive_get_status). 00779 Linux: The drive is unlocked afterwards. (O_EXCL , F_SETLK). 00780 @param drive The drive to release. 00781 @param eject Nonzero to make the drive eject the disc in it. 00782 */ 00783 void burn_drive_release(struct burn_drive *drive, int eject); 00784 00785 00786 /** Returns what kind of disc a drive is holding. This function may need to be 00787 called more than once to get a proper status from it. See burn_disc_status 00788 for details. 00789 @param drive The drive to query for a disc. 00790 @return The status of the drive, or what kind of disc is in it. 00791 Note: BURN_DISC_UNGRABBED indicates wrong API usage 00792 */ 00793 enum burn_disc_status burn_disc_get_status(struct burn_drive *drive); 00794 00795 00796 /* ts A61020 */ 00797 /** WARNING: This revives an old bug-like behavior that might be dangerous. 00798 Sets the drive status to BURN_DISC_BLANK if it is BURN_DISC_UNREADY 00799 or BURN_DISC_UNSUITABLE. Thus marking media as writable which actually 00800 failed to declare themselves either blank or (partially) filled. 00801 @return 1 drive status has been set , 0 = unsuitable drive status 00802 */ 00803 int burn_disc_pretend_blank(struct burn_drive *drive); 00804 00805 00806 /* ts A61106 */ 00807 /** WARNING: This overrides the safety measures against unsuitable media. 00808 Sets the drive status to BURN_DISC_FULL if it is BURN_DISC_UNREADY 00809 or BURN_DISC_UNSUITABLE. Thus marking media as blankable which actually 00810 failed to declare themselves either blank or (partially) filled. 00811 */ 00812 int burn_disc_pretend_full(struct burn_drive *drive); 00813 00814 00815 /* ts A61021 */ 00816 /** Reads ATIP information from inserted media. To be obtained via 00817 burn_drive_get_write_speed(), burn_drive_get_min_write_speed(), 00818 burn_drive_get_start_end_lba(). The drive must be grabbed for this call. 00819 @param drive The drive to query. 00820 @return 1=sucess, 0=no valid ATIP info read, -1 severe error 00821 */ 00822 int burn_disc_read_atip(struct burn_drive *drive); 00823 00824 00825 /* ts A61020 */ 00826 /** Returns start and end lba of the media which is currently inserted 00827 in the given drive. The drive has to be grabbed to have hope for reply. 00828 Shortcomming (not a feature): unless burn_disc_read_atip() was called 00829 only blank media will return valid info. 00830 @param drive The drive to query. 00831 @param start_lba Returns the start lba value 00832 @param end_lba Returns the end lba value 00833 @param flag Bitfield for control purposes (unused yet, submit 0) 00834 @return 1 if lba values are valid , 0 if invalid 00835 */ 00836 int burn_drive_get_start_end_lba(struct burn_drive *drive, 00837 int *start_lba, int *end_lba, int flag); 00838 00839 /* ts A61110 */ 00840 /** Read start lba and Next Writeable Address of a track from media. 00841 Usually a track lba is obtained from the result of burn_track_get_entry(). 00842 This call retrieves an updated lba, eventual nwa, and can address the 00843 invisible track to come. 00844 The drive must be grabbed for this call. One may not issue this call 00845 during ongoing burn_disc_write() or burn_disc_erase(). 00846 @param d The drive to query. 00847 @param o If not NULL: write parameters to be set on drive before query 00848 @param trackno 0=next track to come, >0 number of existing track 00849 @param lba return value: start lba 00850 @param nwa return value: Next Writeable Address 00851 @return 1=nwa is valid , 0=nwa is not valid , -1=error 00852 */ 00853 int burn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o, 00854 int trackno, int *lba, int *nwa); 00855 00856 /* ts A70131 */ 00857 /** Read start lba of the first track in the last complete session. 00858 This is the first parameter of mkisofs option -C. The second parameter 00859 is nwa as obtained by burn_disc_track_lba_nwa() with trackno 0. 00860 @param d The drive to query. 00861 @param start_lba returns the start address of that track 00862 @return <= 0 : failure, 1 = ok 00863 */ 00864 int burn_disc_get_msc1(struct burn_drive *d, int *start_lba); 00865 00866 00867 /* ts A70213 */ 00868 /** Return the best possible estimation of the currently available capacity of 00869 the media. This might depend on particular write option settings. For 00870 inquiring the space with such a set of options, the drive has to be 00871 grabbed and BURN_DRIVE_IDLE. If not, then one will only get a canned value 00872 from the most recent automatic inquiry (e.g. during last drive grabbing). 00873 An eventual start address from burn_write_opts_set_start_byte() will be 00874 subtracted from the obtained capacity estimation. Negative results get 00875 defaulted to 0. 00876 @param d The drive to query. 00877 @param o If not NULL: write parameters to be set on drive before query 00878 @return number of most probably available free bytes 00879 */ 00880 off_t burn_disc_available_space(struct burn_drive *d, 00881 struct burn_write_opts *o); 00882 00883 00884 /* ts A61202 */ 00885 /** Tells the MMC Profile identifier of the loaded media. The drive must be 00886 grabbed in order to get a non-zero result. 00887 libburn currently writes only to profiles 0x09 "CD-R", 0x0a "CD-RW", 00888 0x11 "DVD-R", 0x12 "DVD-RAM", 0x13 "DVD-RW restricted overwrite", 00889 0x14 "DVD-RW Sequential Recording" or 0x1a "DVD+RW". 00890 If enabled by burn_allow_untested_profiles() it also writes to profile 00891 0x15 "DVD-R/DL Sequential Recording". 00892 @param d The drive where the media is inserted. 00893 @param pno Profile Number as of mmc5r03c.pdf, table 89 00894 @param name Profile Name (e.g "CD-RW", unknown profiles have empty name) 00895 @return 1 profile is valid, 0 no profile info available 00896 */ 00897 int burn_disc_get_profile(struct burn_drive *d, int *pno, char name[80]); 00898 00899 /** Tells whether a disc can be erased or not 00900 @return Non-zero means erasable 00901 */ 00902 int burn_disc_erasable(struct burn_drive *d); 00903 00904 /** Returns the progress and status of a drive. 00905 @param drive The drive to query busy state for. 00906 @param p Returns the progress of the operation, NULL if you don't care 00907 @return the current status of the drive. See also burn_drive_status. 00908 */ 00909 enum burn_drive_status burn_drive_get_status(struct burn_drive *drive, 00910 struct burn_progress *p); 00911 00912 /** Creates a write_opts struct for burning to the specified drive 00913 must be freed with burn_write_opts_free 00914 @param drive The drive to write with 00915 @return The write_opts, NULL on error 00916 */ 00917 struct burn_write_opts *burn_write_opts_new(struct burn_drive *drive); 00918 00919 /** Frees a write_opts struct created with burn_write_opts_new 00920 @param opts write_opts to free 00921 */ 00922 void burn_write_opts_free(struct burn_write_opts *opts); 00923 00924 /** Creates a read_opts struct for reading from the specified drive 00925 must be freed with burn_read_opts_free 00926 @param drive The drive to read from 00927 @return The read_opts 00928 */ 00929 struct burn_read_opts *burn_read_opts_new(struct burn_drive *drive); 00930 00931 /** Frees a read_opts struct created with burn_read_opts_new 00932 @param opts write_opts to free 00933 */ 00934 void burn_read_opts_free(struct burn_read_opts *opts); 00935 00936 /** Erase a disc in the drive. The drive must be grabbed successfully BEFORE 00937 calling this functions. Always ensure that the drive reports a status of 00938 BURN_DISC_FULL before calling this function. An erase operation is not 00939 cancellable, as control of the operation is passed wholly to the drive and 00940 there is no way to interrupt it safely. 00941 @param drive The drive with which to erase a disc. 00942 @param fast Nonzero to do a fast erase, where only the disc's headers are 00943 erased; zero to erase the entire disc. 00944 With DVD-RW, fast blanking yields media capable only of DAO. 00945 */ 00946 void burn_disc_erase(struct burn_drive *drive, int fast); 00947 00948 00949 /* ts A70101 - A70112 */ 00950 /** Format media for use with libburn. This currently applies to DVD-RW 00951 in state "Sequential Recording" (profile 0014h) which get formatted to 00952 state "Restricted Overwrite" (profile 0013h). DVD+RW can be "de-iced" 00953 by setting bit2 of flag. Other media cannot be formatted yet. 00954 @param drive The drive with the disc to format. 00955 @param size The size in bytes to be used with the format command. It should 00956 be divisible by 32*1024. The effect of this parameter may 00957 depend on the media profile. 00958 @param flag Bitfield for control purposes: 00959 bit0= after formatting, write the given number of zero-bytes 00960 to the media and eventually perform preliminary closing. 00961 bit1= insist in size 0 even if there is a better default known 00962 bit2= format to maximum available size 00963 bit3= -reserved- 00964 bit4= enforce re-format of (partly) formatted media 00965 bit7= MMC expert application mode (else libburn tries to 00966 choose a suitable format type): 00967 bit8 to bit15 contain the index of the format to use. See 00968 burn_disc_get_formats(), burn_disc_get_format_descr(). 00969 Acceptable types are: 0x00, 0x10, 0x11, 0x13, 0x15, 0x26. 00970 If bit7 is set, bit4 is set automatically. 00971 */ 00972 void burn_disc_format(struct burn_drive *drive, off_t size, int flag); 00973 00974 00975 /* ts A70112 */ 00976 /** Possible formatting status values */ 00977 #define BURN_FORMAT_IS_UNFORMATTED 1 00978 #define BURN_FORMAT_IS_FORMATTED 2 00979 #define BURN_FORMAT_IS_UNKNOWN 3 00980 00981 /** Inquire the formatting status, the associated sizes and the number of 00982 available formats. The info is media specific and stems from MMC command 00983 23h READ FORMAT CAPACITY. See mmc5r03c.pdf 6.24 for background details. 00984 Media type can be determined via burn_disc_get_profile(). 00985 @param drive The drive with the disc to format. 00986 @param status The current formatting status of the inserted media. 00987 See BURN_FORMAT_IS_* macros. Note: "unknown" is the 00988 legal status for quick formatted, yet unwritten DVD-RW. 00989 @param size The size in bytes associated with status. 00990 unformatted: the maximum achievable size of the media 00991 formatted: the currently formatted capacity 00992 unknown: maximum capacity of drive or of media 00993 @param bl_sas Additional info "Block Length/Spare Area Size". 00994 Expected to be constantly 2048 for non-BD media. 00995 @param num_formats The number of available formats. To be used with 00996 burn_disc_get_format_descr() to obtain such a format 00997 and eventually with burn_disc_format() to select one. 00998 @return 1 reply is valid , <=0 failure 00999 */ 01000 int burn_disc_get_formats(struct burn_drive *drive, int *status, off_t *size, 01001 unsigned *bl_sas, int *num_formats); 01002 01003 /** Inquire parameters of an available media format. 01004 @param drive The drive with the disc to format. 01005 @param index The index of the format item. Beginning with 0 up to reply 01006 parameter from burn_disc_get_formats() : num_formats - 1 01007 @param type The format type. See mmc5r03c.pdf, 6.5, 04h FORMAT UNIT. 01008 0x00=full, 0x10=CD-RW/DVD-RW full, 0x11=CD-RW/DVD-RW grow, 01009 0x15=DVD-RW quick, 0x13=DVD-RW quick grow, 01010 0x26=DVD+RW background 01011 @param size The maximum size in bytes achievable with this format. 01012 @param tdp Type Dependent Parameter. See mmc5r03c.pdf. 01013 @return 1 reply is valid , <=0 failure 01014 */ 01015 int burn_disc_get_format_descr(struct burn_drive *drive, int index, 01016 int *type, off_t *size, unsigned *tdp); 01017 01018 01019 01020 /* ts A61109 : this was and is defunct */ 01021 /** Read a disc from the drive and write it to an fd pair. The drive must be 01022 grabbed successfully BEFORE calling this function. Always ensure that the 01023 drive reports a status of BURN_DISC_FULL before calling this function. 01024 @param drive The drive from which to read a disc. 01025 @param o The options for the read operation. 01026 */ 01027 void burn_disc_read(struct burn_drive *drive, const struct burn_read_opts *o); 01028 01029 01030 01031 /* ts A70222 */ 01032 /** The length of a rejection reasons string for burn_precheck_write() and 01033 burn_write_opts_auto_write_type() . 01034 */ 01035 #define BURN_REASONS_LEN 4096 01036 01037 01038 /* ts A70219 */ 01039 /** Examines a completed setup for burn_disc_write() wether it is permissible 01040 with drive and media. This function is called by burn_disc_write() but 01041 an application might be interested in this check in advance. 01042 @param o The options for the writing operation. 01043 @param disc The descrition of the disc to be created 01044 @param reasons Eventually returns a list of rejection reason statements 01045 @param silent 1= do not issue error messages , 0= report problems 01046 @return 1 ok, -1= no recordable media detected, 0= other failure 01047 */ 01048 int burn_precheck_write(struct burn_write_opts *o, struct burn_disc *disc, 01049 char reasons[BURN_REASONS_LEN], int silent); 01050 01051 /* <<< enabling switch for internal usage and trust in this function */ 01052 #define Libburn_precheck_write_ruleS 1 01053 01054 01055 /** Write a disc in the drive. The drive must be grabbed successfully before 01056 calling this function. Always ensure that the drive reports a status of 01057 BURN_DISC_BLANK ot BURN_DISC_APPENDABLE before calling this function. 01058 Note: write_type BURN_WRITE_SAO is currently not capable of writing a mix 01059 of data and audio tracks. You must use BURN_WRITE_TAO for such sessions. 01060 To be set by burn_write_opts_set_write_type(). 01061 @param o The options for the writing operation. 01062 @param disc The struct burn_disc * that described the disc to be created 01063 */ 01064 void burn_disc_write(struct burn_write_opts *o, struct burn_disc *disc); 01065 01066 /** Cancel an operation on a drive. 01067 This will only work when the drive's busy state is BURN_DRIVE_READING or 01068 BURN_DRIVE_WRITING. 01069 @param drive The drive on which to cancel the current operation. 01070 */ 01071 void burn_drive_cancel(struct burn_drive *drive); 01072 01073 01074 /* ts A61223 */ 01075 /** Inquire wether the most recent write run was successful. Reasons for 01076 non-success may be: rejection of burn parameters, abort during fatal errors 01077 during write, a call to burn_drive_cancel() by the application thread. 01078 @param d The drive to inquire. 01079 @return 1=burn seems to have went well, 0=burn failed 01080 */ 01081 int burn_drive_wrote_well(struct burn_drive *d); 01082 01083 01084 /** Convert a minute-second-frame (MSF) value to sector count 01085 @param m Minute component 01086 @param s Second component 01087 @param f Frame component 01088 @return The sector count 01089 */ 01090 int burn_msf_to_sectors(int m, int s, int f); 01091 01092 /** Convert a sector count to minute-second-frame (MSF) 01093 @param sectors The sector count 01094 @param m Returns the minute component 01095 @param s Returns the second component 01096 @param f Returns the frame component 01097 */ 01098 void burn_sectors_to_msf(int sectors, int *m, int *s, int *f); 01099 01100 /** Convert a minute-second-frame (MSF) value to an lba 01101 @param m Minute component 01102 @param s Second component 01103 @param f Frame component 01104 @return The lba 01105 */ 01106 int burn_msf_to_lba(int m, int s, int f); 01107 01108 /** Convert an lba to minute-second-frame (MSF) 01109 @param lba The lba 01110 @param m Returns the minute component 01111 @param s Returns the second component 01112 @param f Returns the frame component 01113 */ 01114 void burn_lba_to_msf(int lba, int *m, int *s, int *f); 01115 01116 /** Create a new disc */ 01117 struct burn_disc *burn_disc_create(void); 01118 01119 /** Delete disc and decrease the reference count on all its sessions 01120 @param d The disc to be freed 01121 */ 01122 void burn_disc_free(struct burn_disc *d); 01123 01124 /** Create a new session */ 01125 struct burn_session *burn_session_create(void); 01126 01127 /** Free a session (and decrease reference count on all tracks inside) 01128 @param s Session to be freed 01129 */ 01130 void burn_session_free(struct burn_session *s); 01131 01132 /** Add a session to a disc at a specific position, increasing the 01133 sessions's reference count. 01134 @param d Disc to add the session to 01135 @param s Session to add to the disc 01136 @param pos position to add at (BURN_POS_END is "at the end") 01137 @return 0 for failure, 1 for success 01138 */ 01139 int burn_disc_add_session(struct burn_disc *d, struct burn_session *s, 01140 unsigned int pos); 01141 01142 /** Remove a session from a disc 01143 @param d Disc to remove session from 01144 @param s Session pointer to find and remove 01145 */ 01146 int burn_disc_remove_session(struct burn_disc *d, struct burn_session *s); 01147 01148 01149 /** Create a track (for TAO recording, or to put in a session) */ 01150 struct burn_track *burn_track_create(void); 01151 01152 /** Free a track 01153 @param t Track to free 01154 */ 01155 void burn_track_free(struct burn_track *t); 01156 01157 /** Add a track to a session at specified position 01158 @param s Session to add to 01159 @param t Track to insert in session 01160 @param pos position to add at (BURN_POS_END is "at the end") 01161 @return 0 for failure, 1 for success 01162 */ 01163 int burn_session_add_track(struct burn_session *s, struct burn_track *t, 01164 unsigned int pos); 01165 01166 /** Remove a track from a session 01167 @param s Session to remove track from 01168 @param t Track pointer to find and remove 01169 @return 0 for failure, 1 for success 01170 */ 01171 int burn_session_remove_track(struct burn_session *s, struct burn_track *t); 01172 01173 01174 /** Define the data in a track 01175 @param t the track to define 01176 @param offset The lib will write this many 0s before start of data 01177 @param tail The number of extra 0s to write after data 01178 @param pad 1 means the lib should pad the last sector with 0s if the 01179 track isn't exactly sector sized. (otherwise the lib will 01180 begin reading from the next track) 01181 @param mode data format (bitfield) 01182 */ 01183 void burn_track_define_data(struct burn_track *t, int offset, int tail, 01184 int pad, int mode); 01185 01186 01187 /* ts A61024 */ 01188 /** Define wether a track shall swap bytes of its input stream. 01189 @param t The track to change 01190 @param swap_source_bytes 0=do not swap, 1=swap byte pairs 01191 @return 1=success , 0=unacceptable value 01192 */ 01193 int burn_track_set_byte_swap(struct burn_track *t, int swap_source_bytes); 01194 01195 01196 /** Set the ISRC details for a track 01197 @param t The track to change 01198 @param country the 2 char country code. Each character must be 01199 only numbers or letters. 01200 @param owner 3 char owner code. Each character must be only numbers 01201 or letters. 01202 @param year 2 digit year. A number in 0-99 (Yep, not Y2K friendly). 01203 @param serial 5 digit serial number. A number in 0-99999. 01204 */ 01205 void burn_track_set_isrc(struct burn_track *t, char *country, char *owner, 01206 unsigned char year, unsigned int serial); 01207 01208 /** Disable ISRC parameters for a track 01209 @param t The track to change 01210 */ 01211 void burn_track_clear_isrc(struct burn_track *t); 01212 01213 /** Hide the first track in the "pre gap" of the disc 01214 @param s session to change 01215 @param onoff 1 to enable hiding, 0 to disable 01216 */ 01217 void burn_session_hide_first_track(struct burn_session *s, int onoff); 01218 01219 /** Get the drive's disc struct - free when done 01220 @param d drive to query 01221 @return the disc struct or NULL on failure 01222 */ 01223 struct burn_disc *burn_drive_get_disc(struct burn_drive *d); 01224 01225 /** Set the track's data source 01226 @param t The track to set the data source for 01227 @param s The data source to use for the contents of the track 01228 @return An error code stating if the source is ready for use for 01229 writing the track, or if an error occured 01230 01231 */ 01232 enum burn_source_status burn_track_set_source(struct burn_track *t, 01233 struct burn_source *s); 01234 01235 01236 /* ts A70218 */ 01237 /** Set a default track size to be used only if the track turns out to be of 01238 unpredictable length and if the effective write type demands a fixed size. 01239 This can be useful to enable write types CD SAO or DVD DAO together with 01240 a track source like stdin. If the track source delivers fewer bytes than 01241 announced then the track will be padded up with zeros. 01242 @param t The track to change 01243 @param size The size to set 01244 @return 0=failure 1=sucess 01245 */ 01246 int burn_track_set_default_size(struct burn_track *t, off_t size); 01247 01248 /** Free a burn_source (decrease its refcount and maybe free it) 01249 @param s Source to free 01250 */ 01251 void burn_source_free(struct burn_source *s); 01252 01253 /** Creates a data source for an image file (and maybe subcode file) */ 01254 struct burn_source *burn_file_source_new(const char *path, 01255 const char *subpath); 01256 01257 /** Creates a data source for an image file (a track) from an open 01258 readable filedescriptor, an eventually open readable subcodes file 01259 descriptor and eventually a fixed size in bytes. 01260 @param datafd The source of data. 01261 @param subfd The eventual source for subcodes. Not used if -1. 01262 @param size The eventual fixed size of eventually both fds. 01263 If this value is 0, the size will be determined from datafd. 01264 */ 01265 struct burn_source *burn_fd_source_new(int datafd, int subfd, off_t size); 01266 01267 01268 /* ts A70328 */ 01269 /** Sets a fixed track size after the data source object has already been 01270 created. 01271 @param t The track to poperate on 01272 @param size the number of bytes to use as track size 01273 @return <=0 indicates failure , >0 success 01274 */ 01275 int burn_track_set_size(struct burn_track *t, off_t size); 01276 01277 01278 /** Tells how long a track will be on disc 01279 >>> NOTE: Not reliable with tracks of undefined length 01280 */ 01281 int burn_track_get_sectors(struct burn_track *); 01282 01283 01284 /* ts A61101 */ 01285 /** Tells how many source bytes have been read and how many data bytes have 01286 been written by the track during burn */ 01287 int burn_track_get_counters(struct burn_track *t, 01288 off_t *read_bytes, off_t *written_bytes); 01289 01290 01291 /** Sets drive read and write speed 01292 Note: "k" is 1000, not 1024. 1xCD = 176.4 k/s, 1xDVD = 1385 k/s. 01293 Fractional speeds should be rounded up. Like 4xCD = 706. 01294 @param d The drive to set speed for 01295 @param read Read speed in k/s (0 is max, -1 is min). 01296 @param write Write speed in k/s (0 is max, -1 is min). 01297 */ 01298 void burn_drive_set_speed(struct burn_drive *d, int read, int write); 01299 01300 01301 /* ts A70711 */ 01302 /** Controls the behavior with writing when the drive buffer is suspected to 01303 be full. To check and wait for enough free buffer space before writing 01304 will move the task of waiting from the operating system's device driver 01305 to libburn. While writing is going on and waiting is enabled, any write 01306 operation will be checked wether it will fill the drive buffer up to 01307 more than max_percent. If so, then waiting will happen until the buffer 01308 fill is predicted with at most min_percent. 01309 Thus: if min_percent < max_percent then transfer rate will oscillate. 01310 This may allow the driver to operate on other devices, e.g. a disk from 01311 which to read the input for writing. On the other hand, this checking might 01312 reduce maximum throughput to the drive or even get misled by faulty buffer 01313 fill replies from the drive. 01314 If a setting parameter is < 0, then this setting will stay unchanged 01315 by the call. 01316 Known burner or media specific pitfalls: 01317 To have max_percent larger than the burner's best reported buffer fill has 01318 the same effect as min_percent==max_percent. Some burners do not report 01319 their full buffer with all media types. Some are not suitable because 01320 they report their buffer fill with delay. 01321 @param d The drive to control 01322 @param enable 0= disable , 1= enable waiting , (-1 = do not change setting) 01323 @param min_usec Shortest possible sleeping period (given in micro seconds) 01324 @param max_usec Longest possible sleeping period (given in micro seconds) 01325 @param timeout_sec If a single write has to wait longer than this number 01326 of seconds, then waiting gets disabled and mindless 01327 writing starts. A value of 0 disables this timeout. 01328 @param min_percent Minimum of desired buffer oscillation: 25 to 100 01329 @param max_percent Maximum of desired buffer oscillation: 25 to 100 01330 @return 1=success , 0=failure 01331 */ 01332 int burn_drive_set_buffer_waiting(struct burn_drive *d, int enable, 01333 int min_usec, int max_usec, int timeout_sec, 01334 int min_percent, int max_percent); 01335 01336 01337 /* these are for my debugging, they will disappear */ 01338 void burn_structure_print_disc(struct burn_disc *d); 01339 void burn_structure_print_session(struct burn_session *s); 01340 void burn_structure_print_track(struct burn_track *t); 01341 01342 /** Sets the write type for the write_opts struct. 01343 Note: write_type BURN_WRITE_SAO is currently not capable of writing a mix 01344 of data and audio tracks. You must use BURN_WRITE_TAO for such sessions. 01345 @param opts The write opts to change 01346 @param write_type The write type to use 01347 @param block_type The block type to use 01348 @return Returns 1 on success and 0 on failure. 01349 */ 01350 int burn_write_opts_set_write_type(struct burn_write_opts *opts, 01351 enum burn_write_types write_type, 01352 int block_type); 01353 01354 01355 /* ts A70207 */ 01356 /** As an alternative to burn_write_opts_set_write_type() this function tries 01357 to find a suitable write type and block type for a given write job 01358 described by opts and disc. To be used after all other setups have been 01359 made, i.e. immediately before burn_disc_write(). 01360 @param opts The nearly complete write opts to change 01361 @param disc The already composed session and track model 01362 @param reasons This text string collects reasons for decision resp. failure 01363 @param flag Bitfield for control purposes: 01364 bit0= do not choose type but check the one that is already set 01365 bit1= do not issue error messages via burn_msgs queue 01366 (is automatically set with bit0) 01367 @return Chosen write type. BURN_WRITE_NONE on failure. 01368 */ 01369 enum burn_write_types burn_write_opts_auto_write_type( 01370 struct burn_write_opts *opts, struct burn_disc *disc, 01371 char reasons[BURN_REASONS_LEN], int flag); 01372 01373 01374 /** Supplies toc entries for writing - not normally required for cd mastering 01375 @param opts The write opts to change 01376 @param count The number of entries 01377 @param toc_entries 01378 */ 01379 void burn_write_opts_set_toc_entries(struct burn_write_opts *opts, 01380 int count, 01381 struct burn_toc_entry *toc_entries); 01382 01383 /** Sets the session format for a disc 01384 @param opts The write opts to change 01385 @param format The session format to set 01386 */ 01387 void burn_write_opts_set_format(struct burn_write_opts *opts, int format); 01388 01389 /** Sets the simulate value for the write_opts struct 01390 @param opts The write opts to change 01391 @param sim If non-zero, the drive will perform a simulation instead of a burn 01392 @return Returns 1 on success and 0 on failure. 01393 */ 01394 int burn_write_opts_set_simulate(struct burn_write_opts *opts, int sim); 01395 01396 /** Controls buffer underrun prevention 01397 @param opts The write opts to change 01398 @param underrun_proof if non-zero, buffer underrun protection is enabled 01399 @return Returns 1 on success and 0 on failure. 01400 */ 01401 int burn_write_opts_set_underrun_proof(struct burn_write_opts *opts, 01402 int underrun_proof); 01403 01404 /** Sets whether to use opc or not with the write_opts struct 01405 @param opts The write opts to change 01406 @param opc If non-zero, optical power calibration will be performed at 01407 start of burn 01408 01409 */ 01410 void burn_write_opts_set_perform_opc(struct burn_write_opts *opts, int opc); 01411 01412 void burn_write_opts_set_has_mediacatalog(struct burn_write_opts *opts, int has_mediacatalog); 01413 01414 void burn_write_opts_set_mediacatalog(struct burn_write_opts *opts, unsigned char mediacatalog[13]); 01415 01416 01417 /* ts A61106 */ 01418 /** Sets the multi flag which eventually marks the emerging session as not 01419 being the last one and thus creating a BURN_DISC_APPENDABLE media. 01420 @param multi 1=media will be appendable, 0=media will be closed (default) 01421 */ 01422 void burn_write_opts_set_multi(struct burn_write_opts *opts, int multi); 01423 01424 01425 /* ts A61222 */ 01426 /** Sets a start address for writing to media and write modes which allow to 01427 choose this address at all (DVD+RW, DVD-RAM, formatted DVD-RW only for 01428 now). The address is given in bytes. If it is not -1 then a write run 01429 will fail if choice of start address is not supported or if the block 01430 alignment of the address is not suitable for media and write mode. 01431 (Alignment to 32 kB blocks is advised with DVD media.) 01432 @param opts The write opts to change 01433 @param value The address in bytes (-1 = start at default address) 01434 */ 01435 void burn_write_opts_set_start_byte(struct burn_write_opts *opts, off_t value); 01436 01437 01438 /* ts A70213 */ 01439 /** Caution: still immature and likely to change. Problems arose with 01440 sequential DVD-RW on one drive. 01441 01442 Controls wether the whole available space of the media shall be filled up 01443 by the last track of the last session. 01444 @param opts The write opts to change 01445 @param fill_up_media If 1 : fill up by last track, if 0 = do not fill up 01446 */ 01447 void burn_write_opts_set_fillup(struct burn_write_opts *opts, 01448 int fill_up_media); 01449 01450 01451 /* ts A70303 */ 01452 /** Eventually makes libburn ignore the failure of some conformance checks: 01453 - the check wether CD write+block type is supported by the drive 01454 - the check wether the media profile supports simulated burning 01455 @param opts The write opts to change 01456 @param use_force 1=ignore above checks, 0=refuse work on failed check 01457 */ 01458 void burn_write_opts_set_force(struct burn_write_opts *opts, int use_force); 01459 01460 01461 /** Sets whether to read in raw mode or not 01462 @param opts The read opts to change 01463 @param raw_mode If non-zero, reading will be done in raw mode, so that everything in the data tracks on the 01464 disc is read, including headers. 01465 */ 01466 void burn_read_opts_set_raw(struct burn_read_opts *opts, int raw_mode); 01467 01468 /** Sets whether to report c2 errors or not 01469 @param opts The read opts to change 01470 @param c2errors If non-zero, report c2 errors. 01471 */ 01472 void burn_read_opts_set_c2errors(struct burn_read_opts *opts, int c2errors); 01473 01474 /** Sets whether to read subcodes from audio tracks or not 01475 @param opts The read opts to change 01476 @param subcodes_audio If non-zero, read subcodes from audio tracks on the disc. 01477 */ 01478 void burn_read_opts_read_subcodes_audio(struct burn_read_opts *opts, 01479 int subcodes_audio); 01480 01481 /** Sets whether to read subcodes from data tracks or not 01482 @param opts The read opts to change 01483 @param subcodes_data If non-zero, read subcodes from data tracks on the disc. 01484 */ 01485 void burn_read_opts_read_subcodes_data(struct burn_read_opts *opts, 01486 int subcodes_data); 01487 01488 /** Sets whether to recover errors if possible 01489 @param opts The read opts to change 01490 @param hardware_error_recovery If non-zero, attempt to recover errors if possible. 01491 */ 01492 void burn_read_opts_set_hardware_error_recovery(struct burn_read_opts *opts, 01493 int hardware_error_recovery); 01494 01495 /** Sets whether to report recovered errors or not 01496 @param opts The read opts to change 01497 @param report_recovered_errors If non-zero, recovered errors will be reported. 01498 */ 01499 void burn_read_opts_report_recovered_errors(struct burn_read_opts *opts, 01500 int report_recovered_errors); 01501 01502 /** Sets whether blocks with unrecoverable errors should be read or not 01503 @param opts The read opts to change 01504 @param transfer_damaged_blocks If non-zero, blocks with unrecoverable errors will still be read. 01505 */ 01506 void burn_read_opts_transfer_damaged_blocks(struct burn_read_opts *opts, 01507 int transfer_damaged_blocks); 01508 01509 /** Sets the number of retries to attempt when trying to correct an error 01510 @param opts The read opts to change 01511 @param hardware_error_retries The number of retries to attempt when correcting an error. 01512 */ 01513 void burn_read_opts_set_hardware_error_retries(struct burn_read_opts *opts, 01514 unsigned char hardware_error_retries); 01515 01516 /** Gets the maximum write speed for a drive and eventually loaded media. 01517 The return value might change by the media type of already loaded media, 01518 again by call burn_drive_grab() and again by call burn_disc_read_atip(). 01519 @param d Drive to query 01520 @return Maximum write speed in K/s 01521 */ 01522 int burn_drive_get_write_speed(struct burn_drive *d); 01523 01524 01525 /* ts A61021 */ 01526 /** Gets the minimum write speed for a drive and eventually loaded media. 01527 The return value might change by the media type of already loaded media, 01528 again by call burn_drive_grab() and again by call burn_disc_read_atip(). 01529 @param d Drive to query 01530 @return Minimum write speed in K/s 01531 */ 01532 int burn_drive_get_min_write_speed(struct burn_drive *d); 01533 01534 01535 /** Gets the maximum read speed for a drive 01536 @param d Drive to query 01537 @return Maximum read speed in K/s 01538 */ 01539 int burn_drive_get_read_speed(struct burn_drive *d); 01540 01541 01542 /* ts A61226 */ 01543 /** Obtain a copy of the current speed descriptor list. The drive's list gets 01544 updated on various occasions such as burn_drive_grab() but the copy 01545 obtained here stays untouched. It has to be disposed via 01546 burn_drive_free_speedlist() when it is not longer needed. Speeds 01547 may appear several times in the list. The list content depends much on 01548 drive and media type. It seems that .source == 1 applies mostly to CD media 01549 whereas .source == 2 applies to any media. 01550 @param d Drive to query 01551 @param speed_list The copy. If empty, *speed_list gets returned as NULL. 01552 @return 1=success , 0=list empty , <0 severe error 01553 */ 01554 int burn_drive_get_speedlist(struct burn_drive *d, 01555 struct burn_speed_descriptor **speed_list); 01556 01557 /* ts A70713 */ 01558 /** Look up the fastest speed descriptor which is not faster than the given 01559 speed_goal. If it is 0, then the fastest one is chosen among the 01560 descriptors with the highest end_lba. If it is -1 then the slowest speed 01561 descriptor is chosen regardless of end_lba. Parameter flag decides wether 01562 the speed goal means write speed or read speed. 01563 @param d Drive to query 01564 @param speed_goal Upper limit for speed, 01565 0=search for maximum speed , -1 search for minimum speed 01566 @param best_descr Result of the search, NULL if no match 01567 @param flag Bitfield for control purposes 01568 bit0= look for best read speed rather than write speed 01569 bit1= look for any source type (else look for source==2 first 01570 and for any other source type only with CD media) 01571 @return >0 indicates a valid best_descr, 0 = no valid best_descr 01572 */ 01573 int burn_drive_get_best_speed(struct burn_drive *d, int speed_goal, 01574 struct burn_speed_descriptor **best_descr, int flag); 01575 01576 01577 /* ts A61226 */ 01578 /** Dispose a speed descriptor list copy which was obtained by 01579 burn_drive_get_speedlist(). 01580 @param speed_list The list copy. *speed_list gets set to NULL. 01581 @return 1=list disposed , 0= *speedlist was already NULL 01582 */ 01583 int burn_drive_free_speedlist(struct burn_speed_descriptor **speed_list); 01584 01585 01586 /* ts A70203 */ 01587 /** The reply structure for burn_disc_get_multi_caps() 01588 */ 01589 struct burn_multi_caps { 01590 01591 /* Multi-session capability allows to keep the media appendable after 01592 writing a session. It also guarantees that the drive will be able 01593 to predict and use the appropriate Next Writeable Address to place 01594 the next session on the media without overwriting the existing ones. 01595 It does not guarantee that the selected write type is able to do 01596 an appending session after the next session. (E.g. CD SAO is capable 01597 of multi-session by keeping a disc appendable. But .might_do_sao 01598 will be 0 afterwards, when checking the appendable media.) 01599 1= media may be kept appendable by burn_write_opts_set_multi(o,1) 01600 0= media will not be appendable 01601 */ 01602 int multi_session; 01603 01604 /* Multi-track capability allows to write more than one track source 01605 during a single session. The written tracks can later be found in 01606 libburn's TOC model with their start addresses and sizes. 01607 1= multiple tracks per session are allowed 01608 0= only one track per session allowed 01609 */ 01610 int multi_track; 01611 01612 /* Start-address capability allows to set a non-zero address with 01613 burn_write_opts_set_start_byte(). Eventually this has to respect 01614 .start_alignment and .start_range_low, .start_range_high in this 01615 structure. 01616 1= non-zero start address is allowed 01617 0= only start address 0 is allowed (to depict the drive's own idea 01618 about the appropriate write start) 01619 */ 01620 int start_adr; 01621 01622 /** The alignment for start addresses. 01623 ( start_address % start_alignment ) must be 0. 01624 */ 01625 off_t start_alignment; 01626 01627 /** The lowest permissible start address. 01628 */ 01629 off_t start_range_low; 01630 01631 /** The highest addressable start address. 01632 */ 01633 off_t start_range_high; 01634 01635 /** Potential availability of write modes 01636 4= needs no size prediction, not to be chosen automatically 01637 3= needs size prediction, not to be chosen automatically 01638 2= available, no size prediction necessary 01639 1= available, needs exact size prediction 01640 0= not available 01641 With CD media (profiles 0x09 and 0x0a) check also the elements 01642 *_block_types of the according write mode. 01643 */ 01644 int might_do_tao; 01645 int might_do_sao; 01646 int might_do_raw; 01647 01648 /** Generally advised write mode. 01649 Not necessarily the one chosen by burn_write_opts_auto_write_type() 01650 because the burn_disc structure might impose particular demands. 01651 */ 01652 enum burn_write_types advised_write_mode; 01653 01654 /** Write mode as given by parameter wt of burn_disc_get_multi_caps(). 01655 */ 01656 enum burn_write_types selected_write_mode; 01657 01658 /** Profile number which was current when the reply was generated */ 01659 int current_profile; 01660 01661 /** Wether the current profile indicates CD media. 1=yes, 0=no */ 01662 int current_is_cd_profile; 01663 01664 /* ts A70528, added to version 0.3.7 */ 01665 /** Wether the current profile is able to perform simulated write */ 01666 int might_simulate; 01667 }; 01668 01669 /** Allocates a struct burn_multi_caps (see above) and fills it with values 01670 which are appropriate for the drive and the loaded media. The drive 01671 must be grabbed for this call. The returned structure has to be disposed 01672 via burn_disc_free_multi_caps() when no longer needed. 01673 @param d The drive to inquire 01674 @param wt With BURN_WRITE_NONE the best capabilities of all write modes 01675 get returned. If set to a write mode like BURN_WRITE_SAO the 01676 capabilities with that particular mode are returned and the 01677 return value is 0 if the desired mode is not possible. 01678 @param caps returns the info structure 01679 @param flag Bitfield for control purposes (unused yet, submit 0) 01680 @return < 0 : error , 0 : writing seems impossible , 1 : writing possible 01681 */ 01682 int burn_disc_get_multi_caps(struct burn_drive *d, enum burn_write_types wt, 01683 struct burn_multi_caps **caps, int flag); 01684 01685 /** Removes from memory a multi session info structure which was returned by 01686 burn_disc_get_multi_caps(). The pointer *caps gets set to NULL. 01687 @param caps the info structure to dispose (note: pointer to pointer) 01688 @return 0 : *caps was already NULL, 1 : memory object was disposed 01689 */ 01690 int burn_disc_free_multi_caps(struct burn_multi_caps **caps); 01691 01692 01693 /** Gets a copy of the toc_entry structure associated with a track 01694 @param t Track to get the entry from 01695 @param entry Struct for the library to fill out 01696 */ 01697 void burn_track_get_entry(struct burn_track *t, struct burn_toc_entry *entry); 01698 01699 /** Gets a copy of the toc_entry structure associated with a session's lead out 01700 @param s Session to get the entry from 01701 @param entry Struct for the library to fill out 01702 */ 01703 void burn_session_get_leadout_entry(struct burn_session *s, 01704 struct burn_toc_entry *entry); 01705 01706 /** Gets an array of all the sessions for the disc 01707 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A SESSION 01708 @param d Disc to get session array for 01709 @param num Returns the number of sessions in the array 01710 @return array of sessions 01711 */ 01712 struct burn_session **burn_disc_get_sessions(struct burn_disc *d, 01713 int *num); 01714 01715 int burn_disc_get_sectors(struct burn_disc *d); 01716 01717 /** Gets an array of all the tracks for a session 01718 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A TRACK 01719 @param s session to get track array for 01720 @param num Returns the number of tracks in the array 01721 @return array of tracks 01722 */ 01723 struct burn_track **burn_session_get_tracks(struct burn_session *s, 01724 int *num); 01725 01726 int burn_session_get_sectors(struct burn_session *s); 01727 01728 /** Gets the mode of a track 01729 @param track the track to query 01730 @return the track's mode 01731 */ 01732 int burn_track_get_mode(struct burn_track *track); 01733 01734 /** Returns whether the first track of a session is hidden in the pregap 01735 @param session the session to query 01736 @return non-zero means the first track is hidden 01737 */ 01738 int burn_session_get_hidefirst(struct burn_session *session); 01739 01740 /** Returns the library's version in its parts 01741 @param major The major version number 01742 @param minor The minor version number 01743 @param micro The micro version number 01744 */ 01745 void burn_version(int *major, int *minor, int *micro); 01746 01747 01748 /* ts A60924 : ticket 74 */ 01749 /** Control queueing and stderr printing of messages from libburn. 01750 Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 01751 "NOTE", "UPDATE", "DEBUG", "ALL". 01752 @param queue_severity Gives the minimum limit for messages to be queued. 01753 Default: "NEVER". If you queue messages then you 01754 must consume them by burn_msgs_obtain(). 01755 @param print_severity Does the same for messages to be printed directly 01756 to stderr. Default: "FATAL". 01757 @param print_id A text prefix to be printed before the message. 01758 @return >0 for success, <=0 for error 01759 01760 */ 01761 int burn_msgs_set_severities(char *queue_severity, 01762 char *print_severity, char *print_id); 01763 01764 /* ts A60924 : ticket 74 */ 01765 #define BURN_MSGS_MESSAGE_LEN 4096 01766 01767 /** Obtain the oldest pending libburn message from the queue which has at 01768 least the given minimum_severity. This message and any older message of 01769 lower severity will get discarded from the queue and is then lost forever. 01770 @param minimum_severity may be one of "NEVER", "FATAL", "SORRY", 01771 "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL". 01772 To call with minimum_severity "NEVER" will discard the 01773 whole queue. 01774 @param error_code Will become a unique error code as liste in 01775 libburn/libdax_msgs.h 01776 @param msg_text Must provide at least BURN_MSGS_MESSAGE_LEN bytes. 01777 @param os_errno Will become the eventual errno related to the message 01778 @param severity Will become the severity related to the message and 01779 should provide at least 80 bytes. 01780 @return 1 if a matching item was found, 0 if not, <0 for severe errors 01781 */ 01782 int burn_msgs_obtain(char *minimum_severity, 01783 int *error_code, char msg_text[], int *os_errno, 01784 char severity[]); 01785 01786 01787 /* ts A61002 */ 01788 /* The prototype of a handler function suitable for burn_set_abort_handling(). 01789 Such a function has to return -2 if it does not want the process to 01790 exit with value 1. 01791 */ 01792 typedef int (*burn_abort_handler_t)(void *handle, int signum, int flag); 01793 01794 /** Control builtin signal handling. See also burn_abort(). 01795 @param handle Opaque handle eventually pointing to an application 01796 provided memory object 01797 @param handler A function to be called on signals. It will get handle as 01798 argument. It should finally call burn_abort(). See there. 01799 @param mode : 0 call handler(handle, signum, 0) on nearly all signals 01800 1 enable system default reaction on all signals 01801 2 try to ignore nearly all signals 01802 10 like mode 2 but handle SIGABRT like with mode 0 01803 Arguments (text, NULL, 0) activate the builtin abort handler. It will 01804 eventually call burn_abort() and then perform exit(1). If text is not NULL 01805 then it is used as prefix for pacifier messages of burn_abort_pacifier(). 01806 */ 01807 void burn_set_signal_handling(void *handle, burn_abort_handler_t handler, 01808 int mode); 01809 01810 #ifndef DOXYGEN 01811 01812 BURN_END_DECLS 01813 01814 #endif 01815 01816 #endif /*LIBBURN_H*/