libburn-0.2.2/libburn/libburn.h

Go to the documentation of this file.
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*/

Generated on Mon Oct 23 18:08:57 2006 for libburn by  doxygen 1.4.6