• Main Page
  • Data Structures
  • Files
  • File List
  • Globals

libisoburn-0.5.6.pl00/libisoburn/isoburn.h

Go to the documentation of this file.
00001 
00002 /*
00003   Class struct of libisoburn.
00004 
00005   Copyright 2007 - 2010 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
00006                     and Thomas Schmitt <scdbackup@gmx.net>
00007   Provided under GPL version 2 or later.
00008 */
00009 
00010 #ifndef Isoburn_includeD
00011 #define Isoburn_includeD
00012 
00013 
00014 /* for uint8_t */
00015 #include <stdint.h>
00016 
00017 /* For emulated TOC of overwriteable media.
00018    Provides minimal info for faking a struct burn_toc_entry.
00019 */
00020 struct isoburn_toc_entry {
00021  int session;
00022  int track_no; /* point */
00023  int start_lba;
00024  int track_blocks;
00025 
00026  char *volid; /* For caching a volume id from emulated toc on overwriteables */
00027 
00028  struct isoburn_toc_entry *next;
00029 };
00030 
00031 int isoburn_toc_entry_new(struct isoburn_toc_entry **objpt,
00032                           struct isoburn_toc_entry *boss, int flag);
00033 
00034 /* @param flag bit0= delete all subordinates too
00035 */
00036 int isoburn_toc_entry_destroy(struct isoburn_toc_entry **o, int flag);
00037 
00038 
00039 /* Size of target_iso_head which is to be written during
00040    isoburn_activate_session()
00041 */
00042 #define Libisoburn_target_head_sizE (32*2048)
00043 
00044 struct isoburn {
00045 
00046 
00047  /* The libburn drive to which this isoburn object is related
00048     Most isoburn calls will use a burn_drive as object handle */
00049  struct burn_drive *drive;
00050 
00051  /* -1= inappropriate media state detected
00052     0= libburn multi-session media, resp. undecided yet
00053     1= random access media */
00054  int emulation_mode;
00055 
00056  /* Although rarely used, libburn can operate on several
00057     drives simultaneously. */
00058  struct isoburn *prev;
00059  struct isoburn *next;
00060 
00061 
00062  /* If >= 0, this address is used as reply for isoburn_disc_get_msc1()
00063  */
00064  int fabricated_msc1;
00065 
00066  /* If >= 0, this address is used in isoburn_disc_track_lba_nwa()
00067     as reply parameter nwa.
00068     (The other nwa parameters below apply only to the effective write address
00069      on random access media. msc2 is handed to libisofs but not to libburn.)
00070  */
00071  int fabricated_msc2;
00072  
00073 
00074  /* The nwa to be used for a first session on the present kind of overwriteable
00075     media (usually Libisoburn_overwriteable_starT, but might be forced to 0)
00076  */
00077  int zero_nwa;
00078 
00079  /* Start address as given by image examination (bytes, not blocks) */
00080  off_t min_start_byte;
00081 
00082  /* Aligned start address to be used for processing (counted in blocks) */
00083  int nwa;
00084 
00085 
00086  /* Truncate to .nwa an eventual regular file serving as output drive */
00087  int truncate;
00088 
00089  /* Eventual freely fabricated isoburn_disc_get_status().
00090     BURN_DISC_UNREADY means that this variable is disabled
00091     and normally emulated status is in effect.
00092  */
00093  enum burn_disc_status fabricated_disc_status;
00094 
00095  /* Eventual emulated table of content read from the chain of ISO headers
00096     on overwriteable media.
00097  */ 
00098  struct isoburn_toc_entry *toc;
00099 
00100  /* Indicator wether the most recent burn run worked :
00101     -1 = undetermined, ask libburn , 0 = failure , 1 = success
00102     To be inquired by isoburn_drive_wrote_well()
00103  */
00104  int wrote_well;
00105 
00106  
00107  /* Buffered ISO head from media (should that become part of
00108     ecma119_read_opts ?) */
00109  uint8_t target_iso_head[Libisoburn_target_head_sizE];
00110 
00111  /* Libisofs image context */
00112  IsoImage *image;
00113 
00114  /* The block data source from which the existing image is read.
00115  */
00116  IsoDataSource *iso_data_source;
00117 
00118  /* The burn source which transfers data from libisofs to libburn.
00119     It has its own fifo.
00120  */
00121  struct burn_source *iso_source;
00122 
00123  /* For iso_tree_set_report_callback() */
00124  int (*read_pacifier)(IsoImage*, IsoFileSource*);
00125 
00126  /* For iso_image_attach_data() */
00127  void *read_pacifier_handle;
00128 
00129  /* An application provided method to immediately deliver messages */
00130  int (*msgs_submit)(void *handle, int error_code, char msg_text[],
00131                     int os_errno, char severity[], int flag);
00132  void *msgs_submit_handle;  /* specific to application method */
00133  int msgs_submit_flag;      /* specific to application method */
00134 
00135 };
00136 
00137 
00138 /* Creation and disposal function */
00139 int isoburn_new(struct isoburn **objpt, int flag);
00140 int isoburn_destroy(struct isoburn **objpt, int flag);
00141 
00142 /* Eventual readers for public attributes */
00143 /* ( put into separate .h file then ) */
00144 int isoburn_get_emulation_mode(struct isoburn *o, int *pt, int flag);
00145 int isoburn_get_target_volset(struct isoburn *o, IsoImage **pt, int flag);
00146 
00147 /* List management */
00148 int isoburn_get_prev(struct isoburn *o, struct isoburn **pt, int flag);
00149 int isoburn_get_next(struct isoburn *o, struct isoburn **pt, int flag);
00150 int isoburn_destroy_all(struct isoburn **objpt, int flag);
00151 int isoburn_link(struct isoburn *o, struct isoburn *link, int flag);
00152 int isoburn_count(struct isoburn *o, int flag);
00153 int isoburn_by_idx(struct isoburn *o, int idx, struct isoburn **pt, int flag);
00154 int isoburn_find_by_drive(struct isoburn **pt, struct burn_drive *d, int flag);
00155 
00156 
00157 /* Non API inner interfaces */
00158 
00159 /* Submit a libisofs error to the libburn messenger. An application message
00160    reader shall recognize the error code range and attribute it to the
00161    libisofs message channel to which one cannot submit via API.
00162    @param iso_error_code   return value <= 0 from a libisofs API call.
00163    @param default_msg_text is to be put out if iso_error_code leads to no
00164                            error message
00165    @param os_errno         operating system errno, submit 0 if none is known
00166    @param min_severity     minimum severity, might be be increased if libisofs
00167                            error severity surpasses min_severity.
00168    @param flag             Bitfield, submit 0 for now
00169 */
00170 int isoburn_report_iso_error(int iso_error_code, char default_msg_text[],
00171                              int os_errno, char min_severity[], int flag);
00172 
00173 /* Calls from burn_wrap.c into isofs_wrap.c */ 
00174 
00175 int isoburn_start_emulation(struct isoburn *o, int flag);
00176 int isoburn_invalidate_iso(struct isoburn *o, int flag);
00177 
00178 
00179 /* Calls from isofs_wrap.c into burn_wrap.c */
00180 
00181 /** Get an eventual isoburn object which is wrapped around the drive.
00182     @param pt    Eventually returns a pointer to the found object.
00183                  It is allowed to become NULL if return value is -1 or 0.
00184                  In this case, the drive is a genuine libburn drive
00185                  with no emulation activated by isoburn.
00186     @param drive The drive to be searched for
00187     @param flag  unused yet
00188     @return -1 unsuitable media, 0 generic media, 1 emulated media.
00189 */
00190 int isoburn_find_emulator(struct isoburn **pt,
00191                           struct burn_drive *drive, int flag);
00192 
00193 /* Deliver an event message. Either via a non-NULL o->msgs_submit() method 
00194    or via burn_msgs_submit() of libburn.
00195 */
00196 int isoburn_msgs_submit(struct isoburn *o, int error_code, char msg_text[], 
00197                         int os_errno, char severity[], int flag);
00198 
00199 /** Set the start address for an emulated add-on session. The value will
00200     be rounded up to the alignment necessary for the media. The aligned
00201     value will be divided by 2048 and then put into  o->nwa .
00202     @param o     The isoburn object to be programmed.
00203     @param value The start address in bytes
00204     @param flag  unused yet
00205     @return <=0 is failure , >0 success
00206 */
00207 int isoburn_set_start_byte(struct isoburn *o, off_t value, int flag);
00208 
00209 /** Obtains the image address offset to be used with image generation.
00210     This is either the (emulated) drive nwa or a value set by
00211     isoburn_prepare_blind_grow().
00212     In any case this is the address to tell to iso_write_opts_set_ms_block().
00213     @param o     The isoburn object to be inquired
00214     @param opts  If not NULL: write parameters to be set on drive before query
00215     @param msc2  The value to be used with iso_write_opts_set_ms_block()
00216     @param flag  unused yet
00217     @return <=0 is failure , >0 success
00218 */
00219 int isoburn_get_msc2(struct isoburn *o,
00220                      struct burn_write_opts *opts, int *msc2, int flag);
00221 
00222 /** Get a data source suitable for read from a drive using burn_read_data()
00223     function.
00224     @param d drive to read from. Must be grabbed.
00225     @return the data source, NULL on error. Must be freed with libisofs
00226             iso_data_source_unref() function. Note: this doesn't release
00227             the drive.
00228 */
00229 IsoDataSource *
00230 isoburn_data_source_new(struct burn_drive *d);
00231 
00232 /** Disable read capabilities of a data source which was originally created
00233     by isoburn_data_source_new(). After this any attempt to read will yield
00234     a FATAL programming error event.
00235     This is usually done to allow libburn to release the drive while libisofs
00236     still holds a reference to the data source object. libisofs is not supposed
00237     to use this object for reading any more, nevertheless. The disabled state
00238     of the data source is a safety fence around this daring situation.
00239     @param src The data source to be disabled
00240     @param flag  unused yet
00241     @return <=0 is failure , >0 success
00242 */
00243 int isoburn_data_source_shutdown(IsoDataSource *src, int flag);
00244 
00245 
00246 /**
00247  * Options for image reading.
00248    (Comments here may be outdated. API getter/setter function descriptions
00249     may override the descriptions here. Any difference is supposed to be a
00250     minor correction only.)
00251  */
00252 struct isoburn_read_opts {
00253     unsigned int norock:1; /*< Do not read Rock Ridge extensions */
00254     unsigned int nojoliet:1; /*< Do not read Joliet extensions */
00255     unsigned int noiso1999:1; /*< Do not read ISO 9660:1999 enhanced tree */
00256 
00257     /* ts A90121 */
00258     unsigned int noaaip:1;   /* Do not read AAIP for ACL and EA */
00259     unsigned int noacl:1;    /* Do not read ACL from external file objects */
00260     unsigned int noea:1;     /* Do not read XFS-style EA from externals */
00261 
00262     /* ts A90508 */
00263     unsigned int noino:1;    /* Discard eventual PX inode numbers */
00264 
00265     /* ts A90810 */
00266     unsigned int nomd5:1;    /* Do not read eventual MD5 array */
00267 
00268     unsigned int preferjoliet:1; 
00269                 /*< When both Joliet and RR extensions are present, the RR
00270                  *  tree is used. If you prefer using Joliet, set this to 1. */
00271     uid_t uid; /**< Default uid when no RR */
00272     gid_t gid; /**< Default uid when no RR */
00273     mode_t mode; /**< Default mode when no RR (only permissions) */
00274     mode_t dirmode; /**< Default mode for directories 
00275                          when no RR (only permissions) */
00276 
00277     /**
00278      * Input charset for RR file names. NULL to use default locale charset.
00279      */
00280     char *input_charset;
00281 
00282     /**
00283      * Enable or disable methods to automatically choose an input charset.
00284      * This eventually overrides input_charset.
00285      *
00286      * bit0= allow to set the input character set automatically from
00287      *       attribute "isofs.cs" of root directory
00288      */
00289     int auto_input_charset;
00290 
00291     /* modified by the function isoburn_read_image */
00292     unsigned int hasRR:1; /*< It will be set to 1 if RR extensions are present,
00293                              to 0 if not. */
00294     unsigned int hasJoliet:1; /*< It will be set to 1 if Joliet extensions are 
00295                                   present, to 0 if not. */
00296 
00297     /**
00298      * It will be set to 1 if the image is an ISO 9660:1999, i.e. it has
00299      * a version 2 Enhanced Volume Descriptor.
00300      */
00301     unsigned int hasIso1999:1;
00302 
00303     /** It will be set to 1 if El-Torito boot record is present, to 0 if not.*/
00304     unsigned int hasElTorito:1;
00305 
00306     uint32_t size; /**< Will be filled with the size (in 2048 byte block) of 
00307                     *   the image, as reported in the PVM. */
00308     unsigned int pretend_blank:1; /* always create empty image */
00309 };
00310 
00311 
00312 /**
00313  * Options for image generation by libisofs and image transport to libburn.
00314    (Comments here may be outdated. API getter/setter function descriptions
00315     may override the descriptions here. Any difference is supposed to be a
00316     minor correction only.)
00317  */
00318 struct isoburn_imgen_opts {
00319 
00320     /* Options for image generation */
00321 
00322     int level;  /**< ISO level to write at. */
00323     
00324     /** Which extensions to support. */
00325     unsigned int rockridge :1;
00326     unsigned int joliet :1;
00327     unsigned int iso1999 :1;
00328 
00329     /* Whether to mark suitable IsoNode as hardlinks in RRIP PX */
00330     unsigned int hardlinks :1;
00331 
00332     /* Write eventual AAIP info containing ACL and EA */
00333     unsigned int aaip :1;
00334 
00335     /* Produce and write a MD5 checksum of the whole session stream. */
00336     unsigned int session_md5 :1;
00337 
00338     /* Produce and write MD5 checksums for each single IsoFile.
00339        See parameter files of iso_write_opts_set_record_md5().
00340      */
00341     unsigned int file_md5 :2;
00342 
00343     /* relaxed constraints */
00344 
00345     /*
00346      * Relaxed constraints. Setting any of these to 1 break the specifications,
00347      * but it is supposed to work on most moderns systems. Use with caution.
00348      */
00349 
00350     /**
00351      * Omit the version number (";1") at the end of the ISO-9660 identifiers.
00352      * Version numbers are usually not used.
00353      *      bit0= omit version number with ECMA-119 and Joliet
00354      *      bit1= omit version number with Joliet alone
00355      */
00356     unsigned int omit_version_numbers :2;
00357 
00358     /**
00359      * Allow ISO-9660 directory hierarchy to be deeper than 8 levels.
00360      */
00361     unsigned int allow_deep_paths :1;
00362 
00363     /**
00364      * Allow path in the ISO-9660 tree to have more than 255 characters.
00365      */
00366     unsigned int allow_longer_paths :1;
00367 
00368     /**
00369      * Allow a single file or directory hierarchy to have up to 37 characters.
00370      * This is larger than the 31 characters allowed by ISO level 2, and the
00371      * extra space is taken from the version number, so this also forces
00372      * omit_version_numbers.
00373      */
00374     unsigned int max_37_char_filenames :1;
00375 
00376     /**
00377      * ISO-9660 forces filenames to have a ".", that separates file name from
00378      * extension. libisofs adds it if original filename doesn't has one. Set
00379      * this to 1 to prevent this behavior
00380      *      bit0= no forced dot with ECMA-119
00381      *      bit1= no forced dot with Joliet
00382      */
00383     unsigned int no_force_dots :2;
00384 
00385     /**
00386      * Allow lowercase characters in ISO-9660 filenames. By default, only
00387      * uppercase characters, numbers and a few other characters are allowed.
00388      */
00389     unsigned int allow_lowercase :1;
00390 
00391     /**
00392      * Allow all ASCII characters to be appear on an ISO-9660 filename. Note
00393      * that "/" and "\0" characters are never allowed, even in RR names.
00394      */
00395     unsigned int allow_full_ascii :1;
00396 
00397     /**
00398      * Allow paths in the Joliet tree to have more than 240 characters.
00399      */
00400     unsigned int joliet_longer_paths :1;
00401 
00402     /**
00403      * Store timestamps as GMT rather than in local time.
00404      */
00405     unsigned int always_gmt :1;
00406 
00407     /**
00408      * Write Rock Ridge info as of specification RRIP-1.10 rather than
00409      * RRIP-1.12: signature "RRIP_1991A" rather than "IEEE_1282",
00410      *            field PX without file serial number
00411      */
00412     unsigned int rrip_version_1_10 :1;
00413 
00414     /**
00415      * Store as ECMA-119 Directory Record timestamp the mtime
00416      * of the source rather than the image creation time.
00417      */
00418     unsigned int dir_rec_mtime :1;
00419 
00420     /**
00421      * Write AAIP as extension according to SUSP 1.10 rather than SUSP 1.12.
00422      * I.e. without announcing it by an ER field and thus without the need
00423      * to preceed the RRIP fields by an ES and to preceed the AA field by ES.
00424      */
00425     unsigned int aaip_susp_1_10 :1;
00426 
00427     unsigned int sort_files:1;
00428                 /**< If files should be sorted based on their weight. */
00429 
00430     /**
00431      * The following options set the default values for files and directory
00432      * permissions, gid and uid. All these take one of three values: 0, 1 or 2.
00433      * If 0, the corresponding attribute will be kept as set in the IsoNode.
00434      * Unless you have changed it, it corresponds to the value on disc, so it
00435      * is suitable for backup purposes. If set to 1, the corresponding attrib.
00436      * will be changed by a default suitable value. Finally, if you set it to
00437      * 2, the attrib. will be changed with the value specified in the options
00438      * below. Note that for mode attributes, only the permissions are set, the
00439      * file type remains unchanged.
00440      */
00441     unsigned int replace_dir_mode :2; 
00442     unsigned int replace_file_mode :2;
00443     unsigned int replace_uid :2;
00444     unsigned int replace_gid :2;
00445     
00446     mode_t dir_mode; /** Mode to use on dirs when replace_dir_mode == 2. */
00447     mode_t file_mode; /** Mode to use on files when replace_file_mode == 2. */
00448     uid_t uid; /** uid to use when replace_uid == 2. */
00449     gid_t gid; /** gid to use when replace_gid == 2. */
00450 
00451     char *output_charset; /**< NULL to use default charset */
00452 
00453 
00454     /* Options for image transport */
00455 
00456     /** The number of bytes to be used for the fifo which decouples libisofs
00457         and libburn for better throughput and for reducing the risk of
00458         interrupting signals hitting the libburn thread which operates the
00459         MMC drive.
00460         The size will be rounded up to the next full 2048.
00461         Minimum is 64kiB, maximum is 1 GiB (but that is too much anyway).
00462     */
00463     int fifo_size;
00464 
00465 
00466     /** Output value: Block address of session start as evaluated from media
00467                       and other options by libisoburn and libburn.
00468         If <0 : Invalid
00469         If >=0: Valid block number. Block size is always 2 KiB.
00470     */
00471     int effective_lba;
00472 
00473     /** Output value: Block address of data section start as predicted by
00474                       libisofs.
00475         If < 16: Invalid
00476         If >=16: Valid block number. Block size is always 2 KiB.
00477     */
00478     int data_start_lba;
00479 
00480     /**
00481      * If not empty: Parameters "name" and "timestamp" for a scdbackup stream
00482      * checksum tag. See scdbackup/README appendix VERIFY.
00483      * It makes sense only for single session images which start at LBA 0.
00484      * Such a tag may be part of a libisofs checksum tag block after the
00485      * session tag line. It then covers the whole session up to its own start
00486      * position.
00487      * If scdbackup_tag_written is not NULL then it is a pointer to an
00488      * application provided array with at least 512 characters. The effectively
00489      * written scdbackup tag will be copied to this memory location.
00490      */
00491     char scdbackup_tag_name[81];
00492     char scdbackup_tag_time[19];
00493     char *scdbackup_tag_written;
00494 
00495 
00496     /* Content of an embedded boot image. Valid if not NULL.
00497      * In that case it must point to a memory buffer at least 32 kB.
00498      */
00499     char *system_area_data;
00500     /*
00501      * bit0= make bytes 446 - 512 of the system area a partition
00502      *       table which reserves partition 1 from byte 63*512 to the
00503      *       end of the ISO image. Assumed are 63 secs/hed, 255 head/cyl.
00504      *       (GRUB protective msdos label.)
00505      *       This works with and without system_area_data.
00506      */
00507     int system_area_options;
00508 
00509     /* User settable PVD time stamps */
00510     time_t vol_creation_time;
00511     time_t vol_modification_time;
00512     time_t vol_expiration_time;
00513     time_t vol_effective_time;
00514     /* To eventually override vol_modification_time by unconverted string
00515        and timezone 0 */
00516     char vol_uuid[17];
00517 
00518 };
00519 
00520 
00521 /* Alignment for session starts on overwriteable media.
00522    (Increased from 16 to 32 blocks for aligning to BD-RE clusters.)
00523 */
00524 #define Libisoburn_nwa_alignemenT 32
00525 
00526 
00527 /* Alignment for outer session scanning with -ROM drives.
00528    (E.g. my DVD-ROM drive shows any DVD type as 0x10 "DVD-ROM" with
00529     more or less false capacity and TOC.)
00530 */
00531 #define Libisoburn_toc_scan_alignemenT 16
00532 
00533 /* Maximum gap to be bridged during a outer TOC scan. Gaps appear between the
00534    end of a session and the start of the next session.
00535    The longest gap found so far was about 38100 after the first session of a
00536    DVD-R.
00537 */
00538 #define Libisoburn_toc_scan_max_gaP 65536
00539 
00540 
00541 /* Creating a chain of image headers which form a TOC:
00542 
00543    The header of the first session is written after the LBA 0 header.
00544    So it persists and can give the end of its session. By help of
00545    Libisoburn_nwa_alignemenT it should be possible to predict the start
00546    of the next session header.
00547    The LBA 0 header is written by isoburn_activate_session() already
00548    with the first session. So the media is mountable.
00549    A problem arises with DVD-RW in Intermediate State. They cannot be
00550    written by random access before they were written sequentially.
00551    In this case, no copy of the session  1 header is maintained and no TOC
00552    will be possible. Thus writing begins sequentially at LBA 0.
00553 */
00554 #define Libisoburn_overwriteable_starT \
00555                                    ((off_t) (Libisoburn_target_head_sizE/2048))
00556 
00557 
00558 /* Wrappers for emulation of TOC on overwriteable media */
00559 
00560 struct isoburn_toc_track {
00561  /* Either track or toc_entry are supposed to be NULL */
00562  struct burn_track *track;
00563  struct isoburn_toc_entry *toc_entry;
00564 };
00565 
00566 struct isoburn_toc_session {
00567  /* Either session or tracks and toc_entry are supposed to be NULL */
00568  struct burn_session *session;
00569  struct isoburn_toc_track **track_pointers;
00570  int track_count;
00571  struct isoburn_toc_entry *toc_entry;
00572 };
00573 
00574 struct isoburn_toc_disc {
00575  /* Either disc or sessions and toc are supposed to be NULL */
00576  struct burn_disc *disc; 
00577  struct isoburn_toc_session *sessions;           /* storage array */
00578  struct isoburn_toc_session **session_pointers;  /* storage array */
00579  struct isoburn_toc_track *tracks;               /* storage array */
00580  struct isoburn_toc_track **track_pointers;      /* storage array */
00581  int session_count;
00582  int track_count;
00583  struct isoburn_toc_entry *toc;
00584 };
00585 
00586 #endif /* Isoburn_includeD */
00587 

Generated on Tue Aug 17 2010 13:01:43 for libisoburn by  doxygen 1.7.1