Main Page | Data Structures | Directories | File List | Data Fields | Globals

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 #include <stdint.h>
00007 
00008 #ifndef DOXYGEN
00009 
00010 #if defined(__cplusplus)
00011 #define BURN_BEGIN_DECLS \
00012     namespace burn { \
00013         extern "C" {
00014 #define BURN_END_DECLS \
00015         } \
00016     }
00017 #else
00018 #define BURN_BEGIN_DECLS
00019 #define BURN_END_DECLS
00020 #endif
00021 
00022 BURN_BEGIN_DECLS
00023 
00024 #endif
00025 
00026 /** References a physical drive in the system */
00027 struct burn_drive;
00028 
00029 /** References a whole disc */
00030 struct burn_disc;
00031 
00032 /** References a single session on a disc */
00033 struct burn_session;
00034 
00035 /** References a single track on a disc */
00036 struct burn_track;
00037 
00038 /** Session format for normal audio or data discs */
00039 #define BURN_CDROM  0
00040 /** Session format for obsolete CD-I discs */
00041 #define BURN_CDI    0x10
00042 /** Session format for CDROM-XA discs */
00043 #define BURN_CDXA   0x20
00044 
00045 #define BURN_POS_END 100
00046 
00047 /** Mask for mode bits */
00048 #define BURN_MODE_BITS 127
00049 
00050 /** Track mode - mode 0 data
00051     0 bytes of user data.  it's all 0s.  mode 0.  get it?  HAH
00052 */
00053 #define BURN_MODE0      (1 << 0)
00054 /** Track mode - mode "raw" - all 2352 bytes supplied by app
00055     FOR DATA TRACKS ONLY!
00056 */
00057 #define BURN_MODE_RAW       (1 << 1)
00058 /** Track mode - mode 1 data
00059     2048 bytes user data, and all the LEC money can buy
00060 */
00061 #define BURN_MODE1      (1 << 2)
00062 /** Track mode - mode 2 data
00063     defaults to formless, 2336 bytes of user data, unprotected
00064     | with a data form if required.
00065 */
00066 #define BURN_MODE2      (1 << 3)
00067 /** Track mode modifier - Form 1, | with MODE2 for reasonable results
00068     2048 bytes of user data, 4 bytes of subheader
00069 */
00070 #define BURN_FORM1      (1 << 4)
00071 /** Track mode modifier - Form 2, | with MODE2 for reasonable results
00072     lots of user data.  not much LEC.
00073 */
00074 #define BURN_FORM2      (1 << 5)
00075 /** Track mode - audio
00076     2352 bytes per sector.  may be | with 4ch or preemphasis.
00077     NOT TO BE CONFUSED WITH BURN_MODE_RAW
00078 */
00079 #define BURN_AUDIO      (1 << 6)
00080 /** Track mode modifier - 4 channel audio. */
00081 #define BURN_4CH        (1 << 7)
00082 /** Track mode modifier - Digital copy permitted, can be set on any track.*/
00083 #define BURN_COPY       (1 << 8)
00084 /** Track mode modifier - 50/15uS pre-emphasis */
00085 #define BURN_PREEMPHASIS    (1 << 9)
00086 /** Input mode modifier - subcodes present packed 16 */
00087 #define BURN_SUBCODE_P16    (1 << 10)
00088 /** Input mode modifier - subcodes present packed 96 */
00089 #define BURN_SUBCODE_P96    (1 << 11)
00090 /** Input mode modifier - subcodes present raw 96 */
00091 #define BURN_SUBCODE_R96    (1 << 12)
00092 
00093 /** Possible disc writing style/modes */
00094 enum burn_write_types
00095 {
00096     /** Packet writing.
00097         currently unsupported
00098     */
00099     BURN_WRITE_PACKET,
00100     /** Track At Once recording.
00101         2s gaps between tracks, no fonky lead-ins
00102     */
00103     BURN_WRITE_TAO,
00104     /** Session At Once.
00105         block type MUST be BURN_BLOCK_SAO
00106     */
00107     BURN_WRITE_SAO,
00108     /** Raw disc at once recording.
00109         all subcodes must be provided by lib or user
00110         only raw block types are supported
00111     */
00112     BURN_WRITE_RAW
00113 };
00114 
00115 /** Data format to send to the drive */
00116 enum burn_block_types
00117 {
00118     /** sync, headers, edc/ecc provided by lib/user */
00119     BURN_BLOCK_RAW0 = 1,
00120     /** sync, headers, edc/ecc and p/q subs provided by lib/user */
00121     BURN_BLOCK_RAW16 = 2,
00122     /** sync, headers, edc/ecc and packed p-w subs provided by lib/user */
00123     BURN_BLOCK_RAW96P = 4,
00124     /** sync, headers, edc/ecc and raw p-w subs provided by lib/user */
00125     BURN_BLOCK_RAW96R = 8,
00126     /** only 2048 bytes of user data provided by lib/user */
00127     BURN_BLOCK_MODE1 = 256,
00128     /** 2336 bytes of user data provided by lib/user */
00129     BURN_BLOCK_MODE2R = 512,
00130     /** 2048 bytes of user data provided by lib/user
00131         subheader provided in write parameters
00132         are we ever going to support this shit?  I vote no.
00133         (supposed to be supported on all drives...)
00134     */
00135     BURN_BLOCK_MODE2_PATHETIC = 1024,
00136     /** 2048 bytes of data + 8 byte subheader provided by lib/user
00137         hey, this is also dumb
00138     */
00139     BURN_BLOCK_MODE2_LAME = 2048,
00140     /** 2324 bytes of data provided by lib/user
00141         subheader provided in write parameters
00142         no sir, I don't like it.
00143     */
00144     BURN_BLOCK_MODE2_OBSCURE = 4096,
00145     /** 2332 bytes of data supplied by lib/user
00146         8 bytes sub header provided in write parameters
00147         this is the second least suck mode2, and is mandatory for
00148         all drives to support.
00149     */
00150     BURN_BLOCK_MODE2_OK = 8192,
00151     /** SAO block sizes are based on cue sheet, so use this. */
00152     BURN_BLOCK_SAO = 16384
00153 };
00154 
00155 /** Possible status' of the drive in regard to the disc in it. */
00156 enum burn_disc_status
00157 {
00158     /** The current status is not yet known */
00159     BURN_DISC_UNREADY,
00160     /** The drive holds a blank disc */
00161     BURN_DISC_BLANK,
00162     /** There is no disc at all in the drive */
00163     BURN_DISC_EMPTY,
00164     /** There is an incomplete disc in the drive */
00165     BURN_DISC_APPENDABLE,
00166     /** There is a disc with data on it in the drive */
00167     BURN_DISC_FULL
00168 };
00169 
00170 /** Possible types of messages form the library. */
00171 enum burn_message_type
00172 {
00173     /** Diagnostic/Process information. For the curious user. */
00174     BURN_MESSAGE_INFO,
00175     /** A warning regarding a possible problem. The user should probably
00176         be notified, but its not fatal. */
00177     BURN_MESSAGE_WARNING,
00178     /** An error message. This usually means the current process will be
00179         aborted, and the user should definately see these. */
00180     BURN_MESSAGE_ERROR
00181 };
00182 
00183 /** Possible information messages */
00184 enum burn_message_info
00185 {
00186     BURN_INFO_FOO
00187 };
00188 
00189 /** Possible warning messages */
00190 enum burn_message_warning
00191 {
00192     BURN_WARNING_FOO
00193 };
00194 
00195 /** Possible error messages */
00196 enum burn_message_error
00197 {
00198     BURN_ERROR_CANCELLED
00199 };
00200 
00201 /** Possible data source return values */
00202 enum burn_source_status
00203 {
00204     /** The source is ok */
00205     BURN_SOURCE_OK,
00206     /** The source is at end of file */
00207     BURN_SOURCE_EOF,
00208     /** The source is unusable */
00209     BURN_SOURCE_FAILED
00210 };
00211 
00212 
00213 /** Possible busy states for a drive */
00214 enum burn_drive_status
00215 {
00216     /** The drive is not in an operation */
00217     BURN_DRIVE_IDLE,
00218     /** The library is spawning the processes to handle a pending
00219         operation (A read/write/etc is about to start but hasn't quite
00220         yet) */
00221     BURN_DRIVE_SPAWNING,
00222     /** The drive is reading data from a disc */
00223     BURN_DRIVE_READING,
00224     /** The drive is writing data to a disc */
00225     BURN_DRIVE_WRITING,
00226     /** The drive is writing Lead-In */
00227     BURN_DRIVE_WRITING_LEADIN,
00228     /** The drive is writing Lead-Out */
00229     BURN_DRIVE_WRITING_LEADOUT,
00230     /** The drive is erasing a disc */
00231     BURN_DRIVE_ERASING,
00232     /** The drive is being grabbed */
00233     BURN_DRIVE_GRABBING
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     int (*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 
00310     /** Can the drive read DVD-RAM discs */
00311     unsigned int read_dvdram:1;
00312     /** Can the drive read DVD-R discs */
00313     unsigned int read_dvdr:1;
00314     /** Can the drive read DVD-ROM discs */
00315     unsigned int read_dvdrom:1;
00316     /** Can the drive read CD-R discs */
00317     unsigned int read_cdr:1;
00318     /** Can the drive read CD-RW discs */
00319     unsigned int read_cdrw:1;
00320 
00321     /** Can the drive write DVD-RAM discs */
00322     unsigned int write_dvdram:1;
00323     /** Can the drive write DVD-R discs */
00324     unsigned int write_dvdr:1;
00325     /** Can the drive write CD-R discs */
00326     unsigned int write_cdr:1;
00327     /** Can the drive write CD-RW discs */
00328     unsigned int write_cdrw:1;
00329 
00330     /** Can the drive simulate a write */
00331     unsigned int write_simulate:1;
00332 
00333     /** Can the drive report C2 errors */
00334     unsigned int c2_errors:1;
00335 
00336     /** The size of the drive's buffer (in kilobytes) */
00337     int buffer_size;
00338     /** 
00339      * The supported block types in tao mode.
00340      * They should be tested with the desired block type.
00341      * See also burn_block_types.
00342      */
00343     int tao_block_types;
00344     /** 
00345      * The supported block types in sao mode.
00346      * They should be tested with the desired block type.
00347      * See also burn_block_types.
00348      */
00349     int sao_block_types;
00350     /** 
00351      * The supported block types in raw mode.
00352      * They should be tested with the desired block type.
00353      * See also burn_block_types.
00354      */
00355     int raw_block_types;
00356     /** 
00357      * The supported block types in packet mode.
00358      * They should be tested with the desired block type.
00359      * See also burn_block_types.
00360      */
00361     int packet_block_types;
00362 
00363     /** The value by which this drive can be indexed when using functions
00364         in the library. This is the value to pass to all libbburn functions
00365         that operate on a drive. */
00366     struct burn_drive *drive;
00367 };
00368 
00369 /** Messages from the library */
00370 struct burn_message
00371 {
00372     /** The drive associated with the message. NULL if the error is not
00373         related to a specific drive. */
00374     struct burn_drive *drive;
00375 
00376     /** The type of message this is. See message_type for details. */
00377     enum burn_message_type type;
00378 
00379     /** The actual message */
00380     union detail {
00381         struct {
00382             enum burn_message_info    message;
00383         } info;
00384         struct {
00385             enum burn_message_warning message;
00386         } warning;
00387         struct {
00388             enum burn_message_error   message;
00389         } error;
00390     } detail;
00391 };
00392 
00393 /** Operation progress report. All values are 0 based indices. 
00394  * */
00395 struct burn_progress {
00396     /** The total number of sessions */
00397     int sessions;
00398     /** Current session.*/
00399     int session;
00400     /** The total number of tracks */
00401     int tracks;
00402     /** Current track. */
00403     int track;
00404     /** The total number of indices */
00405     int indices;
00406     /** Curent index. */
00407     int index;
00408     /** The starting logical block address */
00409     int start_sector;
00410     /** The number of sector */
00411     int sectors;
00412     /** The current sector being processed */
00413     int sector;
00414 };
00415 
00416 /** Initialize the library.
00417     This must be called before using any other functions in the library. It
00418     may be called more than once with no effect.
00419     If is possible to 'restart' the library by shutting it down and
00420     re-initializing it, though there is no good reason to do that.
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 /** Set the verbosity level of the library. The default value is 0, which means
00433     that nothing is output on stderr. The more you increase this, the more
00434     debug output should be displayed on stderr for you.
00435     @param level The verbosity level desired. 0 for nothing, higher positive
00436                  values for more information output.
00437 */
00438 void burn_set_verbosity(int level);
00439 
00440 /** Returns a newly allocated burn_message structure. This message should be
00441     freed with burn_message_free() when you are finished with it.
00442     @return A message or NULL when there are no more messages to retrieve.
00443 */
00444 struct burn_message* burn_get_message(void);
00445 
00446 /** Frees a burn_message structure */
00447 void burn_message_free(struct burn_message *msg);
00448 
00449 /** Scans for drives. This function MUST be called until it returns nonzero.
00450     No drives can be in use when this is called or it will assert.
00451     All drive pointers are invalidated by using this function. Do NOT store
00452     drive pointers across calls to this function or death AND pain will ensue.
00453     When the app is done with the burn_drive_info array, it must be freed with
00454     burn_drive_info_free()
00455     @param drives Returns an array of drives (cdroms/burners). The returned
00456                   array should be freed when it is no longer needed, and
00457                   before calling this function again to rescan.
00458     @param n_drives Returns the number of hardware drives in @c drives.
00459     @return Zero while scanning is not complete; non-zero when it is finished.
00460 */
00461 int burn_drive_scan(struct burn_drive_info *drives[],
00462             unsigned int *n_drives);
00463 /** Frees a burn_drive_info array returned by burn_drive_scan
00464     @param info The array to free
00465 */
00466 void burn_drive_info_free(struct burn_drive_info *info);
00467 
00468 /** Grab a drive. This must be done before the drive can be used (for reading,
00469     writing, etc). It may be neccesary to call this function more than once
00470     to grab a drive. See burn_grab for details.
00471     @param drive The drive to grab. This is found in a returned
00472                  burn_drive_info struct.
00473     @param load Nonzero to make the drive attempt to load a disc (close its
00474                 tray door, etc).
00475     @return 1 if the drive has been grabbed, else 0
00476 */
00477 int burn_drive_grab(struct burn_drive *drive, int load);
00478 
00479 /** Release a drive. This should not be done until the drive is no longer
00480     busy (see burn_drive_get_status).
00481     @param drive The drive to release.
00482     @param eject Nonzero to make the drive eject the disc in it.
00483 */
00484 void burn_drive_release(struct burn_drive *drive, int eject);
00485 
00486 /** Returns what kind of disc a drive is holding. This function may need to be
00487     called more than once to get a proper status from it. See burn_status
00488     for details.
00489     @param drive The drive to query for a disc.
00490     @return The status of the drive, or what kind of disc is in it.
00491 */
00492 enum burn_disc_status burn_disc_get_status(struct burn_drive *drive);
00493 
00494 /** Tells whether a disc can be erased or not
00495     @return Non-zero means erasable
00496 */
00497 int burn_disc_erasable(struct burn_drive *d);
00498 
00499 /** Returns the progress and status of a drive.
00500     @param drive The drive to query busy state for.
00501     @param p Returns the progress of the operation, NULL if you don't care
00502     @return the current status of the drive. See also burn_drive_status.
00503 */
00504 enum burn_drive_status burn_drive_get_status(struct burn_drive *drive,
00505                          struct burn_progress *p);
00506 
00507 /** Creates a write_opts struct for burning to the specified drive
00508     must be freed with burn_write_opts_free
00509     @param drive The drive to write with
00510     @return The write_opts
00511 */
00512 struct burn_write_opts *burn_write_opts_new(struct burn_drive *drive);
00513 
00514 /** Frees a write_opts struct created with burn_write_opts_new
00515     @param opts write_opts to free
00516 */
00517 void burn_write_opts_free(struct burn_write_opts *opts);
00518 
00519 /** Creates a write_opts struct for reading from the specified drive
00520     must be freed with burn_write_opts_free
00521     @param drive The drive to read from
00522     @return The read_opts
00523 */
00524 struct burn_read_opts *burn_read_opts_new(struct burn_drive *drive);
00525 
00526 /** Frees a read_opts struct created with burn_read_opts_new
00527     @param opts write_opts to free
00528 */
00529 void burn_read_opts_free(struct burn_read_opts *opts);
00530 
00531 /** Erase a disc in the drive. The drive must be grabbed successfully BEFORE
00532     calling this functions. Always ensure that the drive reports a status of
00533     BURN_DISC_FULL before calling this function. An erase operation is not
00534     cancellable, as control of the operation is passed wholly to the drive and
00535     there is no way to interrupt it safely.
00536     @param drive The drive with which to erase a disc.
00537     @param fast Nonzero to do a fast erase, where only the disc's headers are
00538                 erased; zero to erase the entire disc.
00539 */
00540 void burn_disc_erase(struct burn_drive *drive, int fast);
00541 
00542 /** Read a disc from the drive and write it to an fd pair. The drive must be
00543     grabbed successfully BEFORE calling this function. Always ensure that the
00544     drive reports a status of BURN_DISC_FULL before calling this function.
00545     @param drive The drive from which to read a disc.
00546     @param o The options for the read operation.
00547 */
00548 void burn_disc_read(struct burn_drive *drive, const struct burn_read_opts *o);
00549 
00550 /** Write a disc in the drive. The drive must be grabbed successfully BEFORE
00551     calling this function. Always ensure that the drive reports a status of
00552     BURN_DISC_BLANK or BURN_STATUS_FULL (to append a new session to the
00553     disc) before calling this function.
00554     @param o The options for the writing operation.
00555     @param disc The struct burn_disc * that described the disc to be created
00556 */
00557 void burn_disc_write(struct burn_write_opts *o, struct burn_disc *disc);
00558 
00559 /** Cancel an operation on a drive.
00560     This will only work when the drive's busy state is BURN_DRIVE_READING or
00561     BURN_DRIVE_WRITING.
00562     @param drive The drive on which to cancel the current operation.
00563 */
00564 void burn_drive_cancel(struct burn_drive *drive);
00565 
00566 /** Convert a minute-second-frame (MSF) value to sector count
00567     @param m Minute component
00568     @param s Second component
00569     @param f Frame component
00570     @return The sector count
00571 */
00572 int burn_msf_to_sectors(int m, int s, int f);
00573 
00574 /** Convert a sector count to minute-second-frame (MSF)
00575     @param sectors The sector count
00576     @param m Returns the minute component
00577     @param s Returns the second component
00578     @param f Returns the frame component
00579 */
00580 void burn_sectors_to_msf(int sectors, int *m, int *s, int *f);
00581 
00582 /** Convert a minute-second-frame (MSF) value to an lba
00583     @param m Minute component
00584     @param s Second component
00585     @param f Frame component
00586     @return The lba
00587 */
00588 int burn_msf_to_lba(int m, int s, int f);
00589 
00590 /** Convert an lba to minute-second-frame (MSF)
00591     @param lba The lba
00592     @param m Returns the minute component
00593     @param s Returns the second component
00594     @param f Returns the frame component
00595 */
00596 void burn_lba_to_msf(int lba, int *m, int *s, int *f);
00597 
00598 /** Create a new disc (for DAO recording)*/
00599 struct burn_disc *burn_disc_create(void);
00600 
00601 /** Delete disc and decrease the reference count on all its sessions
00602     @param d The disc to be freed
00603 */
00604 void burn_disc_free(struct burn_disc *d);
00605 
00606 /** Create a new session (For SAO at once recording, or to be added to a 
00607     disc for DAO)
00608 */
00609 struct burn_session *burn_session_create(void);
00610 
00611 /** Free a session (and decrease reference count on all tracks inside)
00612     @param s Session to be freed
00613 */
00614 void burn_session_free(struct burn_session *s);
00615 
00616 /** Add a session to a disc at a specific position, increasing the 
00617     sessions's reference count.
00618     @param d Disc to add the session to
00619     @param s Session to add to the disc
00620     @param pos position to add at (BURN_POS_END is "at the end")
00621     @return 0 for failure, 1 for success
00622 */
00623 int burn_disc_add_session(struct burn_disc *d, struct burn_session *s,
00624               unsigned int pos);
00625 
00626 /** Remove a session from a disc
00627     @param d Disc to remove session from
00628     @param s Session pointer to find and remove
00629 */
00630 int burn_disc_remove_session(struct burn_disc *d, struct burn_session *s);
00631 
00632 
00633 /** Create a track (for TAO recording, or to put in a session) */
00634 struct burn_track *burn_track_create(void);
00635 
00636 /** Free a track
00637     @param t Track to free
00638 */
00639 void burn_track_free(struct burn_track *t);
00640 
00641 /** Add a track to a session at specified position
00642     @param s Session to add to
00643     @param t Track to insert in session
00644     @param pos position to add at (BURN_POS_END is "at the end")
00645     @return 0 for failure, 1 for success
00646 */
00647 int burn_session_add_track(struct burn_session *s, struct burn_track *t,
00648                unsigned int pos);
00649 
00650 /** Remove a track from a session
00651     @param s Session to remove track from
00652     @param t Track pointer to find and remove
00653     @return 0 for failure, 1 for success
00654 */
00655 int burn_session_remove_track(struct burn_session *s, struct burn_track *t);
00656 
00657 
00658 /** Define the data in a track
00659     @param t the track to define
00660     @param offset The lib will write this many 0s before start of data
00661     @param tail The number of extra 0s to write after data
00662     @param pad 1 means the lib should pad the last sector with 0s if the
00663            track isn't exactly sector sized.  (otherwise the lib will
00664            begin reading from the next track)
00665     @param mode data format (bitfield)
00666 */
00667 void burn_track_define_data(struct burn_track *t, int offset, int tail,
00668                 int pad, int mode);
00669 
00670 /** Set the ISRC details for a track
00671     @param t The track to change
00672     @param country the 2 char country code. Each character must be
00673            only numbers or letters.
00674     @param owner 3 char owner code. Each character must be only numbers
00675            or letters.
00676     @param year 2 digit year. A number in 0-99 (Yep, not Y2K friendly).
00677     @param serial 5 digit serial number. A number in 0-99999.
00678 */
00679 void burn_track_set_isrc(struct burn_track *t, char *country, char *owner,
00680              unsigned char year, unsigned int serial);
00681 
00682 /** Disable ISRC parameters for a track
00683     @param t The track to change
00684 */
00685 void burn_track_clear_isrc(struct burn_track *t);
00686 
00687 /** Hide the first track in the "pre gap" of the disc
00688     @param s session to change
00689     @param onoff 1 to enable hiding, 0 to disable
00690 */
00691 void burn_session_hide_first_track(struct burn_session *s, int onoff);
00692 
00693 /** Get the drive's disc struct - free when done
00694     @param d drive to query
00695     @return the disc struct
00696 */
00697 struct burn_disc *burn_drive_get_disc(struct burn_drive *d);
00698 
00699 /** Set the track's data source
00700     @param t The track to set the data source for
00701     @param s The data source to use for the contents of the track
00702     @return An error code stating if the source is ready for use for
00703             writing the track, or if an error occured
00704     
00705 */
00706 enum burn_source_status burn_track_set_source(struct burn_track *t,
00707                           struct burn_source *s);
00708 
00709 /** Free a burn_source (decrease its refcount and maybe free it)
00710     @param s Source to free
00711 */
00712 void burn_source_free(struct burn_source *s);
00713 
00714 /** Creates a data source for an image file (and maybe subcode file) */
00715 struct burn_source *burn_file_source_new(const char *path,
00716                      const char *subpath);
00717 /** Tells how long a track will be on disc */
00718 int burn_track_get_sectors(struct burn_track *);
00719 
00720 
00721 /** Sets drive read and write speed
00722     @param d The drive to set speed for
00723     @param read Read speed in k/s (0 is max)
00724     @param write Write speed in k/s (0 is max)
00725 */
00726 void burn_drive_set_speed(struct burn_drive *d, int read, int write);
00727 
00728 /* these are for my debugging, they will disappear */
00729 void burn_structure_print_disc(struct burn_disc *d);
00730 void burn_structure_print_session(struct burn_session *s);
00731 void burn_structure_print_track(struct burn_track *t);
00732 
00733 /** Sets the write type for the write_opts struct
00734     @param opts The write opts to change
00735     @param write_type The write type to use
00736     @param block_type The block type to use
00737     @return Returns 1 on success and 0 on failure.
00738 */
00739 int burn_write_opts_set_write_type(struct burn_write_opts *opts,
00740                    enum burn_write_types write_type,
00741                    int block_type);
00742 
00743 /** Supplies toc entries for writing - not normally required for cd mastering
00744     @param opts The write opts to change
00745     @param count The number of entries
00746     @param toc_entries
00747 */
00748 void burn_write_opts_set_toc_entries(struct burn_write_opts *opts,
00749                      int count,
00750                      struct burn_toc_entry *toc_entries);
00751 
00752 /** Sets the session format for a disc
00753     @param opts The write opts to change
00754     @param format The session format to set
00755 */
00756 void burn_write_opts_set_format(struct burn_write_opts *opts, int format);
00757 
00758 /** Sets the simulate value for the write_opts struct
00759     @param opts The write opts to change
00760     @param sim If non-zero, the drive will perform a simulation instead of a burn
00761     @return Returns 1 on success and 0 on failure.
00762 */
00763 int  burn_write_opts_set_simulate(struct burn_write_opts *opts, int sim);
00764 
00765 /** Controls buffer underrun prevention
00766     @param opts The write opts to change
00767     @param underrun_proof if non-zero, buffer underrun protection is enabled
00768     @return Returns 1 on success and 0 on failure.
00769 */
00770 int burn_write_opts_set_underrun_proof(struct burn_write_opts *opts,
00771                        int underrun_proof);
00772 
00773 /** Sets whether to use opc or not with the write_opts struct
00774     @param opts The write opts to change
00775     @param opc If non-zero, optical power calibration will be performed at
00776                start of burn
00777      
00778 */
00779 void burn_write_opts_set_perform_opc(struct burn_write_opts *opts, int opc);
00780 
00781 /** Sets whether to read in raw mode or not
00782     @param opts The read opts to change
00783     @param raw_mode If non-zero, reading will be done in raw mode, so that everything in the data tracks on the
00784             disc is read, including headers.
00785 */
00786 void burn_read_opts_set_raw(struct burn_read_opts *opts, int raw_mode);
00787 
00788 /** Sets whether to report c2 errors or not 
00789     @param opts The read opts to change
00790     @param c2errors If non-zero, report c2 errors.
00791 */
00792 void burn_read_opts_set_c2errors(struct burn_read_opts *opts, int c2errors);
00793 
00794 /** Sets whether to read subcodes from audio tracks or not
00795     @param opts The read opts to change
00796     @param subcodes_audio If non-zero, read subcodes from audio tracks on the disc.
00797 */
00798 void burn_read_opts_read_subcodes_audio(struct burn_read_opts *opts,
00799                     int subcodes_audio);
00800 
00801 /** Sets whether to read subcodes from data tracks or not 
00802     @param opts The read opts to change
00803     @param subcodes_data If non-zero, read subcodes from data tracks on the disc.
00804 */
00805 void burn_read_opts_read_subcodes_data(struct burn_read_opts *opts,
00806                        int subcodes_data);
00807 
00808 /** Sets whether to recover errors if possible
00809     @param opts The read opts to change
00810     @param hardware_error_recovery If non-zero, attempt to recover errors if possible.
00811 */
00812 void burn_read_opts_set_hardware_error_recovery(struct burn_read_opts *opts,
00813                         int hardware_error_recovery);
00814 
00815 /** Sets whether to report recovered errors or not
00816     @param opts The read opts to change
00817     @param report_recovered_errors If non-zero, recovered errors will be reported.
00818 */
00819 void burn_read_opts_report_recovered_errors(struct burn_read_opts *opts,
00820                         int report_recovered_errors);
00821 
00822 /** Sets whether blocks with unrecoverable errors should be read or not
00823     @param opts The read opts to change
00824     @param transfer_damaged_blocks If non-zero, blocks with unrecoverable errors will still be read.
00825 */
00826 void burn_read_opts_transfer_damaged_blocks(struct burn_read_opts *opts,
00827                         int transfer_damaged_blocks);
00828 
00829 /** Sets the number of retries to attempt when trying to correct an error
00830     @param opts The read opts to change
00831     @param hardware_error_retries The number of retries to attempt when correcting an error.
00832 */
00833 void burn_read_opts_set_hardware_error_retries(struct burn_read_opts *opts,
00834                            unsigned char hardware_error_retries);
00835 
00836 /** Gets the maximum write speed for a drive
00837     @param d Drive to query
00838     @return Maximum write speed in K/s
00839 */
00840 int burn_drive_get_write_speed(struct burn_drive *d);
00841 
00842 /** Gets the maximum read speed for a drive
00843     @param d Drive to query
00844     @return Maximum read speed in K/s
00845 */
00846 int burn_drive_get_read_speed(struct burn_drive *d);
00847 
00848 /** Gets a copy of the toc_entry structure associated with a track
00849     @param t Track to get the entry from
00850     @param entry Struct for the library to fill out
00851 */
00852 void burn_track_get_entry(struct burn_track *t, struct burn_toc_entry *entry);
00853 
00854 /** Gets a copy of the toc_entry structure associated with a session's lead out
00855     @param s Session to get the entry from
00856     @param entry Struct for the library to fill out
00857 */
00858 void burn_session_get_leadout_entry(struct burn_session *s,
00859                                     struct burn_toc_entry *entry);
00860 
00861 /** Gets an array of all the sessions for the disc
00862     THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A SESSION
00863     @param d Disc to get session array for
00864     @param num Returns the number of sessions in the array
00865     @return array of sessions
00866 */
00867 struct burn_session **burn_disc_get_sessions(struct burn_disc *d,
00868                                              int *num);
00869 
00870 /** Gets an array of all the tracks for a session
00871     THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A TRACK
00872     @param s session to get track array for
00873     @param num Returns the number of tracks in the array
00874     @return array of tracks
00875 */
00876 struct burn_track **burn_session_get_tracks(struct burn_session *s,
00877                                             int *num);
00878 
00879 /** Gets the mode of a track
00880     @param track the track to query
00881     @return the track's mode
00882 */
00883 int burn_track_get_mode(struct burn_track *track);
00884 
00885 /** Returns whether the first track of a session is hidden in the pregap
00886     @param session the session to query
00887     @return non-zero means the first track is hidden
00888 */
00889 int burn_session_get_hidefirst(struct burn_session *session);
00890 
00891 /** Returns the library's version in its parts
00892     @param major The major version number
00893     @param minor The minor version number
00894     @param micro The micro version number
00895 */
00896 void burn_version(int *major, int *minor, int *micro);
00897 
00898 #ifndef DOXYGEN
00899 
00900 BURN_END_DECLS
00901 
00902 #endif
00903 
00904 #endif /*LIBBURN_H*/

Generated on Mon Feb 13 18:31:19 2006 for libburn by  doxygen 1.4.2