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

Generated on Sat May 5 06:21:19 2007 for libburn by  doxygen 1.5.2