libisofs-0.2.8/libisofs/libisofs.h

Go to the documentation of this file.
00001 /* -*- indent-tabs-mode: t; tab-width: 8; c-basic-offset: 8; -*- */
00002 /* vim: set noet ts=8 sts=8 sw=8 : */
00003 
00004 /**
00005  * Create an ISO-9660 data volume with Rock Ridge and Joliet extensions.
00006  * Usage is easy:
00007  *  - Create a new volume.
00008  *  - Add files and directories.
00009  *  - Write the volume to a file or create a burn source for use with Libburn.
00010  */
00011 
00012 #ifndef LIBISO_LIBISOFS_H
00013 #define LIBISO_LIBISOFS_H
00014 
00015 #include <sys/types.h>
00016 
00017 /* #include <libburn.h> */
00018 struct burn_source;
00019 
00020 /**
00021  * Data volume.
00022  * @see volume.h for details.
00023  */
00024 struct iso_volume;
00025 
00026 /**
00027  * A set of data volumes.
00028  * @see volume.h for details.
00029  */
00030 struct iso_volset;
00031 
00032 /**
00033  * A node in the filesystem tree.
00034  * \see tree.h
00035  */
00036 struct iso_tree_node;
00037 
00038 /**
00039  * El-Torito boot image
00040  * \see eltorito.h
00041  */
00042 struct el_torito_boot_image;
00043 
00044 /**
00045  * A directory in the filesystem tree.
00046  * The first member of this is an iso_tree_node.
00047  * \see tree.h
00048  */
00049 struct iso_tree_node_dir;
00050 
00051 /**
00052  * Extensions addition to ECMA-119 (ISO-9660) image. Usage of at least
00053  * one of these flags is highly recommended if the disc will be used on a
00054  * modern OS.  
00055  */
00056 enum ecma119_extension_flag {
00057     /** 
00058      * Add the standard Rock Ridge extensions. This adds POSIX filesystem 
00059      * features to the ECMA-119 image. Thus, usage of this flag is highly
00060      * recommended for images used on GNU/Linux systems. With the usage
00061      * of RR extension, the resulting image will have long filenames (up to
00062      * 255 characters), deeper directory structure, POSIX permissions and
00063      * owner info on files and directories, support for symbolic links or 
00064      * special files... All that attributes can be modified/setted with the
00065      * appropiate function. 
00066      */
00067     ECMA119_ROCKRIDGE   = (1<<0),
00068     /**
00069      * Add the non-standard Joliet extension to the image. This extension is
00070      * heavily used in Microsoft Windows systems, so if you plan to use your
00071      * disc on such a system you should add this extension. Usage of Joliet
00072      * supplies longer filesystem length (up to 64 unicode characters), and
00073      * deeper directory structure.
00074      */
00075     ECMA119_JOLIET      = (1<<1)
00076 };
00077 
00078 /**
00079  * Flag used to hide a file in the RR/ISO or Joliet tree.
00080  * 
00081  * \see iso_tree_node_set_hidden
00082  */
00083 enum hide_node_flag {
00084     LIBISO_HIDE_ON_RR = 1 << 0,
00085     LIBISO_HIDE_ON_JOLIET = 1 << 1
00086 };
00087 
00088 /**
00089  * El-Torito bootable image type.
00090  */
00091 enum eltorito_boot_media_type {
00092     ELTORITO_FLOPPY_EMUL,
00093     ELTORITO_HARD_DISC_EMUL,
00094     ELTORITO_NO_EMUL
00095 };
00096 
00097 enum ecma119_relaxed_constraints_flag {
00098     ECMA119_OMIT_VERSION_NUMBERS = (1<<0),
00099     /* 37 char filenames involves no version number */
00100     ECMA119_37_CHAR_FILENAMES = (1<<1) | (1<<0), 
00101     ECMA119_NO_DIR_REALOCATION = (1<<2),
00102     ECMA119_RELAXED_FILENAMES = (1<<3)
00103 };
00104 
00105 /**
00106  * Holds the options for the image generation.
00107  */
00108 struct ecma119_source_opts {
00109     int volnum; /**< The volume in the set which you want to write (usually 0) */
00110     int level;  /**< ISO level to write at. */
00111     int flags;  /**< Which extensions to support. */
00112     int relaxed_constraints; /**< see ecma119_relaxed_constraints_flag */
00113     unsigned int no_cache_inodes:1; 
00114                 /**< If use inode caching or not. Set it to 1 to prevent
00115                  *   inode caching.
00116                  *   Usage of inode caching allows detection of hard-links,
00117                  *   which contents are only written once to disc this way.
00118                  *   Don't use inode caching in systems with non unique inodes
00119                  *   per device.
00120                  */  
00121     unsigned int sort_files:1;
00122                 /**< If files should be sorted based on their weight. */
00123     unsigned int default_mode:1;
00124                 /**<
00125                  * The default values for files and directory permissions,
00126                  * gid and uid. This option can be overwritten when set
00127                  * one of the following.
00128                  * 0 to use useful values, 1 to use node modes (this are
00129                  * the same as filesystem ones if not changed after added
00130                  * to tree). 
00131                  */
00132     unsigned int replace_dir_mode:1;
00133                 /**<
00134                  * When 1, permissions for all dirs will be replaced by the
00135                  * specified in dir_mode field.
00136                  */
00137     unsigned int replace_file_mode:1;
00138                 /**<
00139                  * When 1, permissions for all files will be replaced by the
00140                  * specified in file_mode field.
00141                  */
00142     unsigned int replace_uid:1;
00143                 /**<
00144                  * When 1, uid of all nodes (both files and dirs) will be
00145                  * replaced by the specified in uid field.
00146                  */
00147     unsigned int replace_gid:1;
00148                 /**<
00149                  * When 1, gid of all nodes (both files and dirs) will be
00150                  * replaced by the specified in gid field.
00151                  */
00152     mode_t dir_mode; /**< Mode to use on dirs when replace_dir_mode is set. */
00153     mode_t file_mode; /**< Mode to use on files when replace_file_mode is set. */
00154     gid_t gid; /**< gid to use when replace_gid is set. */
00155     uid_t uid; /**< uid to use when replace_uid is set. */
00156     char *input_charset; /**< NULL to use default charset */
00157     char *ouput_charset; /**< NULL to use default charset */
00158 };
00159 
00160 /**
00161  * This will hold the error code for some functions, if them fail.
00162  */
00163 int libisofs_errno;
00164 
00165 /* an unexpected internal error */
00166 #define INTERNAL_ERROR -1
00167 /* file don't exists, or can't be stat'ed */
00168 #define NO_FILE 1
00169 /* user haven't read access to file */
00170 #define NO_READ_ACCESS 2
00171 /* unexpected file type, eg., passing a dir instead of a regular file */
00172 #define UNEXPECTED_FILE_TYPE 3
00173 /* invalid boot image size */
00174 #define ELTORITO_WRONG_IMAGE_SIZE 4
00175 
00176 /**
00177  * Controls the bahavior of iso_tree_radd_dir function
00178  */
00179 struct iso_tree_radd_dir_behavior {
00180     char** excludes; /**< List of paths (file or directory) to be ignored. */
00181     //int follow_sym_link;
00182     int stop_on_error; /**< Stop when an error was found?. */
00183     int error; /**< set to 1 on error */
00184     //int notify_errors;
00185     //char** errors;
00186 };
00187 
00188 /**
00189  * Create a new volume.
00190  * The parameters can be set to NULL if you wish to set them later.
00191  */
00192 struct iso_volume *iso_volume_new(const char *volume_id,
00193                   const char *publisher_id,
00194                   const char *data_preparer_id);
00195 
00196 struct iso_volume *iso_volume_new_with_root(const char *volume_id,
00197                         const char *publisher_id,
00198                         const char *data_preparer_id,
00199                         struct iso_tree_node_dir *root);
00200 
00201 /**
00202  * Free a volume.
00203  */
00204 void iso_volume_free(struct iso_volume *volume);
00205 
00206 /**
00207  * Free a set of data volumes.
00208  */
00209 void iso_volset_free(struct iso_volset *volume);
00210 
00211 /**
00212  * Get the root directory for a volume.
00213  */
00214 struct iso_tree_node_dir *iso_volume_get_root(const struct iso_volume *volume);
00215 
00216 /**
00217  * Fill in the volume identifier for a volume.
00218  */
00219 void iso_volume_set_volume_id(struct iso_volume *volume,
00220                   const char *volume_id);
00221 
00222 /**
00223  * Fill in the publisher for a volume.
00224  */
00225 void iso_volume_set_publisher_id(struct iso_volume *volume,
00226                  const char *publisher_id);
00227 
00228 /**
00229  * Fill in the data preparer for a volume.
00230  */
00231 void iso_volume_set_data_preparer_id(struct iso_volume *volume,
00232                      const char *data_preparer_id);
00233 
00234 /**
00235  * Fill in the system id for a volume. Up to 32 characters.
00236  */
00237 void iso_volume_set_system_id(struct iso_volume *volume,
00238                      const char *system_id);
00239 
00240 /**
00241  * Fill in the application id for a volume. Up to 128 chars.
00242  */
00243 void iso_volume_set_application_id(struct iso_volume *volume,
00244                      const char *application_id);
00245 
00246 /**
00247  * Fill copyright information for the volume. Usually this refers
00248  * to a file on disc. Up to 37 characters.
00249  */
00250 void iso_volume_set_copyright_file_id(struct iso_volume *volume,
00251                      const char *copyright_file_id);
00252 
00253 /**
00254  * Fill abstract information for the volume. Usually this refers
00255  * to a file on disc. Up to 37 characters.
00256  */
00257 void iso_volume_set_abstract_file_id(struct iso_volume *volume,
00258                      const char *abstract_file_id);
00259 
00260 /**
00261  * Fill biblio information for the volume. Usually this refers
00262  * to a file on disc. Up to 37 characters.
00263  */
00264 void iso_volume_set_biblio_file_id(struct iso_volume *volume,
00265                      const char *biblio_file_id);
00266 
00267 /**
00268  * Create a bootable volume by adding a El-Torito boot image.
00269  * 
00270  * \param volume The volume to make bootable.
00271  * \param image The tree node with the file to use as default boot image.
00272  * \param type The boot media type. This can be one of 3 types:
00273  *             - Floppy emulation: Boot image files must be exactly
00274  *               1200 kB, 1440 kB or 2880 kB.
00275  *             - Hard disc emulation: The image must begin with a master
00276  *               boot record with a single image.
00277  *             - No emulation. You should specify load segment and load size
00278  *               of image.
00279  * \param dir The directory node where the boot catalog will be located
00280  *            in image. Usually both boot catalog and boot image will be
00281  *            located in the same dir, maybe /boot.
00282  * \param name The name of the boot catalog.
00283  * 
00284  * \return The default El-Torito bootable image. If specified image file
00285  *         seems to be not correct, this returns NULL and libisofs_errno
00286  *         is set propertly.
00287  * 
00288  * \pre \p volume is a volume without any boot catalog yet
00289  * \pre \p image is a file tree node already inserted in the volume tree.
00290  * \pre \p dir is a directory node already inserted in the volume tree.
00291  * \pre \p name There isn't any dir child with the same name.
00292  * 
00293  */
00294 struct el_torito_boot_image *
00295 iso_volume_create_boot_catalog(struct iso_volume *volume, 
00296                                struct iso_tree_node *image,
00297                                enum eltorito_boot_media_type type,
00298                                struct iso_tree_node_dir *dir, 
00299                                char *name);
00300 
00301 /**
00302  * Sets the load segment for the initial boot image. This is only for
00303  * no emulation boot images, and is a NOP for other image types.
00304  */
00305 void
00306 el_torito_set_load_seg(struct el_torito_boot_image *bootimg, int segment);
00307 
00308 /**
00309  * Sets the number of sectors (512b) to be load at load segment during
00310  * the initial boot procedure. This is only for
00311  * no emulation boot images, and is a NOP for other image types.
00312  */
00313 void
00314 el_torito_set_load_size(struct el_torito_boot_image *bootimg, int sectors);
00315 
00316 /**
00317  * Marks the specified boot image as not bootable
00318  */
00319 void
00320 el_torito_set_no_bootable(struct el_torito_boot_image *bootimg);
00321 
00322 /**
00323  * Specifies that this image needs to be patched. This involves the writting
00324  * of a 56 bytes boot information table at offset 8 of the boot image file.
00325  * Be aware that libisofs will modify original boot image file, so do a backup
00326  * if needed.
00327  * This is needed for isolinux boot images.
00328  */
00329 void
00330 el_torito_set_write_boot_info(struct el_torito_boot_image *bootimg);
00331 
00332 /**
00333  * Locate a node by its path on disc.
00334  * 
00335  * \param volume The volume to search in.
00336  * \param path The path, in the image, of the file.
00337  *
00338  * \return The node found or NULL.
00339  *
00340  * TODO we need a way to allow developers know which kind of node is.
00341  * Think about this when designing the read api 
00342  */
00343 struct iso_tree_node *iso_tree_volume_path_to_node(struct iso_volume *volume, const char *path);
00344 
00345 /**
00346  * Add a file or a directory (recursively) to a volume by specifying its path on the volume.
00347  *
00348  * \param volume The volume to add the file to.
00349  * \param disc_path The path on the disc at which to add the disc.
00350  * \param path The path, on the local filesystem, of the file.
00351  *
00352  * \return The node for the file or NULL if the parent doesn't exists on the disc.
00353  */
00354 //struct iso_tree_node *iso_tree_volume_add_path(struct iso_volume *volume,
00355 //                                  const char *disc_path,
00356 //                                  const char *path);
00357 
00358 /**
00359  * Creates a new, empty directory on the volume.
00360  *
00361  * \param volume The volume to add the directory to.
00362  * \param disc_path The path on the volume at which to add the directory.
00363  *
00364  * \return A pointer to the newly created directory.
00365  */
00366 //struct iso_tree_node *iso_tree_volume_add_new_dir(struct iso_volume *volume,
00367 //                                  const char *disc_path);
00368 
00369 /**
00370  * Create a new Volume Set consisting of only one volume.
00371  * @param volume The first and only volume for the volset to contain.
00372  * @param volset_id The Volume Set ID.
00373  * @return A new iso_volset.
00374  */
00375 struct iso_volset *iso_volset_new(struct iso_volume *volume,
00376                                   const char *volset_id);
00377 
00378 
00379 /**
00380  * Creates a new root dir for a filesystem tree
00381  */
00382 struct iso_tree_node_dir *iso_tree_new_root();
00383 
00384 /**
00385  * Add a file to a directory.
00386  *
00387  * \param path The path, on the local filesystem, of the file.
00388  * 
00389  * \pre \p parent is non-NULL.
00390  * \pre \p path is non-NULL.
00391  * \return An iso_tree_node_file whose path is \p path and whose parent is 
00392  *         \p parent. 
00393  *         On error, returns NULL and libisofs_errno is set appropriately:
00394  *          NO_FILE if path doesn't point to a valid file.
00395  *          NO_READ_ACCESS if user haven't read access on file
00396  *          UNEXPECTED_FILE_TYPE if path doesn't point to a regular file
00397  */
00398 struct iso_tree_node *iso_tree_add_file(struct iso_tree_node_dir *parent, 
00399                     const char *path);
00400 
00401 /**
00402  * Add a symbolic link to a directory.
00403  * 
00404  * \param name The name of the symbolic link
00405  * \param dest The distination of the link, i.e., the file this link points
00406  *             to
00407  * 
00408  * \pre \p parent, name and dest are non-NULL.
00409  * 
00410  * \return An iso_tree_node_symlink
00411  */
00412 struct iso_tree_node *iso_tree_add_symlink(struct iso_tree_node_dir *parent, 
00413                     const char *name, const char *dest);
00414 
00415 /**
00416  * Add a new, empty directory to the tree.
00417  *
00418  * \pre \p parent is non-NULL.
00419  * \pre \p name is unique among the children and files belonging to \p parent.
00420  *  Also, it doesn't contain '/' characters.
00421  *
00422  * \post \p parent contains a child directory whose name is \p name and whose
00423  *  POSIX attributes are the same as \p parent's.
00424  * \return a pointer to the newly created directory.
00425  */
00426 struct iso_tree_node_dir *iso_tree_add_dir(struct iso_tree_node_dir *parent, 
00427                     const char *name);
00428 
00429 /* TODO iso_tree_new_special */
00430 
00431 /**
00432  * Add a file to a directory.
00433  *
00434  * \param path The path, on the local filesystem, of the file.
00435  *
00436  * \pre \p parent is non-NULL.
00437  * \pre \p path is non-NULL and is a valid path to a file or directory on the local
00438  *  filesystem.
00439  * \return An iso_tree_node whose path is \p path and whose parent is \p parent.
00440  *         On error, returns NULL and libisofs_errno is set appropriately:
00441  *          NO_FILE if path doesn't point to a valid file.
00442  *          NO_READ_ACCESS if user haven't read access on file
00443  *          UNEXPECTED_FILE_TYPE if path refers to non  supported file type 
00444  *          (at the momment, only dirs, symlinks and regular
00445  *          files are supported).
00446  */
00447 struct iso_tree_node *iso_tree_add_node(struct iso_tree_node_dir *parent,
00448                     const char *path);
00449 
00450 /**
00451  * Recursively add an existing directory to the tree.
00452  * Warning: when using this, you'll lose pointers to files or subdirectories.
00453  * If you want to have pointers to all files and directories,
00454  * use iso_tree_add_file, iso_tree_add_node and iso_tree_add_dir.
00455  *
00456  * \param path The path, on the local filesystem, of the directory to add.
00457  *
00458  * \pre \p parent is non-NULL.
00459  * \pre \p path is non-NULL and is a valid path to a directory on the local
00460  *  filesystem.
00461  */
00462 void iso_tree_radd_dir(struct iso_tree_node_dir *parent, const char *path, 
00463                        struct iso_tree_radd_dir_behavior *behavior);
00464 
00465 /**
00466  * Set the name of a tree node (using the current locale).
00467  */
00468 void iso_tree_node_set_name(struct iso_tree_node *node, const char *name);
00469 
00470 /**
00471  * Set if the node will be hidden in RR/ISO tree, Joliet tree or both.
00472  * 
00473  * If the file is setted as hidden in one tree, it won't be included there, so
00474  * it won't be visible in a OS accessing CD using that tree. For example,
00475  * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see
00476  * what is recorded on CD, while MS Windows make use of the Joliet tree. If a
00477  * file is hidden only in Joliet, it won't be visible in Windows systems,
00478  * while still visible in Linux.
00479  * 
00480  * If a file is hidden in both trees, it won't be written to image.
00481  * 
00482  * \param node The node that is to be hidden.
00483  * \param hide_attrs hide_node_flag's to set the trees in which file
00484  *        will be hidden.
00485  */
00486 void iso_tree_node_set_hidden(struct iso_tree_node *node, int hide_attrs);
00487 
00488 /**
00489  * Set the group id for the node. This attribute is only useful when 
00490  * Rock Ridge extensions are enabled.
00491  */
00492 void iso_tree_node_set_gid(struct iso_tree_node *node, gid_t gid);
00493 
00494 /**
00495  * Set the user id for the node. This attribute is only useful when 
00496  * Rock Ridge extensions are enabled.
00497  */
00498 void iso_tree_node_set_uid(struct iso_tree_node *node, uid_t uid);
00499 
00500 /**
00501  * Set the permissions for the node. This attribute is only useful when 
00502  * Rock Ridge extensions are enabled.
00503  * 
00504  * \param mode bitmask with the permissions of the node, as specified
00505  *             in 'man 2 stat'. The file type bitfields will be ignored,
00506  *             only file permissions will be modified.
00507  */
00508 void iso_tree_node_set_permissions(struct iso_tree_node *node, mode_t mode);
00509 
00510 /**
00511  * Sets the order in which a node will be written on image. High weihted files
00512  * will be written first, so in a disc them will be written near the center.
00513  * 
00514  * \param node The node which weight will be changed. If it's a dir, this 
00515  *             function will change the weight of all its children. For nodes
00516  *             other that dirs or regular files, this function has no effect.
00517  * \param w The weight as a integer number, the greater this value is, the 
00518  *          closer from the begining of image the file will be written.
00519  */
00520 void iso_tree_node_set_sort_weight(struct iso_tree_node *node, int w);
00521 
00522 /**
00523  * Recursively print a directory to stdout.
00524  * \param spaces The initial number of spaces on the left. Set to 0 if you
00525  *  supply a root directory.
00526  */
00527 void iso_tree_print(const struct iso_tree_node *root, int spaces);
00528 
00529 /** Create a burn_source which can be used as a data source for a track
00530  *
00531  * The volume set used to create the libburn_source can _not_ be modified
00532  * until the libburn_source is freed.
00533  *
00534  * \param volumeset The volume set from which you want to write
00535  * \param opts The options for image generation
00536  *
00537  * \pre \p volumeset is non-NULL
00538  * \pre \p volnum is less than \p volset->volset_size.
00539  * \return A burn_source to be used for the data source for a track
00540  */
00541 struct burn_source* iso_source_new_ecma119(struct iso_volset *volumeset,
00542                         struct ecma119_source_opts *opts);
00543 
00544 #endif /* LIBISO_LIBISOFS_H */

Generated on Wed Oct 10 15:53:16 2007 for libisofs by  doxygen 1.5.2