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 */ 00011 #include <sys/types.h> 00012 00013 #ifndef DOXYGEN 00014 00015 #if defined(__cplusplus) 00016 #define BURN_BEGIN_DECLS \ 00017 namespace burn { \ 00018 extern "C" { 00019 #define BURN_END_DECLS \ 00020 } \ 00021 } 00022 #else 00023 #define BURN_BEGIN_DECLS 00024 #define BURN_END_DECLS 00025 #endif 00026 00027 BURN_BEGIN_DECLS 00028 00029 #endif 00030 00031 /** References a physical drive in the system */ 00032 struct burn_drive; 00033 00034 /** References a whole disc */ 00035 struct burn_disc; 00036 00037 /** References a single session on a disc */ 00038 struct burn_session; 00039 00040 /** References a single track on a disc */ 00041 struct burn_track; 00042 00043 /** Session format for normal audio or data discs */ 00044 #define BURN_CDROM 0 00045 /** Session format for obsolete CD-I discs */ 00046 #define BURN_CDI 0x10 00047 /** Session format for CDROM-XA discs */ 00048 #define BURN_CDXA 0x20 00049 00050 #define BURN_POS_END 100 00051 00052 /** Mask for mode bits */ 00053 #define BURN_MODE_BITS 127 00054 00055 /** Track mode - mode 0 data 00056 0 bytes of user data. it's all 0s. mode 0. get it? HAH 00057 */ 00058 #define BURN_MODE0 (1 << 0) 00059 /** Track mode - mode "raw" - all 2352 bytes supplied by app 00060 FOR DATA TRACKS ONLY! 00061 */ 00062 #define BURN_MODE_RAW (1 << 1) 00063 /** Track mode - mode 1 data 00064 2048 bytes user data, and all the LEC money can buy 00065 */ 00066 #define BURN_MODE1 (1 << 2) 00067 /** Track mode - mode 2 data 00068 defaults to formless, 2336 bytes of user data, unprotected 00069 | with a data form if required. 00070 */ 00071 #define BURN_MODE2 (1 << 3) 00072 /** Track mode modifier - Form 1, | with MODE2 for reasonable results 00073 2048 bytes of user data, 4 bytes of subheader 00074 */ 00075 #define BURN_FORM1 (1 << 4) 00076 /** Track mode modifier - Form 2, | with MODE2 for reasonable results 00077 lots of user data. not much LEC. 00078 */ 00079 #define BURN_FORM2 (1 << 5) 00080 /** Track mode - audio 00081 2352 bytes per sector. may be | with 4ch or preemphasis. 00082 NOT TO BE CONFUSED WITH BURN_MODE_RAW 00083 Audio data must be 44100Hz 16bit stereo with no riff or other header at 00084 beginning. Extra header data will cause pops or clicks. Audio data should 00085 also be in little-endian byte order. Big-endian audio data causes static. 00086 */ 00087 #define BURN_AUDIO (1 << 6) 00088 /** Track mode modifier - 4 channel audio. */ 00089 #define BURN_4CH (1 << 7) 00090 /** Track mode modifier - Digital copy permitted, can be set on any track.*/ 00091 #define BURN_COPY (1 << 8) 00092 /** Track mode modifier - 50/15uS pre-emphasis */ 00093 #define BURN_PREEMPHASIS (1 << 9) 00094 /** Input mode modifier - subcodes present packed 16 */ 00095 #define BURN_SUBCODE_P16 (1 << 10) 00096 /** Input mode modifier - subcodes present packed 96 */ 00097 #define BURN_SUBCODE_P96 (1 << 11) 00098 /** Input mode modifier - subcodes present raw 96 */ 00099 #define BURN_SUBCODE_R96 (1 << 12) 00100 00101 /** Possible disc writing style/modes */ 00102 enum burn_write_types 00103 { 00104 /** Packet writing. 00105 currently unsupported 00106 */ 00107 BURN_WRITE_PACKET, 00108 /** Track At Once recording. 00109 2s gaps between tracks, no fonky lead-ins 00110 */ 00111 BURN_WRITE_TAO, 00112 /** Session At Once. 00113 block type MUST be BURN_BLOCK_SAO 00114 */ 00115 BURN_WRITE_SAO, 00116 /** Raw disc at once recording. 00117 all subcodes must be provided by lib or user 00118 only raw block types are supported 00119 */ 00120 BURN_WRITE_RAW 00121 }; 00122 00123 /** Data format to send to the drive */ 00124 enum burn_block_types 00125 { 00126 /** sync, headers, edc/ecc provided by lib/user */ 00127 BURN_BLOCK_RAW0 = 1, 00128 /** sync, headers, edc/ecc and p/q subs provided by lib/user */ 00129 BURN_BLOCK_RAW16 = 2, 00130 /** sync, headers, edc/ecc and packed p-w subs provided by lib/user */ 00131 BURN_BLOCK_RAW96P = 4, 00132 /** sync, headers, edc/ecc and raw p-w subs provided by lib/user */ 00133 BURN_BLOCK_RAW96R = 8, 00134 /** only 2048 bytes of user data provided by lib/user */ 00135 BURN_BLOCK_MODE1 = 256, 00136 /** 2336 bytes of user data provided by lib/user */ 00137 BURN_BLOCK_MODE2R = 512, 00138 /** 2048 bytes of user data provided by lib/user 00139 subheader provided in write parameters 00140 are we ever going to support this shit? I vote no. 00141 (supposed to be supported on all drives...) 00142 */ 00143 BURN_BLOCK_MODE2_PATHETIC = 1024, 00144 /** 2048 bytes of data + 8 byte subheader provided by lib/user 00145 hey, this is also dumb 00146 */ 00147 BURN_BLOCK_MODE2_LAME = 2048, 00148 /** 2324 bytes of data provided by lib/user 00149 subheader provided in write parameters 00150 no sir, I don't like it. 00151 */ 00152 BURN_BLOCK_MODE2_OBSCURE = 4096, 00153 /** 2332 bytes of data supplied by lib/user 00154 8 bytes sub header provided in write parameters 00155 this is the second least suck mode2, and is mandatory for 00156 all drives to support. 00157 */ 00158 BURN_BLOCK_MODE2_OK = 8192, 00159 /** SAO block sizes are based on cue sheet, so use this. */ 00160 BURN_BLOCK_SAO = 16384 00161 }; 00162 00163 /** Possible status' of the drive in regard to the disc in it. */ 00164 enum burn_disc_status 00165 { 00166 /** The current status is not yet known */ 00167 BURN_DISC_UNREADY, 00168 /** The drive holds a blank disc */ 00169 BURN_DISC_BLANK, 00170 /** There is no disc at all in the drive */ 00171 BURN_DISC_EMPTY, 00172 /** There is an incomplete disc in the drive */ 00173 BURN_DISC_APPENDABLE, 00174 /** There is a disc with data on it in the drive */ 00175 BURN_DISC_FULL 00176 }; 00177 00178 /** Possible types of messages form the library. */ 00179 enum burn_message_type 00180 { 00181 /** Diagnostic/Process information. For the curious user. */ 00182 BURN_MESSAGE_INFO, 00183 /** A warning regarding a possible problem. The user should probably 00184 be notified, but its not fatal. */ 00185 BURN_MESSAGE_WARNING, 00186 /** An error message. This usually means the current process will be 00187 aborted, and the user should definately see these. */ 00188 BURN_MESSAGE_ERROR 00189 }; 00190 00191 /** Possible information messages */ 00192 enum burn_message_info 00193 { 00194 BURN_INFO_FOO 00195 }; 00196 00197 /** Possible warning messages */ 00198 enum burn_message_warning 00199 { 00200 BURN_WARNING_FOO 00201 }; 00202 00203 /** Possible error messages */ 00204 enum burn_message_error 00205 { 00206 BURN_ERROR_CANCELLED 00207 }; 00208 00209 /** Possible data source return values */ 00210 enum burn_source_status 00211 { 00212 /** The source is ok */ 00213 BURN_SOURCE_OK, 00214 /** The source is at end of file */ 00215 BURN_SOURCE_EOF, 00216 /** The source is unusable */ 00217 BURN_SOURCE_FAILED 00218 }; 00219 00220 00221 /** Possible busy states for a drive */ 00222 enum burn_drive_status 00223 { 00224 /** The drive is not in an operation */ 00225 BURN_DRIVE_IDLE, 00226 /** The library is spawning the processes to handle a pending 00227 operation (A read/write/etc is about to start but hasn't quite 00228 yet) */ 00229 BURN_DRIVE_SPAWNING, 00230 /** The drive is reading data from a disc */ 00231 BURN_DRIVE_READING, 00232 /** The drive is writing data to a disc */ 00233 BURN_DRIVE_WRITING, 00234 /** The drive is writing Lead-In */ 00235 BURN_DRIVE_WRITING_LEADIN, 00236 /** The drive is writing Lead-Out */ 00237 BURN_DRIVE_WRITING_LEADOUT, 00238 /** The drive is erasing a disc */ 00239 BURN_DRIVE_ERASING, 00240 /** The drive is being grabbed */ 00241 BURN_DRIVE_GRABBING 00242 }; 00243 00244 /** Information about a track on a disc - this is from the q sub channel of the 00245 lead-in area of a disc. The documentation here is very terse. 00246 See a document such as mmc3 for proper information. 00247 */ 00248 struct burn_toc_entry 00249 { 00250 /** Session the track is in */ 00251 unsigned char session; 00252 /** Type of data. for this struct to be valid, it must be 1 */ 00253 unsigned char adr; 00254 /** Type of data in the track */ 00255 unsigned char control; 00256 /** Zero. Always. Really. */ 00257 unsigned char tno; 00258 /** Track number or special information */ 00259 unsigned char point; 00260 unsigned char min; 00261 unsigned char sec; 00262 unsigned char frame; 00263 unsigned char zero; 00264 /** Track start time minutes for normal tracks */ 00265 unsigned char pmin; 00266 /** Track start time seconds for normal tracks */ 00267 unsigned char psec; 00268 /** Track start time frames for normal tracks */ 00269 unsigned char pframe; 00270 }; 00271 00272 00273 /** Data source for tracks */ 00274 struct burn_source { 00275 /** Reference count for the data source. Should be 1 when a new source 00276 is created. Increment it to take a reference for yourself. Use 00277 burn_source_free to destroy your reference to it. */ 00278 int refcount; 00279 00280 /** Read data from the source */ 00281 int (*read)(struct burn_source *, 00282 unsigned char *buffer, 00283 int size); 00284 00285 /** Read subchannel data from the source (NULL if lib generated) */ 00286 int (*read_sub)(struct burn_source *, 00287 unsigned char *buffer, 00288 int size); 00289 00290 /** Get the size of the source's data */ 00291 off_t (*get_size)(struct burn_source *); 00292 00293 /** Clean up the source specific data */ 00294 void (*free_data)(struct burn_source *); 00295 00296 /** Next source, for when a source runs dry and padding is disabled 00297 THIS IS AUTOMATICALLY HANDLED, DO NOT TOUCH 00298 */ 00299 struct burn_source *next; 00300 00301 /** Source specific data */ 00302 void *data; 00303 }; 00304 00305 00306 /** Information on a drive in the system */ 00307 struct burn_drive_info 00308 { 00309 /** Name of the vendor of the drive */ 00310 char vendor[9]; 00311 /** Name of the drive */ 00312 char product[17]; 00313 /** Revision of the drive */ 00314 char revision[5]; 00315 /** Location of the drive in the filesystem. */ 00316 char location[17]; 00317 /** This is currently the string which is used as persistent 00318 drive address. But be warned: there is NO GUARANTEE that this 00319 will stay so. Always use function burn_drive_get_adr() to 00320 inquire a persisten address. ^^^^^^ ALWAYS ^^^^^^ */ 00321 00322 /** Can the drive read DVD-RAM discs */ 00323 unsigned int read_dvdram:1; 00324 /** Can the drive read DVD-R discs */ 00325 unsigned int read_dvdr:1; 00326 /** Can the drive read DVD-ROM discs */ 00327 unsigned int read_dvdrom:1; 00328 /** Can the drive read CD-R discs */ 00329 unsigned int read_cdr:1; 00330 /** Can the drive read CD-RW discs */ 00331 unsigned int read_cdrw:1; 00332 00333 /** Can the drive write DVD-RAM discs */ 00334 unsigned int write_dvdram:1; 00335 /** Can the drive write DVD-R discs */ 00336 unsigned int write_dvdr:1; 00337 /** Can the drive write CD-R discs */ 00338 unsigned int write_cdr:1; 00339 /** Can the drive write CD-RW discs */ 00340 unsigned int write_cdrw:1; 00341 00342 /** Can the drive simulate a write */ 00343 unsigned int write_simulate:1; 00344 00345 /** Can the drive report C2 errors */ 00346 unsigned int c2_errors:1; 00347 00348 /** The size of the drive's buffer (in kilobytes) */ 00349 int buffer_size; 00350 /** 00351 * The supported block types in tao mode. 00352 * They should be tested with the desired block type. 00353 * See also burn_block_types. 00354 */ 00355 int tao_block_types; 00356 /** 00357 * The supported block types in sao mode. 00358 * They should be tested with the desired block type. 00359 * See also burn_block_types. 00360 */ 00361 int sao_block_types; 00362 /** 00363 * The supported block types in raw mode. 00364 * They should be tested with the desired block type. 00365 * See also burn_block_types. 00366 */ 00367 int raw_block_types; 00368 /** 00369 * The supported block types in packet mode. 00370 * They should be tested with the desired block type. 00371 * See also burn_block_types. 00372 */ 00373 int packet_block_types; 00374 00375 /** The value by which this drive can be indexed when using functions 00376 in the library. This is the value to pass to all libbburn functions 00377 that operate on a drive. */ 00378 struct burn_drive *drive; 00379 }; 00380 00381 /** Messages from the library */ 00382 struct burn_message 00383 { 00384 /** The drive associated with the message. NULL if the error is not 00385 related to a specific drive. */ 00386 struct burn_drive *drive; 00387 00388 /** The type of message this is. See message_type for details. */ 00389 enum burn_message_type type; 00390 00391 /** The actual message */ 00392 union detail { 00393 struct { 00394 enum burn_message_info message; 00395 } info; 00396 struct { 00397 enum burn_message_warning message; 00398 } warning; 00399 struct { 00400 enum burn_message_error message; 00401 } error; 00402 } detail; 00403 }; 00404 00405 /** Operation progress report. All values are 0 based indices. 00406 * */ 00407 struct burn_progress { 00408 /** The total number of sessions */ 00409 int sessions; 00410 /** Current session.*/ 00411 int session; 00412 /** The total number of tracks */ 00413 int tracks; 00414 /** Current track. */ 00415 int track; 00416 /** The total number of indices */ 00417 int indices; 00418 /** Curent index. */ 00419 int index; 00420 /** The starting logical block address */ 00421 int start_sector; 00422 /** The number of sector */ 00423 int sectors; 00424 /** The current sector being processed */ 00425 int sector; 00426 }; 00427 00428 /** Initialize the library. 00429 This must be called before using any other functions in the library. It 00430 may be called more than once with no effect. 00431 It is possible to 'restart' the library by shutting it down and 00432 re-initializing it. This is necessary if you follow the older and 00433 more general way of accessing a drive via burn_drive_scan() and 00434 burn_drive_grab(). See burn_drive_scan_and_grab() with its strong 00435 urges and its explanations. 00436 @return Nonzero if the library was able to initialize; zero if 00437 initialization failed. 00438 */ 00439 int burn_initialize(void); 00440 00441 /** Shutdown the library. 00442 This should be called before exiting your application. Make sure that all 00443 drives you have grabbed are released <i>before</i> calling this. 00444 */ 00445 void burn_finish(void); 00446 00447 /** Set the verbosity level of the library. The default value is 0, which means 00448 that nothing is output on stderr. The more you increase this, the more 00449 debug output should be displayed on stderr for you. 00450 @param level The verbosity level desired. 0 for nothing, higher positive 00451 values for more information output. 00452 */ 00453 void burn_set_verbosity(int level); 00454 00455 /* ts A60813 */ 00456 /** Set parameters for behavior on opening device files. To be called early 00457 after burn_initialize() and before any bus scan. But not mandatory at all. 00458 Parameter value 1 enables a feature, 0 disables. 00459 Default is (1,0,0). Have a good reason before you change it. 00460 @param exclusive Try to open only devices which are not marked as busy 00461 and try to mark them busy if opened sucessfully. (O_EXCL) 00462 There are kernels which simply don't care about O_EXCL. 00463 Some have it off, some have it on, some are switchable. 00464 @param blocking Try to wait for drives which do not open immediately but 00465 also do not return an error as well. (O_NONBLOCK) 00466 This might stall indefinitely with /dev/hdX hard disks. 00467 @param abort_on_busy Unconditionally abort process when a non blocking 00468 exclusive opening attempt indicates a busy drive. 00469 Use this only after thorough tests with your app. 00470 */ 00471 void burn_preset_device_open(int exclusive, int blocking, int abort_on_busy); 00472 00473 /** Returns a newly allocated burn_message structure. This message should be 00474 freed with burn_message_free() when you are finished with it. 00475 @return A message or NULL when there are no more messages to retrieve. 00476 */ 00477 struct burn_message* burn_get_message(void); 00478 00479 /** Frees a burn_message structure */ 00480 void burn_message_free(struct burn_message *msg); 00481 00482 00483 /* ts A60823 */ 00484 /** Aquire a drive with known persistent address.This is the sysadmin friendly 00485 way to open one drive and to leave all others untouched. It bundles 00486 the following API calls to form a non-obtrusive way to use libburn: 00487 burn_drive_add_whitelist() , burn_drive_scan() , burn_drive_grab() 00488 You are *strongly urged* to use this call whenever you know the drive 00489 address in advance. 00490 If not, then you have to use directly above calls. In that case, you are 00491 *strongly urged* to drop any unintended drive which will be exclusively 00492 occupied and not closed by burn_drive_scan(). 00493 This can be done by shutting down the library including a call to 00494 burn_finish(). You may later start a new libburn session and should then 00495 use the function described here with an address obtained after 00496 burn_drive_scan() via burn_drive_get_adr(&(drive_infos[driveno]), adr) . 00497 Another way is to drop the unwanted drives by burn_drive_info_forget(). 00498 @param drive_infos On success returns a one element array with the drive 00499 (cdrom/burner). Thus use with driveno 0 only. On failure 00500 the array has no valid elements at all. 00501 The returned array should be freed via burn_drive_info_free() 00502 when it is no longer needed, and before calling a scan 00503 function again. 00504 This is a result from call burn_drive_scan(). See there. 00505 Use with driveno 0 only. 00506 @param adr The persistent address of the desired drive. Either obtained 00507 by burn_drive_get_adr() or guessed skillfully by application 00508 resp. its user. 00509 @param load Nonzero to make the drive attempt to load a disc (close its 00510 tray door, etc). 00511 @return 1 = success , 0 = drive not found , -1 = other error 00512 */ 00513 int burn_drive_scan_and_grab(struct burn_drive_info *drive_infos[], 00514 char* adr, int load); 00515 00516 00517 /* ts A51221 */ 00518 /** Maximum number of particularly permissible drive addresses */ 00519 #define BURN_DRIVE_WHITELIST_LEN 255 00520 /** Add a device to the list of permissible drives. As soon as some entry is in 00521 the whitelist all non-listed drives are banned from scanning. 00522 @return 1 success, <=0 failure 00523 */ 00524 int burn_drive_add_whitelist(char *device_address); 00525 00526 /** Remove all drives from whitelist. This enables all possible drives. */ 00527 void burn_drive_clear_whitelist(void); 00528 00529 00530 /** Scan for drives. This function MUST be called until it returns nonzero. 00531 No drives can be in use when this is called or it will assert. 00532 All drive pointers are invalidated by using this function. Do NOT store 00533 drive pointers across calls to this function or death AND pain will ensue. 00534 After this call all drives depicted by the returned array are subject 00535 to eventual (O_EXCL) locking. See burn_preset_device_open(). This state 00536 ends either with burn_drive_info_forget() or with burn_drive_release(). 00537 It is unfriendly to other processes on the system to hold drives locked 00538 which one does not definitely plan to use soon. 00539 @param drive_infos Returns an array of drive info items (cdroms/burners). 00540 The returned array must be freed by burn_drive_info_free() 00541 before burn_finish(), and also before calling this function 00542 burn_drive_scan() again. 00543 @param n_drives Returns the number of drive items in drive_infos. 00544 @return Zero while scanning is not complete; non-zero when it is finished. 00545 */ 00546 int burn_drive_scan(struct burn_drive_info *drive_infos[], 00547 unsigned int *n_drives); 00548 00549 /* ts A60904 : ticket 62, contribution by elmom */ 00550 /** Release memory about a single drive and any exclusive lock on it. 00551 Become unable to inquire or grab it. Expect FATAL consequences if you try. 00552 @param drive_info pointer to a single element out of the array 00553 obtained from burn_drive_scan() : &(drive_infos[driveno]) 00554 @param force controls degree of permissible drive usage at the moment this 00555 function is called, and the amount of automatically provided 00556 drive shutdown : 00557 0= drive must be ungrabbed and BURN_DRIVE_IDLE 00558 1= try to release drive resp. accept BURN_DRIVE_GRABBING 00559 Use these two only. Further values are to be defined. 00560 @return 1 on success, 2 if drive was already forgotten, 00561 0 if not permissible, <0 on other failures, 00562 */ 00563 int burn_drive_info_forget(struct burn_drive_info *drive_info, int force); 00564 00565 00566 /** Free a burn_drive_info array returned by burn_drive_scan 00567 */ 00568 void burn_drive_info_free(struct burn_drive_info drive_infos[]); 00569 00570 00571 /* ts A60823 */ 00572 /** Maximum length+1 to expect with a persistent drive address string */ 00573 #define BURN_DRIVE_ADR_LEN 1024 00574 00575 /** Inquire the persistent address of the given drive. 00576 @param drive_info The drive to inquire. Usually some &(drive_infos[driveno]) 00577 @param adr An application provided array of at least BURN_DRIVE_ADR_LEN 00578 characters size. The persistent address gets copied to it. 00579 */ 00580 int burn_drive_get_adr(struct burn_drive_info *drive_info, char adr[]); 00581 00582 00583 /** Grab a drive. This must be done before the drive can be used (for reading, 00584 writing, etc). 00585 @param drive The drive to grab. This is found in a returned 00586 burn_drive_info struct. 00587 @param load Nonzero to make the drive attempt to load a disc (close its 00588 tray door, etc). 00589 @return 1 if it was possible to grab the drive, else 0 00590 */ 00591 int burn_drive_grab(struct burn_drive *drive, int load); 00592 00593 00594 /** Release a drive. This should not be done until the drive is no longer 00595 busy (see burn_drive_get_status). The drive is (O_EXCL) unlocked 00596 afterwards. 00597 @param drive The drive to release. 00598 @param eject Nonzero to make the drive eject the disc in it. 00599 */ 00600 void burn_drive_release(struct burn_drive *drive, int eject); 00601 00602 00603 /** Returns what kind of disc a drive is holding. This function may need to be 00604 called more than once to get a proper status from it. See burn_status 00605 for details. 00606 @param drive The drive to query for a disc. 00607 @return The status of the drive, or what kind of disc is in it. 00608 */ 00609 enum burn_disc_status burn_disc_get_status(struct burn_drive *drive); 00610 00611 /** Tells whether a disc can be erased or not 00612 @return Non-zero means erasable 00613 */ 00614 int burn_disc_erasable(struct burn_drive *d); 00615 00616 /** Returns the progress and status of a drive. 00617 @param drive The drive to query busy state for. 00618 @param p Returns the progress of the operation, NULL if you don't care 00619 @return the current status of the drive. See also burn_drive_status. 00620 */ 00621 enum burn_drive_status burn_drive_get_status(struct burn_drive *drive, 00622 struct burn_progress *p); 00623 00624 /** Creates a write_opts struct for burning to the specified drive 00625 must be freed with burn_write_opts_free 00626 @param drive The drive to write with 00627 @return The write_opts 00628 */ 00629 struct burn_write_opts *burn_write_opts_new(struct burn_drive *drive); 00630 00631 /** Frees a write_opts struct created with burn_write_opts_new 00632 @param opts write_opts to free 00633 */ 00634 void burn_write_opts_free(struct burn_write_opts *opts); 00635 00636 /** Creates a write_opts struct for reading from the specified drive 00637 must be freed with burn_write_opts_free 00638 @param drive The drive to read from 00639 @return The read_opts 00640 */ 00641 struct burn_read_opts *burn_read_opts_new(struct burn_drive *drive); 00642 00643 /** Frees a read_opts struct created with burn_read_opts_new 00644 @param opts write_opts to free 00645 */ 00646 void burn_read_opts_free(struct burn_read_opts *opts); 00647 00648 /** Erase a disc in the drive. The drive must be grabbed successfully BEFORE 00649 calling this functions. Always ensure that the drive reports a status of 00650 BURN_DISC_FULL before calling this function. An erase operation is not 00651 cancellable, as control of the operation is passed wholly to the drive and 00652 there is no way to interrupt it safely. 00653 @param drive The drive with which to erase a disc. 00654 @param fast Nonzero to do a fast erase, where only the disc's headers are 00655 erased; zero to erase the entire disc. 00656 */ 00657 void burn_disc_erase(struct burn_drive *drive, int fast); 00658 00659 /** Read a disc from the drive and write it to an fd pair. The drive must be 00660 grabbed successfully BEFORE calling this function. Always ensure that the 00661 drive reports a status of BURN_DISC_FULL before calling this function. 00662 @param drive The drive from which to read a disc. 00663 @param o The options for the read operation. 00664 */ 00665 void burn_disc_read(struct burn_drive *drive, const struct burn_read_opts *o); 00666 00667 /** Write a disc in the drive. The drive must be grabbed successfully BEFORE 00668 calling this function. Always ensure that the drive reports a status of 00669 BURN_DISC_BLANK or BURN_STATUS_FULL (to append a new session to the 00670 disc) before calling this function. 00671 @param o The options for the writing operation. 00672 @param disc The struct burn_disc * that described the disc to be created 00673 */ 00674 void burn_disc_write(struct burn_write_opts *o, struct burn_disc *disc); 00675 00676 /** Cancel an operation on a drive. 00677 This will only work when the drive's busy state is BURN_DRIVE_READING or 00678 BURN_DRIVE_WRITING. 00679 @param drive The drive on which to cancel the current operation. 00680 */ 00681 void burn_drive_cancel(struct burn_drive *drive); 00682 00683 /** Convert a minute-second-frame (MSF) value to sector count 00684 @param m Minute component 00685 @param s Second component 00686 @param f Frame component 00687 @return The sector count 00688 */ 00689 int burn_msf_to_sectors(int m, int s, int f); 00690 00691 /** Convert a sector count to minute-second-frame (MSF) 00692 @param sectors The sector count 00693 @param m Returns the minute component 00694 @param s Returns the second component 00695 @param f Returns the frame component 00696 */ 00697 void burn_sectors_to_msf(int sectors, int *m, int *s, int *f); 00698 00699 /** Convert a minute-second-frame (MSF) value to an lba 00700 @param m Minute component 00701 @param s Second component 00702 @param f Frame component 00703 @return The lba 00704 */ 00705 int burn_msf_to_lba(int m, int s, int f); 00706 00707 /** Convert an lba to minute-second-frame (MSF) 00708 @param lba The lba 00709 @param m Returns the minute component 00710 @param s Returns the second component 00711 @param f Returns the frame component 00712 */ 00713 void burn_lba_to_msf(int lba, int *m, int *s, int *f); 00714 00715 /** Create a new disc (for DAO recording)*/ 00716 struct burn_disc *burn_disc_create(void); 00717 00718 /** Delete disc and decrease the reference count on all its sessions 00719 @param d The disc to be freed 00720 */ 00721 void burn_disc_free(struct burn_disc *d); 00722 00723 /** Create a new session (For SAO at once recording, or to be added to a 00724 disc for DAO) 00725 */ 00726 struct burn_session *burn_session_create(void); 00727 00728 /** Free a session (and decrease reference count on all tracks inside) 00729 @param s Session to be freed 00730 */ 00731 void burn_session_free(struct burn_session *s); 00732 00733 /** Add a session to a disc at a specific position, increasing the 00734 sessions's reference count. 00735 @param d Disc to add the session to 00736 @param s Session to add to the disc 00737 @param pos position to add at (BURN_POS_END is "at the end") 00738 @return 0 for failure, 1 for success 00739 */ 00740 int burn_disc_add_session(struct burn_disc *d, struct burn_session *s, 00741 unsigned int pos); 00742 00743 /** Remove a session from a disc 00744 @param d Disc to remove session from 00745 @param s Session pointer to find and remove 00746 */ 00747 int burn_disc_remove_session(struct burn_disc *d, struct burn_session *s); 00748 00749 00750 /** Create a track (for TAO recording, or to put in a session) */ 00751 struct burn_track *burn_track_create(void); 00752 00753 /** Free a track 00754 @param t Track to free 00755 */ 00756 void burn_track_free(struct burn_track *t); 00757 00758 /** Add a track to a session at specified position 00759 @param s Session to add to 00760 @param t Track to insert in session 00761 @param pos position to add at (BURN_POS_END is "at the end") 00762 @return 0 for failure, 1 for success 00763 */ 00764 int burn_session_add_track(struct burn_session *s, struct burn_track *t, 00765 unsigned int pos); 00766 00767 /** Remove a track from a session 00768 @param s Session to remove track from 00769 @param t Track pointer to find and remove 00770 @return 0 for failure, 1 for success 00771 */ 00772 int burn_session_remove_track(struct burn_session *s, struct burn_track *t); 00773 00774 00775 /** Define the data in a track 00776 @param t the track to define 00777 @param offset The lib will write this many 0s before start of data 00778 @param tail The number of extra 0s to write after data 00779 @param pad 1 means the lib should pad the last sector with 0s if the 00780 track isn't exactly sector sized. (otherwise the lib will 00781 begin reading from the next track) 00782 @param mode data format (bitfield) 00783 */ 00784 void burn_track_define_data(struct burn_track *t, int offset, int tail, 00785 int pad, int mode); 00786 00787 /** Set the ISRC details for a track 00788 @param t The track to change 00789 @param country the 2 char country code. Each character must be 00790 only numbers or letters. 00791 @param owner 3 char owner code. Each character must be only numbers 00792 or letters. 00793 @param year 2 digit year. A number in 0-99 (Yep, not Y2K friendly). 00794 @param serial 5 digit serial number. A number in 0-99999. 00795 */ 00796 void burn_track_set_isrc(struct burn_track *t, char *country, char *owner, 00797 unsigned char year, unsigned int serial); 00798 00799 /** Disable ISRC parameters for a track 00800 @param t The track to change 00801 */ 00802 void burn_track_clear_isrc(struct burn_track *t); 00803 00804 /** Hide the first track in the "pre gap" of the disc 00805 @param s session to change 00806 @param onoff 1 to enable hiding, 0 to disable 00807 */ 00808 void burn_session_hide_first_track(struct burn_session *s, int onoff); 00809 00810 /** Get the drive's disc struct - free when done 00811 @param d drive to query 00812 @return the disc struct 00813 */ 00814 struct burn_disc *burn_drive_get_disc(struct burn_drive *d); 00815 00816 /** Set the track's data source 00817 @param t The track to set the data source for 00818 @param s The data source to use for the contents of the track 00819 @return An error code stating if the source is ready for use for 00820 writing the track, or if an error occured 00821 00822 */ 00823 enum burn_source_status burn_track_set_source(struct burn_track *t, 00824 struct burn_source *s); 00825 00826 /** Free a burn_source (decrease its refcount and maybe free it) 00827 @param s Source to free 00828 */ 00829 void burn_source_free(struct burn_source *s); 00830 00831 /** Creates a data source for an image file (and maybe subcode file) */ 00832 struct burn_source *burn_file_source_new(const char *path, 00833 const char *subpath); 00834 00835 /** Creates a data source for an image file (a track) from an open 00836 readable filedescriptor, an eventually open readable subcodes file 00837 descriptor and eventually a fixed size in bytes. 00838 @param datafd The source of data. 00839 @param subfd The eventual source for subcodes. Not used if -1. 00840 @param size The eventual fixed size of eventually both fds. 00841 If this value is 0, the size will be determined from datafd. 00842 */ 00843 struct burn_source *burn_fd_source_new(int datafd, int subfd, off_t size); 00844 00845 /** Tells how long a track will be on disc */ 00846 int burn_track_get_sectors(struct burn_track *); 00847 00848 00849 /** Sets drive read and write speed 00850 @param d The drive to set speed for 00851 @param read Read speed in k/s (0 is max) 00852 @param write Write speed in k/s (0 is max) 00853 */ 00854 void burn_drive_set_speed(struct burn_drive *d, int read, int write); 00855 00856 /* these are for my debugging, they will disappear */ 00857 void burn_structure_print_disc(struct burn_disc *d); 00858 void burn_structure_print_session(struct burn_session *s); 00859 void burn_structure_print_track(struct burn_track *t); 00860 00861 /** Sets the write type for the write_opts struct 00862 @param opts The write opts to change 00863 @param write_type The write type to use 00864 @param block_type The block type to use 00865 @return Returns 1 on success and 0 on failure. 00866 */ 00867 int burn_write_opts_set_write_type(struct burn_write_opts *opts, 00868 enum burn_write_types write_type, 00869 int block_type); 00870 00871 /** Supplies toc entries for writing - not normally required for cd mastering 00872 @param opts The write opts to change 00873 @param count The number of entries 00874 @param toc_entries 00875 */ 00876 void burn_write_opts_set_toc_entries(struct burn_write_opts *opts, 00877 int count, 00878 struct burn_toc_entry *toc_entries); 00879 00880 /** Sets the session format for a disc 00881 @param opts The write opts to change 00882 @param format The session format to set 00883 */ 00884 void burn_write_opts_set_format(struct burn_write_opts *opts, int format); 00885 00886 /** Sets the simulate value for the write_opts struct 00887 @param opts The write opts to change 00888 @param sim If non-zero, the drive will perform a simulation instead of a burn 00889 @return Returns 1 on success and 0 on failure. 00890 */ 00891 int burn_write_opts_set_simulate(struct burn_write_opts *opts, int sim); 00892 00893 /** Controls buffer underrun prevention 00894 @param opts The write opts to change 00895 @param underrun_proof if non-zero, buffer underrun protection is enabled 00896 @return Returns 1 on success and 0 on failure. 00897 */ 00898 int burn_write_opts_set_underrun_proof(struct burn_write_opts *opts, 00899 int underrun_proof); 00900 00901 /** Sets whether to use opc or not with the write_opts struct 00902 @param opts The write opts to change 00903 @param opc If non-zero, optical power calibration will be performed at 00904 start of burn 00905 00906 */ 00907 void burn_write_opts_set_perform_opc(struct burn_write_opts *opts, int opc); 00908 00909 void burn_write_opts_set_has_mediacatalog(struct burn_write_opts *opts, int has_mediacatalog); 00910 00911 void burn_write_opts_set_mediacatalog(struct burn_write_opts *opts, unsigned char mediacatalog[13]); 00912 00913 /** Sets whether to read in raw mode or not 00914 @param opts The read opts to change 00915 @param raw_mode If non-zero, reading will be done in raw mode, so that everything in the data tracks on the 00916 disc is read, including headers. 00917 */ 00918 void burn_read_opts_set_raw(struct burn_read_opts *opts, int raw_mode); 00919 00920 /** Sets whether to report c2 errors or not 00921 @param opts The read opts to change 00922 @param c2errors If non-zero, report c2 errors. 00923 */ 00924 void burn_read_opts_set_c2errors(struct burn_read_opts *opts, int c2errors); 00925 00926 /** Sets whether to read subcodes from audio tracks or not 00927 @param opts The read opts to change 00928 @param subcodes_audio If non-zero, read subcodes from audio tracks on the disc. 00929 */ 00930 void burn_read_opts_read_subcodes_audio(struct burn_read_opts *opts, 00931 int subcodes_audio); 00932 00933 /** Sets whether to read subcodes from data tracks or not 00934 @param opts The read opts to change 00935 @param subcodes_data If non-zero, read subcodes from data tracks on the disc. 00936 */ 00937 void burn_read_opts_read_subcodes_data(struct burn_read_opts *opts, 00938 int subcodes_data); 00939 00940 /** Sets whether to recover errors if possible 00941 @param opts The read opts to change 00942 @param hardware_error_recovery If non-zero, attempt to recover errors if possible. 00943 */ 00944 void burn_read_opts_set_hardware_error_recovery(struct burn_read_opts *opts, 00945 int hardware_error_recovery); 00946 00947 /** Sets whether to report recovered errors or not 00948 @param opts The read opts to change 00949 @param report_recovered_errors If non-zero, recovered errors will be reported. 00950 */ 00951 void burn_read_opts_report_recovered_errors(struct burn_read_opts *opts, 00952 int report_recovered_errors); 00953 00954 /** Sets whether blocks with unrecoverable errors should be read or not 00955 @param opts The read opts to change 00956 @param transfer_damaged_blocks If non-zero, blocks with unrecoverable errors will still be read. 00957 */ 00958 void burn_read_opts_transfer_damaged_blocks(struct burn_read_opts *opts, 00959 int transfer_damaged_blocks); 00960 00961 /** Sets the number of retries to attempt when trying to correct an error 00962 @param opts The read opts to change 00963 @param hardware_error_retries The number of retries to attempt when correcting an error. 00964 */ 00965 void burn_read_opts_set_hardware_error_retries(struct burn_read_opts *opts, 00966 unsigned char hardware_error_retries); 00967 00968 /** Gets the maximum write speed for a drive 00969 @param d Drive to query 00970 @return Maximum write speed in K/s 00971 */ 00972 int burn_drive_get_write_speed(struct burn_drive *d); 00973 00974 /** Gets the maximum read speed for a drive 00975 @param d Drive to query 00976 @return Maximum read speed in K/s 00977 */ 00978 int burn_drive_get_read_speed(struct burn_drive *d); 00979 00980 /** Gets a copy of the toc_entry structure associated with a track 00981 @param t Track to get the entry from 00982 @param entry Struct for the library to fill out 00983 */ 00984 void burn_track_get_entry(struct burn_track *t, struct burn_toc_entry *entry); 00985 00986 /** Gets a copy of the toc_entry structure associated with a session's lead out 00987 @param s Session to get the entry from 00988 @param entry Struct for the library to fill out 00989 */ 00990 void burn_session_get_leadout_entry(struct burn_session *s, 00991 struct burn_toc_entry *entry); 00992 00993 /** Gets an array of all the sessions for the disc 00994 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A SESSION 00995 @param d Disc to get session array for 00996 @param num Returns the number of sessions in the array 00997 @return array of sessions 00998 */ 00999 struct burn_session **burn_disc_get_sessions(struct burn_disc *d, 01000 int *num); 01001 01002 int burn_disc_get_sectors(struct burn_disc *d); 01003 01004 /** Gets an array of all the tracks for a session 01005 THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A TRACK 01006 @param s session to get track array for 01007 @param num Returns the number of tracks in the array 01008 @return array of tracks 01009 */ 01010 struct burn_track **burn_session_get_tracks(struct burn_session *s, 01011 int *num); 01012 01013 int burn_session_get_sectors(struct burn_session *s); 01014 01015 /** Gets the mode of a track 01016 @param track the track to query 01017 @return the track's mode 01018 */ 01019 int burn_track_get_mode(struct burn_track *track); 01020 01021 /** Returns whether the first track of a session is hidden in the pregap 01022 @param session the session to query 01023 @return non-zero means the first track is hidden 01024 */ 01025 int burn_session_get_hidefirst(struct burn_session *session); 01026 01027 /** Returns the library's version in its parts 01028 @param major The major version number 01029 @param minor The minor version number 01030 @param micro The micro version number 01031 */ 01032 void burn_version(int *major, int *minor, int *micro); 01033 01034 #ifndef DOXYGEN 01035 01036 BURN_END_DECLS 01037 01038 #endif 01039 01040 #endif /*LIBBURN_H*/