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 00111 */ 00112 BURN_WRITE_PACKET, 00113 /** Track At Once recording. 00114 2s gaps between tracks, no fonky lead-ins 00115 */ 00116 BURN_WRITE_TAO, 00117 /** Session At Once. 00118 block type MUST be BURN_BLOCK_SAO 00119 */ 00120 BURN_WRITE_SAO, 00121 /** Raw disc at once recording. 00122 all subcodes must be provided by lib or user 00123 only raw block types are supported 00124 */ 00125 BURN_WRITE_RAW 00126 }; 00127 00128 /** Data format to send to the drive */ 00129 enum burn_block_types 00130 { 00131 /** sync, headers, edc/ecc provided by lib/user */ 00132 BURN_BLOCK_RAW0 = 1, 00133 /** sync, headers, edc/ecc and p/q subs provided by lib/user */ 00134 BURN_BLOCK_RAW16 = 2, 00135 /** sync, headers, edc/ecc and packed p-w subs provided by lib/user */ 00136 BURN_BLOCK_RAW96P = 4, 00137 /** sync, headers, edc/ecc and raw p-w subs provided by lib/user */ 00138 BURN_BLOCK_RAW96R = 8, 00139 /** only 2048 bytes of user data provided by lib/user */ 00140 BURN_BLOCK_MODE1 = 256, 00141 /** 2336 bytes of user data provided by lib/user */ 00142 BURN_BLOCK_MODE2R = 512, 00143 /** 2048 bytes of user data provided by lib/user 00144 subheader provided in write parameters 00145 are we ever going to support this shit? I vote no. 00146 (supposed to be supported on all drives...) 00147 */ 00148 BURN_BLOCK_MODE2_PATHETIC = 1024, 00149 /** 2048 bytes of data + 8 byte subheader provided by lib/user 00150 hey, this is also dumb 00151 */ 00152 BURN_BLOCK_MODE2_LAME = 2048, 00153 /** 2324 bytes of data provided by lib/user 00154 subheader provided in write parameters 00155 no sir, I don't like it. 00156 */ 00157 BURN_BLOCK_MODE2_OBSCURE = 4096, 00158 /** 2332 bytes of data supplied by lib/user 00159 8 bytes sub header provided in write parameters 00160 this is the second least suck mode2, and is mandatory for 00161 all drives to support. 00162 */ 00163 BURN_BLOCK_MODE2_OK = 8192, 00164 /** SAO block sizes are based on cue sheet, so use this. */ 00165 BURN_BLOCK_SAO = 16384 00166 }; 00167 00168 /** Possible status' of the drive in regard to the disc in it. */ 00169 enum burn_disc_status 00170 { 00171 /** The current status is not yet known */ 00172 BURN_DISC_UNREADY, 00173 /** The drive holds a blank disc */ 00174 BURN_DISC_BLANK, 00175 /** There is no disc at all in the drive */ 00176 BURN_DISC_EMPTY, 00177 /** There is an incomplete disc in the drive */ 00178 BURN_DISC_APPENDABLE, 00179 /** There is a disc with data on it in the drive */ 00180 BURN_DISC_FULL, 00181 00182 /* ts A61007 */ 00183 /** The drive was not grabbed when the status was inquired */ 00184 BURN_DISC_UNGRABBED, 00185 00186 /* ts A61020 */ 00187 /** The media seems not to be suitable for burning */ 00188 BURN_DISC_UNSUITABLE 00189 }; 00190 00191 00192 /** Possible data source return values */ 00193 enum burn_source_status 00194 { 00195 /** The source is ok */ 00196 BURN_SOURCE_OK, 00197 /** The source is at end of file */ 00198 BURN_SOURCE_EOF, 00199 /** The source is unusable */ 00200 BURN_SOURCE_FAILED 00201 }; 00202 00203 00204 /** Possible busy states for a drive */ 00205 enum burn_drive_status 00206 { 00207 /** The drive is not in an operation */ 00208 BURN_DRIVE_IDLE, 00209 /** The library is spawning the processes to handle a pending 00210 operation (A read/write/etc is about to start but hasn't quite 00211 yet) */ 00212 BURN_DRIVE_SPAWNING, 00213 /** The drive is reading data from a disc */ 00214 BURN_DRIVE_READING, 00215 /** The drive is writing data to a disc */ 00216 BURN_DRIVE_WRITING, 00217 /** The drive is writing Lead-In */ 00218 BURN_DRIVE_WRITING_LEADIN, 00219 /** The drive is writing Lead-Out */ 00220 BURN_DRIVE_WRITING_LEADOUT, 00221 /** The drive is erasing a disc */ 00222 BURN_DRIVE_ERASING, 00223 /** The drive is being grabbed */ 00224 BURN_DRIVE_GRABBING, 00225 00226 /* ts A61102 */ 00227 /** The drive gets written zeroes before the track payload data */ 00228 BURN_DRIVE_WRITING_PREGAP, 00229 /** The drive is told to close a track (TAO only) */ 00230 BURN_DRIVE_CLOSING_TRACK, 00231 /** The drive is told to close a session (TAO only) */ 00232 BURN_DRIVE_CLOSING_SESSION 00233 00234 }; 00235 00236 /** Information about a track on a disc - this is from the q sub channel of the 00237 lead-in area of a disc. The documentation here is very terse. 00238 See a document such as mmc3 for proper information. 00239 */ 00240 struct burn_toc_entry 00241 { 00242 /** Session the track is in */ 00243 unsigned char session; 00244 /** Type of data. for this struct to be valid, it must be 1 */ 00245 unsigned char adr; 00246 /** Type of data in the track */ 00247 unsigned char control; 00248 /** Zero. Always. Really. */ 00249 unsigned char tno; 00250 /** Track number or special information */ 00251 unsigned char point; 00252 unsigned char min; 00253 unsigned char sec; 00254 unsigned char frame; 00255 unsigned char zero; 00256 /** Track start time minutes for normal tracks */ 00257 unsigned char pmin; 00258 /** Track start time seconds for normal tracks */ 00259 unsigned char psec; 00260 /** Track start time frames for normal tracks */ 00261 unsigned char pframe; 00262 }; 00263 00264 00265 /** Data source for tracks */ 00266 struct burn_source { 00267 /** Reference count for the data source. Should be 1 when a new source 00268 is created. Increment it to take a reference for yourself. Use 00269 burn_source_free to destroy your reference to it. */ 00270 int refcount; 00271 00272 /** Read data from the source */ 00273 int (*read)(struct burn_source *, 00274 unsigned char *buffer, 00275 int size); 00276 00277 /** Read subchannel data from the source (NULL if lib generated) */ 00278 int (*read_sub)(struct burn_source *, 00279 unsigned char *buffer, 00280 int size); 00281 00282 /** Get the size of the source's data */ 00283 off_t (*get_size)(struct burn_source *); 00284 00285 /** Clean up the source specific data */ 00286 void (*free_data)(struct burn_source *); 00287 00288 /** Next source, for when a source runs dry and padding is disabled 00289 THIS IS AUTOMATICALLY HANDLED, DO NOT TOUCH 00290 */ 00291 struct burn_source *next; 00292 00293 /** Source specific data */ 00294 void *data; 00295 }; 00296 00297 00298 /** Information on a drive in the system */ 00299 struct burn_drive_info 00300 { 00301 /** Name of the vendor of the drive */ 00302 char vendor[9]; 00303 /** Name of the drive */ 00304 char product[17]; 00305 /** Revision of the drive */ 00306 char revision[5]; 00307 /** Location of the drive in the filesystem. */ 00308 char location[17]; 00309 /** This is currently the string which is used as persistent 00310 drive address. But be warned: there is NO GUARANTEE that this 00311 will stay so. Always use function burn_drive_get_adr() to 00312 inquire a persistent address. ^^^^^^ ALWAYS ^^^^^^ */ 00313 00314 /** Can the drive read DVD-RAM discs */ 00315 unsigned int read_dvdram:1; 00316 /** Can the drive read DVD-R discs */ 00317 unsigned int read_dvdr:1; 00318 /** Can the drive read DVD-ROM discs */ 00319 unsigned int read_dvdrom:1; 00320 /** Can the drive read CD-R discs */ 00321 unsigned int read_cdr:1; 00322 /** Can the drive read CD-RW discs */ 00323 unsigned int read_cdrw:1; 00324 00325 /** Can the drive write DVD-RAM discs */ 00326 unsigned int write_dvdram:1; 00327 /** Can the drive write DVD-R discs */ 00328 unsigned int write_dvdr:1; 00329 /** Can the drive write CD-R discs */ 00330 unsigned int write_cdr:1; 00331 /** Can the drive write CD-RW discs */ 00332 unsigned int write_cdrw:1; 00333 00334 /** Can the drive simulate a write */ 00335 unsigned int write_simulate:1; 00336 00337 /** Can the drive report C2 errors */ 00338 unsigned int c2_errors:1; 00339 00340 /** The size of the drive's buffer (in kilobytes) */ 00341 int buffer_size; 00342 /** 00343 * The supported block types in tao mode. 00344 * They should be tested with the desired block type. 00345 * See also burn_block_types. 00346 */ 00347 int tao_block_types; 00348 /** 00349 * The supported block types in sao mode. 00350 * They should be tested with the desired block type. 00351 * See also burn_block_types. 00352 */ 00353 int sao_block_types; 00354 /** 00355 * The supported block types in raw mode. 00356 * They should be tested with the desired block type. 00357 * See also burn_block_types. 00358 */ 00359 int raw_block_types; 00360 /** 00361 * The supported block types in packet mode. 00362 * They should be tested with the desired block type. 00363 * See also burn_block_types. 00364 */ 00365 int packet_block_types; 00366 00367 /** The value by which this drive can be indexed when using functions 00368 in the library. This is the value to pass to all libbburn functions 00369 that operate on a drive. */ 00370 struct burn_drive *drive; 00371 }; 00372 00373 00374 /** Operation progress report. All values are 0 based indices. 00375 * */ 00376 struct burn_progress { 00377 /** The total number of sessions */ 00378 int sessions; 00379 /** Current session.*/ 00380 int session; 00381 /** The total number of tracks */ 00382 int tracks; 00383 /** Current track. */ 00384 int track; 00385 /** The total number of indices */ 00386 int indices; 00387 /** Curent index. */ 00388 int index; 00389 /** The starting logical block address */ 00390 int start_sector; 00391 /** On write: The number of sectors. 00392 On blank: 0x10000 as upper limit for relative progress steps */ 00393 int sectors; 00394 /** On write: The current sector being processed. 00395 On blank: Relative progress steps 0 to 0x10000 */ 00396 int sector; 00397 00398 /* ts A61023 */ 00399 /** The capacity of the drive buffer */ 00400 unsigned buffer_capacity; 00401 /** The free space in the drive buffer (might be slightly outdated) */ 00402 unsigned buffer_available; 00403 00404 /* ts A61119 */ 00405 /** The number of bytes sent to the drive buffer */ 00406 off_t buffered_bytes; 00407 /** The minimum number of buffered bytes. (Caution: Before surely 00408 one buffer size of bytes was processed, this value is 0xffffffff.) 00409 */ 00410 unsigned buffer_min_fill; 00411 }; 00412 00413 /** Initialize the library. 00414 This must be called before using any other functions in the library. It 00415 may be called more than once with no effect. 00416 It is possible to 'restart' the library by shutting it down and 00417 re-initializing it. This is necessary if you follow the older and 00418 more general way of accessing a drive via burn_drive_scan() and 00419 burn_drive_grab(). See burn_drive_scan_and_grab() with its strong 00420 urges and its explanations. 00421 @return Nonzero if the library was able to initialize; zero if 00422 initialization failed. 00423 */ 00424 int burn_initialize(void); 00425 00426 /** Shutdown the library. 00427 This should be called before exiting your application. Make sure that all 00428 drives you have grabbed are released <i>before</i> calling this. 00429 */ 00430 void burn_finish(void); 00431 00432 00433 /* ts A61002 */ 00434 /** Abort any running drive operation and finally call burn_finish(). 00435 You MUST calm down the busy drive if an aborting event occurs during a 00436 burn run. For that you may call this function either from your own signal 00437 handling code or indirectly by activating the builtin signal handling: 00438 burn_set_signal_handling("my_app_name : ", NULL, 0); 00439 Else you may eventually call burn_drive_cancel() on the active drive and 00440 wait for it to assume state BURN_DRIVE_IDLE. 00441 @param patience Maximum number of seconds to wait for drives to finish 00442 @param pacifier_func If not NULL: a function to produce appeasing messages. 00443 See burn_abort_pacifier() for an example. 00444 @return 1 ok, all went well 00445 0 had to leave a drive in unclean state 00446 <0 severe error, do no use libburn again 00447 */ 00448 int burn_abort(int patience, 00449 int (*pacifier_func)(void *handle, int patience, int elapsed), 00450 void *handle); 00451 00452 /** A pacifier function suitable for burn_abort. 00453 @param handle If not NULL, a pointer to a text suitable for printf("%s") 00454 @param patience Maximum number of seconds to wait 00455 @param elapsed Elapsed number of seconds 00456 */ 00457 int burn_abort_pacifier(void *handle, int patience, int elapsed); 00458 00459 00460 /** ts A61006 : This is for development only. Not suitable for applications. 00461 Set the verbosity level of the library. The default value is 0, which means 00462 that nothing is output on stderr. The more you increase this, the more 00463 debug output should be displayed on stderr for you. 00464 @param level The verbosity level desired. 0 for nothing, higher positive 00465 values for more information output. 00466 */ 00467 void burn_set_verbosity(int level); 00468 00469 /* ts A60813 */ 00470 /** Set parameters for behavior on opening device files. To be called early 00471 after burn_initialize() and before any bus scan. But not mandatory at all. 00472 Parameter value 1 enables a feature, 0 disables. 00473 Default is (1,0,0). Have a good reason before you change it. 00474 @param exclusive 1 = Try to open only devices which are not marked as busy 00475 and try to mark them busy if opened sucessfully. (O_EXCL) 00476 There are kernels which simply don't care about O_EXCL. 00477 Some have it off, some have it on, some are switchable. 00478 2 = in case of a SCSI device, also try to open exclusively 00479 the matching /dev/sr, /dev/scd and /dev/st . 00480 0 = no attempt to make drive access exclusive. 00481 @param blocking Try to wait for drives which do not open immediately but 00482 also do not return an error as well. (O_NONBLOCK) 00483 This might stall indefinitely with /dev/hdX hard disks. 00484 @param abort_on_busy Unconditionally abort process when a non blocking 00485 exclusive opening attempt indicates a busy drive. 00486 Use this only after thorough tests with your app. 00487 */ 00488 void burn_preset_device_open(int exclusive, int blocking, int abort_on_busy); 00489 00490 00491 /* ts A60823 */ 00492 /** Aquire a drive with known persistent address.This is the sysadmin friendly 00493 way to open one drive and to leave all others untouched. It bundles 00494 the following API calls to form a non-obtrusive way to use libburn: 00495 burn_drive_add_whitelist() , burn_drive_scan() , burn_drive_grab() 00496 You are *strongly urged* to use this call whenever you know the drive 00497 address in advance. 00498 If not, then you have to use directly above calls. In that case, you are 00499 *strongly urged* to drop any unintended drive which will be exclusively 00500 occupied and not closed by burn_drive_scan(). 00501 This can be done by shutting down the library including a call to 00502 burn_finish(). You may later start a new libburn session and should then 00503 use the function described here with an address obtained after 00504 burn_drive_scan() via burn_drive_get_adr(&(drive_infos[driveno]), adr) . 00505 Another way is to drop the unwanted drives by burn_drive_info_forget(). 00506 @param drive_infos On success returns a one element array with the drive 00507 (cdrom/burner). Thus use with driveno 0 only. On failure 00508 the array has no valid elements at all. 00509 The returned array should be freed via burn_drive_info_free() 00510 when it is no longer needed, and before calling a scan 00511 function again. 00512 This is a result from call burn_drive_scan(). See there. 00513 Use with driveno 0 only. 00514 @param adr The persistent address of the desired drive. Either obtained 00515 by burn_drive_get_adr() or guessed skillfully by application 00516 resp. its user. 00517 @param load Nonzero to make the drive attempt to load a disc (close its 00518 tray door, etc). 00519 @return 1 = success , 0 = drive not found , -1 = other error 00520 */ 00521 int burn_drive_scan_and_grab(struct burn_drive_info *drive_infos[], 00522 char* adr, int load); 00523 00524 00525 /* ts A51221 */ 00526 /** Maximum number of particularly permissible drive addresses */ 00527 #define BURN_DRIVE_WHITELIST_LEN 255 00528 /** Add a device to the list of permissible drives. As soon as some entry is in 00529 the whitelist all non-listed drives are banned from scanning. 00530 @return 1 success, <=0 failure 00531 */ 00532 int burn_drive_add_whitelist(char *device_address); 00533 00534 /** Remove all drives from whitelist. This enables all possible drives. */ 00535 void burn_drive_clear_whitelist(void); 00536 00537 00538 /** Scan for drives. This function MUST be called until it returns nonzero. 00539 No drives may be in use when this is called. 00540 All drive pointers are invalidated by using this function. Do NOT store 00541 drive pointers across calls to this function or death AND pain will ensue. 00542 After this call all drives depicted by the returned array are subject 00543 to eventual (O_EXCL) locking. See burn_preset_device_open(). This state 00544 ends either with burn_drive_info_forget() or with burn_drive_release(). 00545 It is unfriendly to other processes on the system to hold drives locked 00546 which one does not definitely plan to use soon. 00547 @param drive_infos Returns an array of drive info items (cdroms/burners). 00548 The returned array must be freed by burn_drive_info_free() 00549 before burn_finish(), and also before calling this function 00550 burn_drive_scan() again. 00551 @param n_drives Returns the number of drive items in drive_infos. 00552 @return 0 while scanning is not complete 00553 >0 when it is finished sucessfully, 00554 <0 when finished but failed. 00555 */ 00556 int burn_drive_scan(struct burn_drive_info *drive_infos[], 00557 unsigned int *n_drives); 00558 00559 /* ts A60904 : ticket 62, contribution by elmom */ 00560 /** Release memory about a single drive and any exclusive lock on it. 00561 Become unable to inquire or grab it. Expect FATAL consequences if you try. 00562 @param drive_info pointer to a single element out of the array 00563 obtained from burn_drive_scan() : &(drive_infos[driveno]) 00564 @param force controls degree of permissible drive usage at the moment this 00565 function is called, and the amount of automatically provided 00566 drive shutdown : 00567 0= drive must be ungrabbed and BURN_DRIVE_IDLE 00568 1= try to release drive resp. accept BURN_DRIVE_GRABBING 00569 Use these two only. Further values are to be defined. 00570 @return 1 on success, 2 if drive was already forgotten, 00571 0 if not permissible, <0 on other failures, 00572 */ 00573 int burn_drive_info_forget(struct burn_drive_info *drive_info, int force); 00574 00575 00576 /** Free a burn_drive_info array returned by burn_drive_scan 00577 */ 00578 void burn_drive_info_free(struct burn_drive_info drive_infos[]); 00579 00580 00581 /* ts A60823 */ 00582 /** Maximum length+1 to expect with a persistent drive address string */ 00583 #define BURN_DRIVE_ADR_LEN 1024 00584 00585 /** Inquire the persistent address of the given drive. 00586 @param drive_info The drive to inquire. Usually some &(drive_infos[driveno]) 00587 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00588 characters size. The persistent address gets copied to it. 00589 @return >0 success , <=0 error (due to libburn internal problem) 00590 */ 00591 int burn_drive_get_adr(struct burn_drive_info *drive_info, char adr[]); 00592 00593 /* ts A60922 ticket 33 */ 00594 /** Evaluate wether the given address would be a possible persistent drive 00595 address of libburn. 00596 @return 1 means yes, 0 means no 00597 */ 00598 int burn_drive_is_enumerable_adr(char *adr); 00599 00600 /* ts A60922 ticket 33 */ 00601 /** Try to convert a given existing filesystem address into a persistent drive 00602 address. This succeeds with symbolic links or if a hint about the drive's 00603 system address can be read from the filesystem object and a matching drive 00604 is found. 00605 @param path The address of an existing file system object 00606 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00607 characters size. The persistent address gets copied to it. 00608 @return 1 = success , 0 = failure , -1 = severe error 00609 */ 00610 int burn_drive_convert_fs_adr(char *path, char adr[]); 00611 00612 /* ts A60923 */ 00613 /** Try to convert a given SCSI address of bus,host,channel,target,lun into 00614 a persistent drive address. If a SCSI address component parameter is < 0 00615 then it is not decisive and the first enumerated address which matches 00616 the >= 0 parameters is taken as result. 00617 Note: bus and (host,channel) are supposed to be redundant. 00618 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00619 characters size. The persistent address gets copied to it. 00620 @return 1 = success , 0 = failure , -1 = severe error 00621 */ 00622 int burn_drive_convert_scsi_adr(int bus_no, int host_no, int channel_no, 00623 int target_no, int lun_no, char adr[]); 00624 00625 /* ts A60923 - A61005 */ 00626 /** Try to obtain bus,host,channel,target,lun from path. If there is an SCSI 00627 address at all, then this call should succeed with a persistent 00628 drive address obtained via burn_drive_get_adr(). It is also supposed to 00629 succeed with any device file of a (possibly emulated) SCSI device. 00630 @return 1 = success , 0 = failure , -1 = severe error 00631 */ 00632 int burn_drive_obtain_scsi_adr(char *path, int *bus_no, int *host_no, 00633 int *channel_no, int *target_no, int *lun_no); 00634 00635 /** Grab a drive. This must be done before the drive can be used (for reading, 00636 writing, etc). 00637 @param drive The drive to grab. This is found in a returned 00638 burn_drive_info struct. 00639 @param load Nonzero to make the drive attempt to load a disc (close its 00640 tray door, etc). 00641 @return 1 if it was possible to grab the drive, else 0 00642 */ 00643 int burn_drive_grab(struct burn_drive *drive, int load); 00644 00645 00646 /** Release a drive. This should not be done until the drive is no longer 00647 busy (see burn_drive_get_status). The drive is (O_EXCL) unlocked 00648 afterwards. 00649 @param drive The drive to release. 00650 @param eject Nonzero to make the drive eject the disc in it. 00651 */ 00652 void burn_drive_release(struct burn_drive *drive, int eject); 00653 00654 00655 /** Returns what kind of disc a drive is holding. This function may need to be 00656 called more than once to get a proper status from it. See burn_disc_status 00657 for details. 00658 @param drive The drive to query for a disc. 00659 @return The status of the drive, or what kind of disc is in it. 00660 Note: BURN_DISC_UNGRABBED indicates wrong API usage 00661 */ 00662 enum burn_disc_status burn_disc_get_status(struct burn_drive *drive); 00663 00664 00665 /* ts A61020 */ 00666 /** WARNING: This revives an old bug-like behavior that might be dangerous. 00667 Sets the drive status to BURN_DISC_BLANK if it is BURN_DISC_UNREADY 00668 or BURN_DISC_UNSUITABLE. Thus marking media as writable which actually 00669 failed to declare themselves either blank or (partially) filled. 00670 @return 1 drive status has been set , 0 = unsuitable drive status 00671 */ 00672 int burn_disc_pretend_blank(struct burn_drive *drive); 00673 00674 00675 /* ts A61106 */ 00676 /** WARNING: This overrides the safety measures against unsuitable media. 00677 Sets the drive status to BURN_DISC_FULL if it is BURN_DISC_UNREADY 00678 or BURN_DISC_UNSUITABLE. Thus marking media as blankable which actually 00679 failed to declare themselves either blank or (partially) filled. 00680 */ 00681 int burn_disc_pretend_full(struct burn_drive *drive); 00682 00683 00684 /* ts A61021 */ 00685 /** Reads ATIP information from inserted media. To be obtained via 00686 burn_drive_get_write_speed(), burn_drive_get_min_write_speed(), 00687 burn_drive_get_start_end_lba(). The drive must be grabbed for this call. 00688 @param drive The drive to query. 00689 @return 1=sucess, 0=no valid ATIP info read, -1 severe error 00690 */ 00691 int burn_disc_read_atip(struct burn_drive *drive); 00692 00693 00694 /* ts A61020 */ 00695 /** Returns start and end lba of the media which is currently inserted 00696 in the given drive. The drive has to be grabbed to have hope for reply. 00697 Shortcomming (not a feature): unless burn_disc_read_atip() was called 00698 only blank media will return valid info. 00699 @param drive The drive to query. 00700 @param start_lba Returns the start lba value 00701 @param end_lba Returns the end lba value 00702 @param flag Bitfield for control purposes (unused yet, submit 0) 00703 @return 1 if lba values are valid , 0 if invalid 00704 */ 00705 int burn_drive_get_start_end_lba(struct burn_drive *drive, 00706 int *start_lba, int *end_lba, int flag); 00707 00708 /* ts A61110 */ 00709 /** Read start lba and Next Writeable Address of a track from media. 00710 Usually a track lba is obtained from the result of burn_track_get_entry(). 00711 This call retrieves an updated lba, eventual nwa, and can address the 00712 invisible track to come. 00713 The drive must be grabbed for this call. One may not issue this call 00714 during ongoing burn_disc_write() or burn_disc_erase(). 00715 @param d The drive to query. 00716 @param o If not NULL: write parameters to be set on drive before query 00717 @param trackno 0=next track to come, >0 number of existing track 00718 @return 1=nwa is valid , 0=nwa is not valid , -1=error 00719 */ 00720 int burn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o, 00721 int trackno, int *lba, int *nwa); 00722 00723 00724 /** Tells whether a disc can be erased or not 00725 @return Non-zero means erasable 00726 */ 00727 int burn_disc_erasable(struct burn_drive *d); 00728 00729 /** Returns the progress and status of a drive. 00730 @param drive The drive to query busy state for. 00731 @param p Returns the progress of the operation, NULL if you don't care 00732 @return the current status of the drive. See also burn_drive_status. 00733 */ 00734 enum burn_drive_status burn_drive_get_status(struct burn_drive *drive, 00735 struct burn_progress *p); 00736 00737 /** Creates a write_opts struct for burning to the specified drive 00738 must be freed with burn_write_opts_free 00739 @param drive The drive to write with 00740 @return The write_opts, NULL on error 00741 */ 00742 struct burn_write_opts *burn_write_opts_new(struct burn_drive *drive); 00743 00744 /** Frees a write_opts struct created with burn_write_opts_new 00745 @param opts write_opts to free 00746 */ 00747 void burn_write_opts_free(struct burn_write_opts *opts); 00748 00749 /** Creates a read_opts struct for reading from the specified drive 00750 must be freed with burn_write_opts_free 00751 @param drive The drive to read from 00752 @return The read_opts 00753 */ 00754 struct burn_read_opts *burn_read_opts_new(struct burn_drive *drive); 00755 00756 /** Frees a read_opts struct created with burn_read_opts_new 00757 @param opts write_opts to free 00758 */ 00759 void burn_read_opts_free(struct burn_read_opts *opts); 00760 00761 /** Erase a disc in the drive. The drive must be grabbed successfully BEFORE 00762 calling this functions. Always ensure that the drive reports a status of 00763 BURN_DISC_FULL before calling this function. An erase operation is not 00764 cancellable, as control of the operation is passed wholly to the drive and 00765 there is no way to interrupt it safely. 00766 @param drive The drive with which to erase a disc. 00767 @param fast Nonzero to do a fast erase, where only the disc's headers are 00768 erased; zero to erase the entire disc. 00769 */ 00770 void burn_disc_erase(struct burn_drive *drive, int fast); 00771 00772 /* ts A61109 : this is defunct */ 00773 /** Read a disc from the drive and write it to an fd pair. The drive must be 00774 grabbed successfully BEFORE calling this function. Always ensure that the 00775 drive reports a status of BURN_DISC_FULL before calling this function. 00776 @param drive The drive from which to read a disc. 00777 @param o The options for the read operation. 00778 */ 00779 void burn_disc_read(struct burn_drive *drive, const struct burn_read_opts *o); 00780 00781 /** Write a disc in the drive. The drive must be grabbed successfully before 00782 calling this function. Always ensure that the drive reports a status of 00783 BURN_DISC_BLANK before calling this function. 00784 @param o The options for the writing operation. 00785 @param disc The struct burn_disc * that described the disc to be created 00786 */ 00787 void burn_disc_write(struct burn_write_opts *o, struct burn_disc *disc); 00788 00789 /** Cancel an operation on a drive. 00790 This will only work when the drive's busy state is BURN_DRIVE_READING or 00791 BURN_DRIVE_WRITING. 00792 @param drive The drive on which to cancel the current operation. 00793 */ 00794 void burn_drive_cancel(struct burn_drive *drive); 00795 00796 /** Convert a minute-second-frame (MSF) value to sector count 00797 @param m Minute component 00798 @param s Second component 00799 @param f Frame component 00800 @return The sector count 00801 */ 00802 int burn_msf_to_sectors(int m, int s, int f); 00803 00804 /** Convert a sector count to minute-second-frame (MSF) 00805 @param sectors The sector count 00806 @param m Returns the minute component 00807 @param s Returns the second component 00808 @param f Returns the frame component 00809 */ 00810 void burn_sectors_to_msf(int sectors, int *m, int *s, int *f); 00811 00812 /** Convert a minute-second-frame (MSF) value to an lba 00813 @param m Minute component 00814 @param s Second component 00815 @param f Frame component 00816 @return The lba 00817 */ 00818 int burn_msf_to_lba(int m, int s, int f); 00819 00820 /** Convert an lba to minute-second-frame (MSF) 00821 @param lba The lba 00822 @param m Returns the minute component 00823 @param s Returns the second component 00824 @param f Returns the frame component 00825 */ 00826 void burn_lba_to_msf(int lba, int *m, int *s, int *f); 00827 00828 /** Create a new disc (for DAO recording)*/ 00829 struct burn_disc *burn_disc_create(void); 00830 00831 /** Delete disc and decrease the reference count on all its sessions 00832 @param d The disc to be freed 00833 */ 00834 void burn_disc_free(struct burn_disc *d); 00835 00836 /** Create a new session (For SAO at once recording, or to be added to a 00837 disc for DAO) 00838 */ 00839 struct burn_session *burn_session_create(void); 00840 00841 /** Free a session (and decrease reference count on all tracks inside) 00842 @param s Session to be freed 00843 */ 00844 void burn_session_free(struct burn_session *s); 00845 00846 /** Add a session to a disc at a specific position, increasing the 00847 sessions's reference count. 00848 @param d Disc to add the session to 00849 @param s Session to add to the disc 00850 @param pos position to add at (BURN_POS_END is "at the end") 00851 @return 0 for failure, 1 for success 00852 */ 00853 int burn_disc_add_session(struct burn_disc *d, struct burn_session *s, 00854 unsigned int pos); 00855 00856 /** Remove a session from a disc 00857 @param d Disc to remove session from 00858 @param s Session pointer to find and remove 00859 */ 00860 int burn_disc_remove_session(struct burn_disc *d, struct burn_session *s); 00861 00862 00863 /** Create a track (for TAO recording, or to put in a session) */ 00864 struct burn_track *burn_track_create(void); 00865 00866 /** Free a track 00867 @param t Track to free 00868 */ 00869 void burn_track_free(struct burn_track *t); 00870 00871 /** Add a track to a session at specified position 00872 @param s Session to add to 00873 @param t Track to insert in session 00874 @param pos position to add at (BURN_POS_END is "at the end") 00875 @return 0 for failure, 1 for success 00876 */ 00877 int burn_session_add_track(struct burn_session *s, struct burn_track *t, 00878 unsigned int pos); 00879 00880 /** Remove a track from a session 00881 @param s Session to remove track from 00882 @param t Track pointer to find and remove 00883 @return 0 for failure, 1 for success 00884 */ 00885 int burn_session_remove_track(struct burn_session *s, struct burn_track *t); 00886 00887 00888 /** Define the data in a track 00889 @param t the track to define 00890 @param offset The lib will write this many 0s before start of data 00891 @param tail The number of extra 0s to write after data 00892 @param pad 1 means the lib should pad the last sector with 0s if the 00893 track isn't exactly sector sized. (otherwise the lib will 00894 begin reading from the next track) 00895 @param mode data format (bitfield) 00896 */ 00897 void burn_track_define_data(struct burn_track *t, int offset, int tail, 00898 int pad, int mode); 00899 00900 00901 /* ts A61024 */ 00902 /** Define wether a track shall swap bytes of its input stream. 00903 @param t The track to change 00904 @param swap_source_bytes 0=do not swap, 1=swap byte pairs 00905 @return 1=success , 0=unacceptable value 00906 */ 00907 int burn_track_set_byte_swap(struct burn_track *t, int swap_source_bytes); 00908 00909 00910 /** Set the ISRC details for a track 00911 @param t The track to change 00912 @param country the 2 char country code. Each character must be 00913 only numbers or letters. 00914 @param owner 3 char owner code. Each character must be only numbers 00915 or letters. 00916 @param year 2 digit year. A number in 0-99 (Yep, not Y2K friendly). 00917 @param serial 5 digit serial number. A number in 0-99999. 00918 */ 00919 void burn_track_set_isrc(struct burn_track *t, char *country, char *owner, 00920 unsigned char year, unsigned int serial); 00921 00922 /** Disable ISRC parameters for a track 00923 @param t The track to change 00924 */ 00925 void burn_track_clear_isrc(struct burn_track *t); 00926 00927 /** Hide the first track in the "pre gap" of the disc 00928 @param s session to change 00929 @param onoff 1 to enable hiding, 0 to disable 00930 */ 00931 void burn_session_hide_first_track(struct burn_session *s, int onoff); 00932 00933 /** Get the drive's disc struct - free when done 00934 @param d drive to query 00935 @return the disc struct or NULL on failure 00936 */ 00937 struct burn_disc *burn_drive_get_disc(struct burn_drive *d); 00938 00939 /** Set the track's data source 00940 @param t The track to set the data source for 00941 @param s The data source to use for the contents of the track 00942 @return An error code stating if the source is ready for use for 00943 writing the track, or if an error occured 00944 00945 */ 00946 enum burn_source_status burn_track_set_source(struct burn_track *t, 00947 struct burn_source *s); 00948 00949 /** Free a burn_source (decrease its refcount and maybe free it) 00950 @param s Source to free 00951 */ 00952 void burn_source_free(struct burn_source *s); 00953 00954 /** Creates a data source for an image file (and maybe subcode file) */ 00955 struct burn_source *burn_file_source_new(const char *path, 00956 const char *subpath); 00957 00958 /** Creates a data source for an image file (a track) from an open 00959 readable filedescriptor, an eventually open readable subcodes file 00960 descriptor and eventually a fixed size in bytes. 00961 @param datafd The source of data. 00962 @param subfd The eventual source for subcodes. Not used if -1. 00963 @param size The eventual fixed size of eventually both fds. 00964 If this value is 0, the size will be determined from datafd. 00965 */ 00966 struct burn_source *burn_fd_source_new(int datafd, int subfd, off_t size); 00967 00968 /** Tells how long a track will be on disc 00969 >>> NOTE: Not reliable with tracks of undefined length 00970 */ 00971 int burn_track_get_sectors(struct burn_track *); 00972 00973 00974 /* ts A61101 */ 00975 /** Tells how many source bytes have been read and how many data bytes have 00976 been written by the track during burn */ 00977 int burn_track_get_counters(struct burn_track *t, 00978 off_t *read_bytes, off_t *written_bytes); 00979 00980 00981 /** Sets drive read and write speed 00982 @param d The drive to set speed for 00983 @param read Read speed in k/s (0 is max) 00984 @param write Write speed in k/s (0 is max) 00985 */ 00986 void burn_drive_set_speed(struct burn_drive *d, int read, int write); 00987 00988 /* these are for my debugging, they will disappear */ 00989 void burn_structure_print_disc(struct burn_disc *d); 00990 void burn_structure_print_session(struct burn_session *s); 00991 void burn_structure_print_track(struct burn_track *t); 00992 00993 /** Sets the write type for the write_opts struct 00994 @param opts The write opts to change 00995 @param write_type The write type to use 00996 @param block_type The block type to use 00997 @return Returns 1 on success and 0 on failure. 00998 */ 00999 int burn_write_opts_set_write_type(struct burn_write_opts *opts, 01000 enum burn_write_types write_type, 01001 int block_type); 01002 01003 /** Supplies toc entries for writing - not normally required for cd mastering 01004 @param opts The write opts to change 01005 @param count The number of entries 01006 @param toc_entries 01007 */ 01008 void burn_write_opts_set_toc_entries(struct burn_write_opts *opts, 01009 int count, 01010 struct burn_toc_entry *toc_entries); 01011 01012 /** Sets the session format for a disc 01013 @param opts The write opts to change 01014 @param format The session format to set 01015 */ 01016 void burn_write_opts_set_format(struct burn_write_opts *opts, int format); 01017 01018 /** Sets the simulate value for the write_opts struct 01019 @param opts The write opts to change 01020 @param sim If non-zero, the drive will perform a simulation instead of a burn 01021 @return Returns 1 on success and 0 on failure. 01022 */ 01023 int burn_write_opts_set_simulate(struct burn_write_opts *opts, int sim); 01024 01025 /** Controls buffer underrun prevention 01026 @param opts The write opts to change 01027 @param underrun_proof if non-zero, buffer underrun protection is enabled 01028 @return Returns 1 on success and 0 on failure. 01029 */ 01030 int burn_write_opts_set_underrun_proof(struct burn_write_opts *opts, 01031 int underrun_proof); 01032 01033 /** Sets whether to use opc or not with the write_opts struct 01034 @param opts The write opts to change 01035 @param opc If non-zero, optical power calibration will be performed at 01036 start of burn 01037 01038 */ 01039 void burn_write_opts_set_perform_opc(struct burn_write_opts *opts, int opc); 01040 01041 void burn_write_opts_set_has_mediacatalog(struct burn_write_opts *opts, int has_mediacatalog); 01042 01043 void burn_write_opts_set_mediacatalog(struct burn_write_opts *opts, unsigned char mediacatalog[13]); 01044 01045 01046 /* ts A61106 */ 01047 /* Sets the multi flag which eventually marks the emerging session as not being 01048 the last one and thus creating a BURN_DISC_APPENDABLE media. 01049 @param multi 1=media will be appendable, 0=media will be closed (default) 01050 */ 01051 void burn_write_opts_set_multi(struct burn_write_opts *opts, int multi); 01052 01053 01054 /** Sets whether to read in raw mode or not 01055 @param opts The read opts to change 01056 @param raw_mode If non-zero, reading will be done in raw mode, so that everything in the data tracks on the 01057 disc is read, including headers. 01058 */ 01059 void burn_read_opts_set_raw(struct burn_read_opts *opts, int raw_mode); 01060 01061 /** Sets whether to report c2 errors or not 01062 @param opts The read opts to change 01063 @param c2errors If non-zero, report c2 errors. 01064 */ 01065 void burn_read_opts_set_c2errors(struct burn_read_opts *opts, int c2errors); 01066 01067 /** Sets whether to read subcodes from audio tracks or not 01068 @param opts The read opts to change 01069 @param subcodes_audio If non-zero, read subcodes from audio tracks on the disc. 01070 */ 01071 void burn_read_opts_read_subcodes_audio(struct burn_read_opts *opts, 01072 int subcodes_audio); 01073 01074 /** Sets whether to read subcodes from data tracks or not 01075 @param opts The read opts to change 01076 @param subcodes_data If non-zero, read subcodes from data tracks on the disc. 01077 */ 01078 void burn_read_opts_read_subcodes_data(struct burn_read_opts *opts, 01079 int subcodes_data); 01080 01081 /** Sets whether to recover errors if possible 01082 @param opts The read opts to change 01083 @param hardware_error_recovery If non-zero, attempt to recover errors if possible. 01084 */ 01085 void burn_read_opts_set_hardware_error_recovery(struct burn_read_opts *opts, 01086 int hardware_error_recovery); 01087 01088 /** Sets whether to report recovered errors or not 01089 @param opts The read opts to change 01090 @param report_recovered_errors If non-zero, recovered errors will be reported. 01091 */ 01092 void burn_read_opts_report_recovered_errors(struct burn_read_opts *opts, 01093 int report_recovered_errors); 01094 01095 /** Sets whether blocks with unrecoverable errors should be read or not 01096 @param opts The read opts to change 01097 @param transfer_damaged_blocks If non-zero, blocks with unrecoverable errors will still be read. 01098 */ 01099 void burn_read_opts_transfer_damaged_blocks(struct burn_read_opts *opts, 01100 int transfer_damaged_blocks); 01101 01102 /** Sets the number of retries to attempt when trying to correct an error 01103 @param opts The read opts to change 01104 @param hardware_error_retries The number of retries to attempt when correcting an error. 01105 */ 01106 void burn_read_opts_set_hardware_error_retries(struct burn_read_opts *opts, 01107 unsigned char hardware_error_retries); 01108 01109 /** Gets the maximum write speed for a drive 01110 @param d Drive to query 01111 @return Maximum write speed in K/s 01112 */ 01113 int burn_drive_get_write_speed(struct burn_drive *d); 01114 01115 01116 /* ts A61021 */ 01117 /** Gets the minimum write speed for a drive. This might differ from 01118 burn_drive_get_write_speed() only after burn_disc_read_atip() 01119 @param d Drive to query 01120 @return Minimum write speed in K/s 01121 */ 01122 int burn_drive_get_min_write_speed(struct burn_drive *d); 01123 01124 01125 /** Gets the maximum read speed for a drive 01126 @param d Drive to query 01127 @return Maximum read speed in K/s 01128 */ 01129 int burn_drive_get_read_speed(struct burn_drive *d); 01130 01131 /** Gets a copy of the toc_entry structure associated with a track 01132 @param t Track to get the entry from 01133 @param entry Struct for the library to fill out 01134 */ 01135 void burn_track_get_entry(struct burn_track *t, struct burn_toc_entry *entry); 01136 01137 /** Gets a copy of the toc_entry structure associated with a session's lead out 01138 @param s Session to get the entry from 01139 @param entry Struct for the library to fill out 01140 */ 01141 void burn_session_get_leadout_entry(struct burn_session *s, 01142 struct burn_toc_entry *entry); 01143 01144 /** Gets an array of all the sessions for the disc 01145 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A SESSION 01146 @param d Disc to get session array for 01147 @param num Returns the number of sessions in the array 01148 @return array of sessions 01149 */ 01150 struct burn_session **burn_disc_get_sessions(struct burn_disc *d, 01151 int *num); 01152 01153 int burn_disc_get_sectors(struct burn_disc *d); 01154 01155 /** Gets an array of all the tracks for a session 01156 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A TRACK 01157 @param s session to get track array for 01158 @param num Returns the number of tracks in the array 01159 @return array of tracks 01160 */ 01161 struct burn_track **burn_session_get_tracks(struct burn_session *s, 01162 int *num); 01163 01164 int burn_session_get_sectors(struct burn_session *s); 01165 01166 /** Gets the mode of a track 01167 @param track the track to query 01168 @return the track's mode 01169 */ 01170 int burn_track_get_mode(struct burn_track *track); 01171 01172 /** Returns whether the first track of a session is hidden in the pregap 01173 @param session the session to query 01174 @return non-zero means the first track is hidden 01175 */ 01176 int burn_session_get_hidefirst(struct burn_session *session); 01177 01178 /** Returns the library's version in its parts 01179 @param major The major version number 01180 @param minor The minor version number 01181 @param micro The micro version number 01182 */ 01183 void burn_version(int *major, int *minor, int *micro); 01184 01185 01186 /* ts A60924 : ticket 74 */ 01187 /** Control queueing and stderr printing of messages from libburn. 01188 Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 01189 "NOTE", "UPDATE", "DEBUG", "ALL". 01190 @param queue_severity Gives the minimum limit for messages to be queued. 01191 Default: "NEVER". If you queue messages then you 01192 must consume them by burn_msgs_obtain(). 01193 @param print_severity Does the same for messages to be printed directly 01194 to stderr. Default: "FATAL". 01195 @param print_id A text prefix to be printed before the message. 01196 @return >0 for success, <=0 for error 01197 01198 */ 01199 int burn_msgs_set_severities(char *queue_severity, 01200 char *print_severity, char *print_id); 01201 01202 /* ts A60924 : ticket 74 */ 01203 #define BURN_MSGS_MESSAGE_LEN 4096 01204 01205 /** Obtain the oldest pending libburn message from the queue which has at 01206 least the given minimum_severity. This message and any older message of 01207 lower severity will get discarded from the queue and is then lost forever. 01208 Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 01209 "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 01210 will discard the whole queue. 01211 @param error_code Will become a unique error code as liste in 01212 libburn/libdax_msgs.h 01213 @param msg_text Must provide at least BURN_MSGS_MESSAGE_LEN bytes. 01214 @param os_errno Will become the eventual errno related to the message 01215 @param severity Will become the severity related to the message and 01216 should provide at least 80 bytes. 01217 @return 1 if a matching item was found, 0 if not, <0 for severe errors 01218 */ 01219 int burn_msgs_obtain(char *minimum_severity, 01220 int *error_code, char msg_text[], int *os_errno, 01221 char severity[]); 01222 01223 01224 /* ts A61002 */ 01225 /* The prototype of a handler function suitable for burn_set_abort_handling(). 01226 Such a function has to return -2 if it does not want the process to 01227 exit with value 1. 01228 */ 01229 typedef int (*burn_abort_handler_t)(void *handle, int signum, int flag); 01230 01231 /** Control builtin signal handling. See also burn_abort(). 01232 @param handle Opaque handle eventually pointing to an application 01233 provided memory object 01234 @param handler A function to be called on signals. It will get handle as 01235 argument. It should finally call burn_abort(). See there. 01236 @param mode : 0 call handler(handle, signum, 0) on nearly all signals 01237 1 enable system default reaction on all signals 01238 2 try to ignore nearly all signals 01239 10 like mode 2 but handle SIGABRT like with mode 0 01240 Arguments (text, NULL, 0) activate the builtin abort handler. It will 01241 eventually call burn_abort() and then perform exit(1). If text is not NULL 01242 then it is used as prefix for pacifier messages of burn_abort_pacifier(). 01243 */ 01244 void burn_set_signal_handling(void *handle, burn_abort_handler_t handler, 01245 int mode); 01246 01247 #ifndef DOXYGEN 01248 01249 BURN_END_DECLS 01250 01251 #endif 01252 01253 #endif /*LIBBURN_H*/