00001 /** 00002 @author Mario Danic, Thomas Schmitt 00003 00004 @mainpage Libburnia Documentation Index 00005 00006 @section intro Introduction 00007 00008 Libburnia is an open-source project for reading, mastering and writing 00009 optical discs. 00010 For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD-RW, DVD-R. 00011 00012 Not supported yet are dual layer media, HD-DVD, BD (blue ray). Testers for 00013 dual layer DVD+/-R are wanted, though. 00014 00015 The project comprises of several more or less interdependent parts which 00016 together strive to be a usable foundation for application development. 00017 These are libraries, language bindings, and middleware binaries which emulate 00018 classical (and valuable) Linux tools. 00019 00020 Our scope is currently Linux 2.4 and 2.6 only. For ports to other systems 00021 we would need : login on a development machine resp. a live OS on CD or DVD, 00022 advise from a system person about the equivalent of Linux sg or FreeBSD CAM, 00023 volunteers for testing of realistic use cases. 00024 00025 We have a workable code base for burning data and audio CDs and many DVD types. 00026 The burn API is quite comprehensively documented and can be used to build a 00027 presentable application. 00028 We have a functional binary which emulates the core use cases of cdrecord in 00029 order to prove that usability, and in order to allow you to explore libburn's 00030 scope by help of existing cdrecord frontends. 00031 00032 @subsection components The project components (list subject to growth, hopefully): 00033 00034 - libburn is the library by which preformatted data get onto optical media. 00035 It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or 00036 /dev/srM or /dev/hdX (e.g. on kernel 2.6). 00037 libburn is the foundation of our cdrecord emulation. Its code is 00038 independent of cdrecord. Its DVD capabilities are learned from 00039 studying the code of dvd+rw-tools and MMC-5 specs. No code but only 00040 the pure SCSI knowledge has been taken from dvd+rw-tools, though. 00041 00042 - libisofs is the library to pack up hard disk files and directories into a 00043 ISO 9660 disk image. This may then be brought to CD via libburn. 00044 libisofs is to be the foundation of our upcoming mkisofs emulation. 00045 00046 - cdrskin is a limited cdrecord compatibility wrapper for libburn. 00047 cdrecord is a powerful GPL'ed burn program included in Joerg 00048 Schilling's cdrtools. cdrskin strives to be a second source for 00049 the services traditionally provided by cdrecord. Additionally it 00050 provides libburn's DVD capabilities, where only -sao is compatible 00051 with cdrecord. 00052 cdrskin does not contain any bytes copied from cdrecord's sources. 00053 Many bytes have been copied from the message output of cdrecord 00054 runs, though. 00055 See cdrskin/README for more. 00056 00057 - "test" is a collection of application gestures and examples given by the 00058 authors of the library features. The burn API example of libburn 00059 is named test/libburner.c . The API for media information inquiry is 00060 demonstrated in test/telltoc.c . 00061 Explore these examples if you look for inspiration. 00062 00063 We plan to be a responsive upstream. Bear with us. 00064 00065 00066 @section using Using the libraries 00067 00068 Our build system is based on autotools. 00069 User experience tells us that you will need at least autotools version 1.7. 00070 00071 To build libburn and its subprojects it should be sufficient to go into 00072 its toplevel directory and execute 00073 00074 - ./bootstrap (needed if you downloaded from SVN) 00075 00076 - ./configure 00077 00078 - make 00079 00080 To make the libraries accessible for running resp. developing applications 00081 00082 - make install 00083 00084 Both libraries are written in C language and get built by autotools. 00085 Thus we expect them to be useable by a wide range of Linux-implemented 00086 languages and development tools. 00087 00088 00089 @section libburner Libburner 00090 00091 libburner is a minimal demo application for the library libburn 00092 (see: libburn/libburn.h) as provided on http://libburn.pykix.org . 00093 It can list the available devices, can blank a CD-RW or DVD-RW and 00094 can burn to recordable CD and recordable single layer DVD. 00095 00096 It's main purpose, nevertheless, is to show you how to use libburn and also 00097 to serve the libburnia team as reference application. libburner does indeed 00098 define the standard way how above three gestures can be implemented and 00099 stay upward compatible for a good while. 00100 00101 @subsection libburner-help Libburner --help 00102 <pre> 00103 Usage: test/libburner 00104 [--drive <address>|<driveno>|"-"] [--audio] 00105 [--blank_fast|--blank_full|--format_overwrite] 00106 [--try_to_simulate] 00107 [--multi] [<one or more imagefiles>|"-"] 00108 Examples 00109 A bus scan (needs rw-permissions to see a drive): 00110 test/libburner --drive - 00111 Burn a file to drive chosen by number, leave appendable: 00112 test/libburner --drive 0 --multi my_image_file 00113 Burn a file to drive chosen by persistent address, close: 00114 test/libburner --drive /dev/hdc my_image_file 00115 Blank a used CD-RW (is combinable with burning in one run): 00116 test/libburner --drive /dev/hdc --blank_fast 00117 Blank a used DVD-RW (is combinable with burning in one run): 00118 test/libburner --drive /dev/hdc --blank_full 00119 Format a DVD-RW to avoid need for blanking before re-use: 00120 test/libburner --drive /dev/hdc --format_overwrite 00121 Burn two audio tracks (to CD only): 00122 lame --decode -t /path/to/track1.mp3 track1.cd 00123 test/dewav /path/to/track2.wav -o track2.cd 00124 test/libburner --drive /dev/hdc --audio track1.cd track2.cd 00125 Burn a compressed afio archive on-the-fly: 00126 ( cd my_directory ; find . -print | afio -oZ - ) | \ 00127 test/libburner --drive /dev/hdc - 00128 To be read from *not mounted* media via: afio -tvZ /dev/hdc 00129 </pre> 00130 libburner has two companions, telltoc and dewav, which help to perform some 00131 peripheral tasks of burning. 00132 00133 telltoc prints a table of content (sessions, tracks and leadouts), it tells 00134 about type and state of media, and also is able to provide the necessary 00135 multi-session information for program mkisofs option -C. Especially helpful 00136 are its predictions with "Write multi" and "Write modes" where availability 00137 of "TAO" indicates that tracks of unpredicted length can be written. 00138 See: test/telltoc --help. 00139 00140 dewav extracts raw byte-swapped audio data from files of format .wav (MS WAVE) 00141 or .au (SUN Audio). See example in libburner --help. 00142 00143 @subsection libburner-source Sourceode of libburner 00144 00145 Click on blue names of functions, structures, variables, etc in oder to 00146 get to the according specs of libburn API or libburner sourcecode. 00147 00148 @include libburner.c 00149 */