00001 /* 00002 * Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic 00003 * 00004 * This file is part of the libisofs project; you can redistribute it and/or 00005 * modify it under the terms of the GNU General Public License version 2 as 00006 * published by the Free Software Foundation. See COPYING file for details. 00007 */ 00008 #ifndef LIBISO_LIBISOFS_H_ 00009 #define LIBISO_LIBISOFS_H_ 00010 00011 #include <sys/stat.h> 00012 #include <stdint.h> 00013 #include <stdlib.h> 00014 00015 struct burn_source; 00016 00017 /** 00018 * Context for image creation. It holds the files that will be added to image, 00019 * and several options to control libisofs behavior. 00020 * 00021 * @since 0.6.2 00022 */ 00023 typedef struct Iso_Image IsoImage; 00024 00025 /* 00026 * A node in the iso tree, i.e. a file that will be written to image. 00027 * 00028 * It can represent any kind of files. When needed, you can get the type with 00029 * iso_node_get_type() and cast it to the appropiate subtype. Useful macros 00030 * are provided, see below. 00031 * 00032 * @since 0.6.2 00033 */ 00034 typedef struct Iso_Node IsoNode; 00035 00036 /** 00037 * A directory in the iso tree. It is an special type of IsoNode and can be 00038 * casted to it in any case. 00039 * 00040 * @since 0.6.2 00041 */ 00042 typedef struct Iso_Dir IsoDir; 00043 00044 /** 00045 * A symbolic link in the iso tree. It is an special type of IsoNode and can be 00046 * casted to it in any case. 00047 * 00048 * @since 0.6.2 00049 */ 00050 typedef struct Iso_Symlink IsoSymlink; 00051 00052 /** 00053 * A regular file in the iso tree. It is an special type of IsoNode and can be 00054 * casted to it in any case. 00055 * 00056 * @since 0.6.2 00057 */ 00058 typedef struct Iso_File IsoFile; 00059 00060 /** 00061 * An special file in the iso tree. This is used to represent any POSIX file 00062 * other that regular files, directories or symlinks, i.e.: socket, block and 00063 * character devices, and fifos. 00064 * It is an special type of IsoNode and can be casted to it in any case. 00065 * 00066 * @since 0.6.2 00067 */ 00068 typedef struct Iso_Special IsoSpecial; 00069 00070 /** 00071 * The type of an IsoNode. 00072 * 00073 * When an user gets an IsoNode from an image, (s)he can use 00074 * iso_node_get_type() to get the current type of the node, and then 00075 * cast to the appropriate subtype. For example: 00076 * 00077 * ... 00078 * IsoNode *node; 00079 * res = iso_dir_iter_next(iter, &node); 00080 * if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) { 00081 * IsoDir *dir = (IsoDir *)node; 00082 * ... 00083 * } 00084 * 00085 * @since 0.6.2 00086 */ 00087 enum IsoNodeType { 00088 LIBISO_DIR, 00089 LIBISO_FILE, 00090 LIBISO_SYMLINK, 00091 LIBISO_SPECIAL, 00092 LIBISO_BOOT 00093 }; 00094 00095 /* macros to check node type */ 00096 #define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR) 00097 #define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE) 00098 #define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK) 00099 #define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL) 00100 #define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT) 00101 00102 /* macros for safe downcasting */ 00103 #define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL)) 00104 #define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL)) 00105 #define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL)) 00106 #define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL)) 00107 00108 #define ISO_NODE(n) ((IsoNode*)n) 00109 00110 /** 00111 * Context for iterate on directory children. 00112 * @see iso_dir_get_children() 00113 * 00114 * @since 0.6.2 00115 */ 00116 typedef struct Iso_Dir_Iter IsoDirIter; 00117 00118 /** 00119 * It represents an El-Torito boot image. 00120 * 00121 * @since 0.6.2 00122 */ 00123 typedef struct el_torito_boot_image ElToritoBootImage; 00124 00125 /** 00126 * An special type of IsoNode that acts as a placeholder for an El-Torito 00127 * boot catalog. Once written, it will appear as a regular file. 00128 * 00129 * @since 0.6.2 00130 */ 00131 typedef struct Iso_Boot IsoBoot; 00132 00133 /** 00134 * Flag used to hide a file in the RR/ISO or Joliet tree. 00135 * 00136 * @see iso_node_set_hidden 00137 * @since 0.6.2 00138 */ 00139 enum IsoHideNodeFlag { 00140 /** Hide the node in the ECMA-119 / RR tree */ 00141 LIBISO_HIDE_ON_RR = 1 << 0, 00142 /** Hide the node in the Joliet tree, if Joliet extension are enabled */ 00143 LIBISO_HIDE_ON_JOLIET = 1 << 1, 00144 /** Hide the node in the ISO-9660:1999 tree, if that format is enabled */ 00145 LIBISO_HIDE_ON_1999 = 1 << 2 00146 }; 00147 00148 /** 00149 * El-Torito bootable image type. 00150 * 00151 * @since 0.6.2 00152 */ 00153 enum eltorito_boot_media_type { 00154 ELTORITO_FLOPPY_EMUL, 00155 ELTORITO_HARD_DISC_EMUL, 00156 ELTORITO_NO_EMUL 00157 }; 00158 00159 /** 00160 * Replace mode used when addding a node to a file. 00161 * This controls how libisofs will act when you tried to add to a dir a file 00162 * with the same name that an existing file. 00163 * 00164 * @since 0.6.2 00165 */ 00166 enum iso_replace_mode { 00167 /** 00168 * Never replace an existing node, and instead fail with 00169 * ISO_NODE_NAME_NOT_UNIQUE. 00170 */ 00171 ISO_REPLACE_NEVER, 00172 /** 00173 * Always replace the old node with the new. 00174 */ 00175 ISO_REPLACE_ALWAYS, 00176 /** 00177 * Replace with the new node if it is the same file type 00178 */ 00179 ISO_REPLACE_IF_SAME_TYPE, 00180 /** 00181 * Replace with the new node if it is the same file type and its ctime 00182 * is newer than the old one. 00183 */ 00184 ISO_REPLACE_IF_SAME_TYPE_AND_NEWER, 00185 /** 00186 * Replace with the new node if its ctime is newer than the old one. 00187 */ 00188 ISO_REPLACE_IF_NEWER 00189 /* 00190 * TODO #00006 define more values 00191 * -if both are dirs, add contents (and what to do with conflicts?) 00192 */ 00193 }; 00194 00195 /** 00196 * Options for image written. 00197 * @see iso_write_opts_new() 00198 * @since 0.6.2 00199 */ 00200 typedef struct iso_write_opts IsoWriteOpts; 00201 00202 /** 00203 * Options for image reading or import. 00204 * @see iso_read_opts_new() 00205 * @since 0.6.2 00206 */ 00207 typedef struct iso_read_opts IsoReadOpts; 00208 00209 /** 00210 * Source for image reading. 00211 * 00212 * @see struct iso_data_source 00213 * @since 0.6.2 00214 */ 00215 typedef struct iso_data_source IsoDataSource; 00216 00217 /** 00218 * Data source used by libisofs for reading an existing image. 00219 * 00220 * It offers homogeneous read access to arbitrary blocks to different sources 00221 * for images, such as .iso files, CD/DVD drives, etc... 00222 * 00223 * To create a multisession image, libisofs needs a IsoDataSource, that the 00224 * user must provide. The function iso_data_source_new_from_file() constructs 00225 * an IsoDataSource that uses POSIX I/O functions to access data. You can use 00226 * it with regular .iso images, and also with block devices that represent a 00227 * drive. 00228 * 00229 * @since 0.6.2 00230 */ 00231 struct iso_data_source 00232 { 00233 00234 /* reserved for future usage, set to 0 */ 00235 int version; 00236 00237 /** 00238 * Reference count for the data source. Should be 1 when a new source 00239 * is created. Don't access it directly, but with iso_data_source_ref() 00240 * and iso_data_source_unref() functions. 00241 */ 00242 unsigned int refcount; 00243 00244 /** 00245 * Opens the given source. You must open() the source before any attempt 00246 * to read data from it. The open is the right place for grabbing the 00247 * underlying resources. 00248 * 00249 * @return 00250 * 1 if success, < 0 on error 00251 */ 00252 int (*open)(IsoDataSource *src); 00253 00254 /** 00255 * Close a given source, freeing all system resources previously grabbed in 00256 * open(). 00257 * 00258 * @return 00259 * 1 if success, < 0 on error 00260 */ 00261 int (*close)(IsoDataSource *src); 00262 00263 /** 00264 * Read an arbitrary block (2048 bytes) of data from the source. 00265 * 00266 * @param lba 00267 * Block to be read. 00268 * @param buffer 00269 * Buffer where the data will be written. It should have at least 00270 * 2048 bytes. 00271 * @return 00272 * 1 if success, < 0 on error 00273 */ 00274 int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer); 00275 00276 /** 00277 * Clean up the source specific data. Never call this directly, it is 00278 * automatically called by iso_data_source_unref() when refcount reach 00279 * 0. 00280 */ 00281 void (*free_data)(IsoDataSource *); 00282 00283 /** Source specific data */ 00284 void *data; 00285 }; 00286 00287 /** 00288 * Return information for image. This is optionally allocated by libisofs, 00289 * as a way to inform user about the features of an existing image, such as 00290 * extensions present, size, ... 00291 * 00292 * @see iso_image_import() 00293 * @since 0.6.2 00294 */ 00295 typedef struct iso_read_image_features IsoReadImageFeatures; 00296 00297 /** 00298 * POSIX abstraction for source files. 00299 * 00300 * @see struct iso_file_source 00301 * @since 0.6.2 00302 */ 00303 typedef struct iso_file_source IsoFileSource; 00304 00305 /** 00306 * Abstract for source filesystems. 00307 * 00308 * @see struct iso_filesystem 00309 * @since 0.6.2 00310 */ 00311 typedef struct iso_filesystem IsoFilesystem; 00312 00313 /** 00314 * Interface that defines the operations (methods) available for an 00315 * IsoFileSource. 00316 * 00317 * @see struct IsoFileSource_Iface 00318 * @since 0.6.2 00319 */ 00320 typedef struct IsoFileSource_Iface IsoFileSourceIface; 00321 00322 /** 00323 * IsoFilesystem implementation to deal with ISO images, and to offer a way to 00324 * access specific information of the image, such as several volume attributes, 00325 * extensions being used, El-Torito artifacts... 00326 * 00327 * @since 0.6.2 00328 */ 00329 typedef IsoFilesystem IsoImageFilesystem; 00330 00331 /** 00332 * See IsoFilesystem->get_id() for info about this. 00333 * @since 0.6.2 00334 */ 00335 extern unsigned int iso_fs_global_id; 00336 00337 /** 00338 * An IsoFilesystem is a handler for a source of files, or a "filesystem". 00339 * That is defined as a set of files that are organized in a hierarchical 00340 * structure. 00341 * 00342 * A filesystem allows libisofs to access files from several sources in 00343 * an homogeneous way, thus abstracting the underlying operations needed to 00344 * access and read file contents. Note that this doesn't need to be tied 00345 * to the disc filesystem used in the partition being accessed. For example, 00346 * we have an IsoFilesystem implementation to access any mounted filesystem, 00347 * using standard Linux functions. It is also legal, of course, to implement 00348 * an IsoFilesystem to deal with a specific filesystem over raw partitions. 00349 * That is what we do, for example, to access an ISO Image. 00350 * 00351 * Each file inside an IsoFilesystem is represented as an IsoFileSource object, 00352 * that defines POSIX-like interface for accessing files. 00353 * 00354 * @since 0.6.2 00355 */ 00356 struct iso_filesystem 00357 { 00358 /** 00359 * Type of filesystem. 00360 * "file" -> local filesystem 00361 * "iso " -> iso image filesystem 00362 */ 00363 char type[4]; 00364 00365 /* reserved for future usage, set to 0 */ 00366 int version; 00367 00368 /** 00369 * Get the root of a filesystem. 00370 * 00371 * @return 00372 * 1 on success, < 0 on error 00373 */ 00374 int (*get_root)(IsoFilesystem *fs, IsoFileSource **root); 00375 00376 /** 00377 * Retrieve a file from its absolute path inside the filesystem. 00378 * 00379 * @return 00380 * 1 success, < 0 error 00381 * Error codes: 00382 * ISO_FILE_ACCESS_DENIED 00383 * ISO_FILE_BAD_PATH 00384 * ISO_FILE_DOESNT_EXIST 00385 * ISO_OUT_OF_MEM 00386 * ISO_FILE_ERROR 00387 * ISO_NULL_POINTER 00388 */ 00389 int (*get_by_path)(IsoFilesystem *fs, const char *path, 00390 IsoFileSource **file); 00391 00392 /** 00393 * Get filesystem identifier. 00394 * 00395 * If the filesystem is able to generate correct values of the st_dev 00396 * and st_ino fields for the struct stat of each file, this should 00397 * return an unique number, greater than 0. 00398 * 00399 * To get a identifier for your filesystem implementation you should 00400 * use iso_fs_global_id, incrementing it by one each time. 00401 * 00402 * Otherwise, if you can't ensure values in the struct stat are valid, 00403 * this should return 0. 00404 */ 00405 unsigned int (*get_id)(IsoFilesystem *fs); 00406 00407 /** 00408 * Opens the filesystem for several read operations. Calling this funcion 00409 * is not needed at all, each time that the underlying system resource 00410 * needs to be accessed, it is openned propertly. 00411 * However, if you plan to execute several operations on the filesystem, 00412 * it is a good idea to open it previously, to prevent several open/close 00413 * operations to occur. 00414 * 00415 * @return 1 on success, < 0 on error 00416 */ 00417 int (*open)(IsoFilesystem *fs); 00418 00419 /** 00420 * Close the filesystem, thus freeing all system resources. You should 00421 * call this function if you have previously open() it. 00422 * Note that you can open()/close() a filesystem several times. 00423 * 00424 * @return 1 on success, < 0 on error 00425 */ 00426 int (*close)(IsoFilesystem *fs); 00427 00428 /** 00429 * Free implementation specific data. Should never be called by user. 00430 * Use iso_filesystem_unref() instead. 00431 */ 00432 void (*free)(IsoFilesystem *fs); 00433 00434 /* internal usage, do never access them directly */ 00435 unsigned int refcount; 00436 void *data; 00437 }; 00438 00439 /** 00440 * Interface definition for an IsoFileSource. Defines the POSIX-like function 00441 * to access files and abstract underlying source. 00442 * 00443 * @since 0.6.2 00444 */ 00445 struct IsoFileSource_Iface 00446 { 00447 /* reserved for future usage, set to 0 */ 00448 int version; 00449 00450 /** 00451 * Get the path, relative to the filesystem this file source belongs to. 00452 * 00453 * @return 00454 * the path of the FileSource inside the filesystem, it should be 00455 * freed when no more needed. 00456 */ 00457 char* (*get_path)(IsoFileSource *src); 00458 00459 /** 00460 * Get the name of the file, with the dir component of the path. 00461 * 00462 * @return 00463 * the name of the file, it should be freed when no more needed. 00464 */ 00465 char* (*get_name)(IsoFileSource *src); 00466 00467 /** 00468 * Get information about the file. It is equivalent to lstat(2). 00469 * 00470 * @return 00471 * 1 success, < 0 error 00472 * Error codes: 00473 * ISO_FILE_ACCESS_DENIED 00474 * ISO_FILE_BAD_PATH 00475 * ISO_FILE_DOESNT_EXIST 00476 * ISO_OUT_OF_MEM 00477 * ISO_FILE_ERROR 00478 * ISO_NULL_POINTER 00479 */ 00480 int (*lstat)(IsoFileSource *src, struct stat *info); 00481 00482 /** 00483 * Get information about the file. If the file is a symlink, the info 00484 * returned refers to the destination. It is equivalent to stat(2). 00485 * 00486 * @return 00487 * 1 success, < 0 error 00488 * Error codes: 00489 * ISO_FILE_ACCESS_DENIED 00490 * ISO_FILE_BAD_PATH 00491 * ISO_FILE_DOESNT_EXIST 00492 * ISO_OUT_OF_MEM 00493 * ISO_FILE_ERROR 00494 * ISO_NULL_POINTER 00495 */ 00496 int (*stat)(IsoFileSource *src, struct stat *info); 00497 00498 /** 00499 * Check if the process has access to read file contents. Note that this 00500 * is not necessarily related with (l)stat functions. For example, in a 00501 * filesystem implementation to deal with an ISO image, if the user has 00502 * read access to the image it will be able to read all files inside it, 00503 * despite of the particular permission of each file in the RR tree, that 00504 * are what the above functions return. 00505 * 00506 * @return 00507 * 1 if process has read access, < 0 on error 00508 * Error codes: 00509 * ISO_FILE_ACCESS_DENIED 00510 * ISO_FILE_BAD_PATH 00511 * ISO_FILE_DOESNT_EXIST 00512 * ISO_OUT_OF_MEM 00513 * ISO_FILE_ERROR 00514 * ISO_NULL_POINTER 00515 */ 00516 int (*access)(IsoFileSource *src); 00517 00518 /** 00519 * Opens the source. 00520 * @return 1 on success, < 0 on error 00521 * Error codes: 00522 * ISO_FILE_ALREADY_OPENNED 00523 * ISO_FILE_ACCESS_DENIED 00524 * ISO_FILE_BAD_PATH 00525 * ISO_FILE_DOESNT_EXIST 00526 * ISO_OUT_OF_MEM 00527 * ISO_FILE_ERROR 00528 * ISO_NULL_POINTER 00529 */ 00530 int (*open)(IsoFileSource *src); 00531 00532 /** 00533 * Close a previuously openned file 00534 * @return 1 on success, < 0 on error 00535 * Error codes: 00536 * ISO_FILE_ERROR 00537 * ISO_NULL_POINTER 00538 * ISO_FILE_NOT_OPENNED 00539 */ 00540 int (*close)(IsoFileSource *src); 00541 00542 /** 00543 * Attempts to read up to count bytes from the given source into 00544 * the buffer starting at buf. 00545 * 00546 * The file src must be open() before calling this, and close() when no 00547 * more needed. Not valid for dirs. On symlinks it reads the destination 00548 * file. 00549 * 00550 * @return 00551 * number of bytes read, 0 if EOF, < 0 on error 00552 * Error codes: 00553 * ISO_FILE_ERROR 00554 * ISO_NULL_POINTER 00555 * ISO_FILE_NOT_OPENNED 00556 * ISO_WRONG_ARG_VALUE -> if count == 0 00557 * ISO_FILE_IS_DIR 00558 * ISO_OUT_OF_MEM 00559 * ISO_INTERRUPTED 00560 */ 00561 int (*read)(IsoFileSource *src, void *buf, size_t count); 00562 00563 /** 00564 * Read a directory. 00565 * 00566 * Each call to this function will return a new children, until we reach 00567 * the end of file (i.e, no more children), in that case it returns 0. 00568 * 00569 * The dir must be open() before calling this, and close() when no more 00570 * needed. Only valid for dirs. 00571 * 00572 * Note that "." and ".." children MUST NOT BE returned. 00573 * 00574 * @param child 00575 * pointer to be filled with the given child. Undefined on error or OEF 00576 * @return 00577 * 1 on success, 0 if EOF (no more children), < 0 on error 00578 * Error codes: 00579 * ISO_FILE_ERROR 00580 * ISO_NULL_POINTER 00581 * ISO_FILE_NOT_OPENNED 00582 * ISO_FILE_IS_NOT_DIR 00583 * ISO_OUT_OF_MEM 00584 */ 00585 int (*readdir)(IsoFileSource *src, IsoFileSource **child); 00586 00587 /** 00588 * Read the destination of a symlink. You don't need to open the file 00589 * to call this. 00590 * 00591 * @param buf 00592 * allocated buffer of at least bufsiz bytes. 00593 * The dest. will be copied there, and it will be NULL-terminated 00594 * @param bufsiz 00595 * characters to be copied. Destination link will be truncated if 00596 * it is larger than given size. This include the \0 character. 00597 * @return 00598 * 1 on success, < 0 on error 00599 * Error codes: 00600 * ISO_FILE_ERROR 00601 * ISO_NULL_POINTER 00602 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 00603 * ISO_FILE_IS_NOT_SYMLINK 00604 * ISO_OUT_OF_MEM 00605 * ISO_FILE_BAD_PATH 00606 * ISO_FILE_DOESNT_EXIST 00607 * 00608 */ 00609 int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz); 00610 00611 /** 00612 * Get the filesystem for this source. No extra ref is added, so you 00613 * musn't unref the IsoFilesystem. 00614 * 00615 * @return 00616 * The filesystem, NULL on error 00617 */ 00618 IsoFilesystem* (*get_filesystem)(IsoFileSource *src); 00619 00620 /** 00621 * Free implementation specific data. Should never be called by user. 00622 * Use iso_file_source_unref() instead. 00623 */ 00624 void (*free)(IsoFileSource *src); 00625 00626 /* 00627 * TODO #00004 Add a get_mime_type() function. 00628 * This can be useful for GUI apps, to choose the icon of the file 00629 */ 00630 }; 00631 00632 /** 00633 * An IsoFile Source is a POSIX abstraction of a file. 00634 * 00635 * @since 0.6.2 00636 */ 00637 struct iso_file_source 00638 { 00639 const IsoFileSourceIface *class; 00640 int refcount; 00641 void *data; 00642 }; 00643 00644 /** 00645 * Initialize libisofs. You must call this before any usage of the library. 00646 * @return 1 on success, < 0 on error 00647 * 00648 * @since 0.6.2 00649 */ 00650 int iso_init(); 00651 00652 /** 00653 * Finalize libisofs. 00654 * 00655 * @since 0.6.2 00656 */ 00657 void iso_finish(); 00658 00659 /** 00660 * Create a new image, empty. 00661 * 00662 * The image will be owned by you and should be unref() when no more needed. 00663 * 00664 * @param name 00665 * Name of the image. This will be used as volset_id and volume_id. 00666 * @param image 00667 * Location where the image pointer will be stored. 00668 * @return 00669 * 1 sucess, < 0 error 00670 * 00671 * @since 0.6.2 00672 */ 00673 int iso_image_new(const char *name, IsoImage **image); 00674 00675 00676 /** 00677 * The following two functions three macros are utilities to help ensuring 00678 * version match of application, compile time header, and runtime library. 00679 */ 00680 /** 00681 * Get version of the libisofs library at runtime. 00682 * 00683 * @since 0.6.2 00684 */ 00685 void iso_lib_version(int *major, int *minor, int *micro); 00686 00687 /** 00688 * Check at runtime if the library is ABI compatible with the given version. 00689 * 00690 * @return 00691 * 1 lib is compatible, 0 is not. 00692 * 00693 * @since 0.6.2 00694 */ 00695 int iso_lib_is_compatible(int major, int minor, int micro); 00696 00697 00698 /** 00699 * These three release version numbers tell the revision of this header file 00700 * and of the API it describes. They are memorized by applications at 00701 * compile time. 00702 * They must show the same values as these symbols in ./configure.ac 00703 * LIBISOFS_MAJOR_VERSION=... 00704 * LIBISOFS_MINOR_VERSION=... 00705 * LIBISOFS_MICRO_VERSION=... 00706 * Note to anybody who does own work inside libisofs: 00707 * Any change of configure.ac or libisofs.h has to keep up this equality ! 00708 * 00709 * Before usage of these macros on your code, please read the usage discussion 00710 * below. 00711 * 00712 * @since 0.6.2 00713 */ 00714 #define iso_lib_header_version_major 0 00715 #define iso_lib_header_version_minor 6 00716 #define iso_lib_header_version_micro 2 00717 00718 /** 00719 * Usage discussion: 00720 * 00721 * Some developers of the libburnia project have differing opinions how to 00722 * ensure the compatibility of libaries and applications. 00723 * 00724 * It is about whether to use at compile time and at runtime the version 00725 * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso 00726 * advises to use other means. 00727 * 00728 * At compile time: 00729 * 00730 * Vreixo Formoso advises to leave proper version matching to properly 00731 * programmed checks in the the application's build system, which will 00732 * eventually refuse compilation. 00733 * 00734 * Thomas Schmitt advises to use the macros defined here for comparison with 00735 * the application's requirements of library revisions and to eventually 00736 * break compilation. 00737 * 00738 * Both advises are combinable. I.e. be master of your build system and have 00739 * #if checks in the source code of your application, nevertheless. 00740 * 00741 * At runtime (via iso_lib_is_compatible()): 00742 * 00743 * Vreixo Formoso advises to compare the application's requirements of 00744 * library revisions with the runtime library. This is to allow runtime 00745 * libraries which are young enough for the application but too old for 00746 * the lib*.h files seen at compile time. 00747 * 00748 * Thomas Schmitt advises to compare the header revisions defined here with 00749 * the runtime library. This is to enforce a strictly monotonous chain of 00750 * revisions from app to header to library, at the cost of excluding some older 00751 * libraries. 00752 * 00753 * These two advises are mutually exclusive. 00754 */ 00755 00756 00757 /** 00758 * Creates an IsoWriteOpts for writing an image. You should set the options 00759 * desired with the correspondent setters. 00760 * 00761 * Options by default are determined by the selected profile. Fifo size is set 00762 * by default to 2 MB. 00763 * 00764 * @param opts 00765 * Pointer to the location where the newly created IsoWriteOpts will be 00766 * stored. You should free it with iso_write_opts_free() when no more 00767 * needed. 00768 * @param profile 00769 * Default profile for image creation. For now the following values are 00770 * defined: 00771 * ---> 0 [BASIC] 00772 * No extensions are enabled, and ISO level is set to 1. Only suitable 00773 * for usage for very old and limited systems (like MS-DOS), or by a 00774 * start point from which to set your custom options. 00775 * ---> 1 [BACKUP] 00776 * POSIX compatibility for backup. Simple settings, ISO level is set to 00777 * 2 and RR extensions are enabled. Useful for backup purposes. 00778 * ---> 2 [DISTRIBUTION] 00779 * Setting for information distribution. Both RR and Joliet are enabled 00780 * to maximize compatibility with most systems. Permissions are set to 00781 * default values, and timestamps to the time of recording. 00782 * @return 00783 * 1 success, < 0 error 00784 * 00785 * @since 0.6.2 00786 */ 00787 int iso_write_opts_new(IsoWriteOpts **opts, int profile); 00788 00789 /** 00790 * Free an IsoWriteOpts previously allocated with iso_write_opts_new(). 00791 * 00792 * @since 0.6.2 00793 */ 00794 void iso_write_opts_free(IsoWriteOpts *opts); 00795 00796 /** 00797 * Set the ISO-9960 level to write at. 00798 * 00799 * @param level 00800 * -> 1 for higher compatibility with old systems. With this level 00801 * filenames are restricted to 8.3 characters. 00802 * -> 2 to allow up to 31 filename characters. 00803 * @return 00804 * 1 success, < 0 error 00805 * 00806 * @since 0.6.2 00807 */ 00808 int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level); 00809 00810 /** 00811 * Whether to use or not Rock Ridge extensions. 00812 * 00813 * This are standard extensions to ECMA-119, intended to add POSIX filesystem 00814 * features to ECMA-119 images. Thus, usage of this flag is highly recommended 00815 * for images used on GNU/Linux systems. With the usage of RR extension, the 00816 * resulting image will have long filenames (up to 255 characters), deeper 00817 * directory structure, POSIX permissions and owner info on files and 00818 * directories, support for symbolic links or special files... All that 00819 * attributes can be modified/setted with the appropiate function. 00820 * 00821 * @param enable 00822 * 1 to enable RR extension, 0 to not add them 00823 * @return 00824 * 1 success, < 0 error 00825 * 00826 * @since 0.6.2 00827 */ 00828 int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable); 00829 00830 /** 00831 * Whether to add the non-standard Joliet extension to the image. 00832 * 00833 * This extensions are heavily used in Microsoft Windows systems, so if you 00834 * plan to use your disc on such a system you should add this extension. 00835 * Usage of Joliet supplies longer filesystem length (up to 64 unicode 00836 * characters), and deeper directory structure. 00837 * 00838 * @param enable 00839 * 1 to enable Joliet extension, 0 to not add them 00840 * @return 00841 * 1 success, < 0 error 00842 * 00843 * @since 0.6.2 00844 */ 00845 int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable); 00846 00847 /** 00848 * Whether to use newer ISO-9660:1999 version. 00849 * 00850 * This is the second version of ISO-9660. It allows longer filenames and has 00851 * less restrictions than old ISO-9660. However, nobody is using it so there 00852 * are no much reasons to enable this. 00853 * 00854 * @since 0.6.2 00855 */ 00856 int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable); 00857 00858 /** 00859 * Omit the version number (";1") at the end of the ISO-9660 identifiers. 00860 * This breaks ECMA-119 specification, but version numbers are usually not 00861 * used, so it should work on most systems. Use with caution. 00862 * 00863 * @since 0.6.2 00864 */ 00865 int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit); 00866 00867 /** 00868 * Allow ISO-9660 directory hierarchy to be deeper than 8 levels. 00869 * This breaks ECMA-119 specification. Use with caution. 00870 * 00871 * @since 0.6.2 00872 */ 00873 int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow); 00874 00875 /** 00876 * Allow path in the ISO-9660 tree to have more than 255 characters. 00877 * This breaks ECMA-119 specification. Use with caution. 00878 * 00879 * @since 0.6.2 00880 */ 00881 int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow); 00882 00883 /** 00884 * Allow a single file or directory hierarchy to have up to 37 characters. 00885 * This is larger than the 31 characters allowed by ISO level 2, and the 00886 * extra space is taken from the version number, so this also forces 00887 * omit_version_numbers. 00888 * This breaks ECMA-119 specification and could lead to buffer overflow 00889 * problems on old systems. Use with caution. 00890 * 00891 * @since 0.6.2 00892 */ 00893 int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow); 00894 00895 /** 00896 * ISO-9660 forces filenames to have a ".", that separates file name from 00897 * extension. libisofs adds it if original filename doesn't has one. Set 00898 * this to 1 to prevent this behavior. 00899 * This breaks ECMA-119 specification. Use with caution. 00900 * 00901 * @since 0.6.2 00902 */ 00903 int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no); 00904 00905 /** 00906 * Allow lowercase characters in ISO-9660 filenames. By default, only 00907 * uppercase characters, numbers and a few other characters are allowed. 00908 * This breaks ECMA-119 specification. Use with caution. 00909 * 00910 * @since 0.6.2 00911 */ 00912 int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow); 00913 00914 /** 00915 * Allow all ASCII characters to be appear on an ISO-9660 filename. Note 00916 * that "/" and "\0" characters are never allowed, even in RR names. 00917 * This breaks ECMA-119 specification. Use with caution. 00918 * 00919 * @since 0.6.2 00920 */ 00921 int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow); 00922 00923 /** 00924 * Allow all characters to be part of Volume and Volset identifiers on 00925 * the Primary Volume Descriptor. This breaks ISO-9660 contraints, but 00926 * should work on modern systems. 00927 * 00928 * @since 0.6.2 00929 */ 00930 int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow); 00931 00932 /** 00933 * Allow paths in the Joliet tree to have more than 240 characters. 00934 * This breaks Joliet specification. Use with caution. 00935 * 00936 * @since 0.6.2 00937 */ 00938 int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow); 00939 00940 /** 00941 * Whether to sort files based on their weight. 00942 * 00943 * @see iso_node_set_sort_weight 00944 * @since 0.6.2 00945 */ 00946 int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort); 00947 00948 /** 00949 * Whether to set default values for files and directory permissions, gid and 00950 * uid. All these take one of three values: 0, 1 or 2. 00951 * 00952 * If 0, the corresponding attribute will be kept as setted in the IsoNode. 00953 * Unless you have changed it, it corresponds to the value on disc, so it 00954 * is suitable for backup purposes. If set to 1, the corresponding attrib. 00955 * will be changed by a default suitable value. Finally, if you set it to 00956 * 2, the attrib. will be changed with the value specified by the functioins 00957 * below. Note that for mode attributes, only the permissions are set, the 00958 * file type remains unchanged. 00959 * 00960 * @see iso_write_opts_set_default_dir_mode 00961 * @see iso_write_opts_set_default_file_mode 00962 * @see iso_write_opts_set_default_uid 00963 * @see iso_write_opts_set_default_gid 00964 * @since 0.6.2 00965 */ 00966 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, 00967 int file_mode, int uid, int gid); 00968 00969 /** 00970 * Set the mode to use on dirs when you set the replace_mode of dirs to 2. 00971 * 00972 * @see iso_write_opts_set_replace_mode 00973 * @since 0.6.2 00974 */ 00975 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); 00976 00977 /** 00978 * Set the mode to use on files when you set the replace_mode of files to 2. 00979 * 00980 * @see iso_write_opts_set_replace_mode 00981 * @since 0.6.2 00982 */ 00983 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); 00984 00985 /** 00986 * Set the uid to use when you set the replace_uid to 2. 00987 * 00988 * @see iso_write_opts_set_replace_mode 00989 * @since 0.6.2 00990 */ 00991 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); 00992 00993 /** 00994 * Set the gid to use when you set the replace_gid to 2. 00995 * 00996 * @see iso_write_opts_set_replace_mode 00997 * @since 0.6.2 00998 */ 00999 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); 01000 01001 /** 01002 * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use 01003 * values from timestamp field. This has only meaning if RR extensions 01004 * are enabled. 01005 * 01006 * @see iso_write_opts_set_default_timestamp 01007 * @since 0.6.2 01008 */ 01009 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); 01010 01011 /** 01012 * Set the timestamp to use when you set the replace_timestamps to 2. 01013 * 01014 * @see iso_write_opts_set_replace_timestamps 01015 * @since 0.6.2 01016 */ 01017 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); 01018 01019 /** 01020 * Whether to always record timestamps in GMT. 01021 * 01022 * By default, libisofs stores local time information on image. You can set 01023 * this to always store timestamps in GMT. This is useful if you want to hide 01024 * your timezone, or you live in a timezone that can't be represented in 01025 * ECMA-119. These are timezones whose offset from GMT is greater than +13 01026 * hours, lower than -12 hours, or not a multiple of 15 minutes. 01027 * 01028 * @since 0.6.2 01029 */ 01030 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); 01031 01032 /** 01033 * Set the charset to use for the RR names of the files that will be created 01034 * on the image. 01035 * NULL to use default charset, that is the locale charset. 01036 * You can obtain the list of charsets supported on your system executing 01037 * "iconv -l" in a shell. 01038 * 01039 * @since 0.6.2 01040 */ 01041 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); 01042 01043 /** 01044 * Set the type of the image to create. Libisofs support two kind of images: 01045 * stand-alone and appendable. 01046 * 01047 * A stand-alone image is an image that is valid alone, and that can be 01048 * mounted by its own. This is the kind of image you will want to create 01049 * in most cases. A stand-alone image can be burned in an empty CD or DVD, 01050 * or write to an .iso file for future burning or distribution. 01051 * 01052 * On the other side, an appendable image is not self contained, it refers 01053 * to serveral files that are stored outside the image. Its usage is for 01054 * multisession discs, where you add data in a new session, while the 01055 * previous session data can still be accessed. In those cases, the old 01056 * data is not written again. Instead, the new image refers to it, and thus 01057 * it's only valid when appended to the original. Note that in those cases 01058 * the image will be written after the original, and thus you will want 01059 * to use a ms_block greater than 0. 01060 * 01061 * Note that if you haven't import a previous image (by means of 01062 * iso_image_import()), the image will always be a stand-alone image, as 01063 * there is no previous data to refer to. 01064 * 01065 * @param appendable 01066 * 1 to create an appendable image, 0 for an stand-alone one. 01067 * 01068 * @since 0.6.2 01069 */ 01070 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int appendable); 01071 01072 /** 01073 * Set the start block of the image. It is supposed to be the lba where the 01074 * first block of the image will be written on disc. All references inside the 01075 * ISO image will take this into account, thus providing a mountable image. 01076 * 01077 * For appendable images, that are written to a new session, you should 01078 * pass here the lba of the next writable address on disc. 01079 * 01080 * In stand alone images this is usually 0. However, you may want to 01081 * provide a different ms_block if you don't plan to burn the image in the 01082 * first session on disc, such as in some CD-Extra disc whether the data 01083 * image is written in a new session after some audio tracks. 01084 * 01085 * @since 0.6.2 01086 */ 01087 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); 01088 01089 /** 01090 * Sets the buffer where to store the descriptors that need to be written 01091 * at the beginning of a overwriteable media to grow the image. 01092 * 01093 * @param overwrite 01094 * When not NULL, it should point to a buffer of at least 64KiB, where 01095 * libisofs will write the contents that should be written at the 01096 * beginning of a overwriteable media, to grow the image. The growing 01097 * of an image is a way, used by first time in growisofs by Andy Polyakov, 01098 * to allow the appending of new data to non-multisession media, such 01099 * as DVD+RW, in the same way you append a new session to a multisession 01100 * disc, i.e., without need to write again the contents of the previous 01101 * image. 01102 * 01103 * Note that if you want this kind of image growing, you will also need to 01104 * set appendable to "1" and provide a valid ms_block after the previous 01105 * image. 01106 * 01107 * You should initialize the buffer either with 0s, or with the contents of 01108 * the first blocks of the image you're growing. In most cases, 0 is good 01109 * enought. 01110 * 01111 * If you don't need this information, for example because you're creating a 01112 * new image from scratch of because you will create an image for a true 01113 * multisession media, just don't set this buffer or set it to NULL. 01114 * 01115 * @since 0.6.2 01116 */ 01117 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); 01118 01119 /** 01120 * Set the size, in number of blocks, of the FIFO buffer used between the 01121 * writer thread and the burn_source. You have to provide at least a 32 01122 * blocks buffer. Default value is set to 2MB, if that is ok for you, you 01123 * don't need to call this function. 01124 * 01125 * @since 0.6.2 01126 */ 01127 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); 01128 01129 /** 01130 * Create a burn_source to actually write the image. That burn_source can be 01131 * used with libburn as a data source for a track. 01132 * 01133 * @param image 01134 * The image to write. 01135 * @param opts 01136 * The options for image generation. All needed data will be copied, so 01137 * you can free the given struct once this function returns. 01138 * @param burn_src 01139 * Location where the pointer to the burn_source will be stored 01140 * @return 01141 * 1 on success, < 0 on error 01142 * 01143 * @since 0.6.2 01144 */ 01145 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, 01146 struct burn_source **burn_src); 01147 01148 /** 01149 * Creates an IsoReadOpts for reading an existent image. You should set the 01150 * options desired with the correspondent setters. Note that you may want to 01151 * set the start block value. 01152 * 01153 * Options by default are determined by the selected profile. 01154 * 01155 * @param opts 01156 * Pointer to the location where the newly created IsoReadOpts will be 01157 * stored. You should free it with iso_read_opts_free() when no more 01158 * needed. 01159 * @param profile 01160 * Default profile for image reading. For now the following values are 01161 * defined: 01162 * ---> 0 [STANDARD] 01163 * Suitable for most situations. All extension are read. When both 01164 * Joliet and RR extension are present, RR is used. 01165 * @return 01166 * 1 success, < 0 error 01167 * 01168 * @since 0.6.2 01169 */ 01170 int iso_read_opts_new(IsoReadOpts **opts, int profile); 01171 01172 /** 01173 * Free an IsoReadOpts previously allocated with iso_read_opts_new(). 01174 * 01175 * @since 0.6.2 01176 */ 01177 void iso_read_opts_free(IsoReadOpts *opts); 01178 01179 /** 01180 * Set the block where the image begins. It is usually 0, but may be different 01181 * on a multisession disc. 01182 * 01183 * @since 0.6.2 01184 */ 01185 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); 01186 01187 /** 01188 * Do not read Rock Ridge extensions. 01189 * In most cases you don't want to use this. It could be useful if RR info 01190 * is damaged, or if you want to use the Joliet tree. 01191 * 01192 * @since 0.6.2 01193 */ 01194 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); 01195 01196 /** 01197 * Do not read Joliet extensions. 01198 * 01199 * @since 0.6.2 01200 */ 01201 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); 01202 01203 /** 01204 * Do not read ISO 9660:1999 enhanced tree 01205 * 01206 * @since 0.6.2 01207 */ 01208 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); 01209 01210 /** 01211 * Whether to prefer Joliet over RR. libisofs usually prefers RR over 01212 * Joliet, as it give us much more info about files. So, if both extensions 01213 * are present, RR is used. You can set this if you prefer Joliet, but 01214 * note that this is not very recommended. This doesn't mean than RR 01215 * extensions are not read: if no Joliet is present, libisofs will read 01216 * RR tree. 01217 * 01218 * @since 0.6.2 01219 */ 01220 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); 01221 01222 /** 01223 * Set default uid for files when RR extensions are not present. 01224 * 01225 * @since 0.6.2 01226 */ 01227 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); 01228 01229 /** 01230 * Set default gid for files when RR extensions are not present. 01231 * 01232 * @since 0.6.2 01233 */ 01234 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid); 01235 01236 /** 01237 * Set default permissions for files when RR extensions are not present. 01238 * 01239 * @param file_perm 01240 * Permissions for files. 01241 * @param dir_perm 01242 * Permissions for directories. 01243 * 01244 * @since 0.6.2 01245 */ 01246 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm, 01247 mode_t dir_perm); 01248 01249 /** 01250 * Set the input charset of the file names on the image. NULL to use locale 01251 * charset. You have to specify a charset if the image filenames are encoded 01252 * in a charset different that the local one. This could happen, for example, 01253 * if the image was created on a system with different charset. 01254 * 01255 * @param charset 01256 * The charset to use as input charset. You can obtain the list of 01257 * charsets supported on your system executing "iconv -l" in a shell. 01258 * 01259 * @since 0.6.2 01260 */ 01261 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset); 01262 01263 /** 01264 * Import a previous session or image, for growing or modify. 01265 * 01266 * @param image 01267 * The image context to which old image will be imported. Note that all 01268 * files added to image, and image attributes, will be replaced with the 01269 * contents of the old image. 01270 * TODO #00025 support for merging old image files 01271 * @param src 01272 * Data Source from which old image will be read. A extra reference is 01273 * added, so you still need to iso_data_source_unref() yours. 01274 * @param opts 01275 * Options for image import. All needed data will be copied, so you 01276 * can free the given struct once this function returns. 01277 * @param features 01278 * If not NULL, a new IsoReadImageFeatures will be allocated and filled 01279 * with the features of the old image. It should be freed with 01280 * iso_read_image_features_destroy() when no more needed. You can pass 01281 * NULL if you're not interested on them. 01282 * @return 01283 * 1 on success, < 0 on error 01284 * 01285 * @since 0.6.2 01286 */ 01287 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts, 01288 IsoReadImageFeatures **features); 01289 01290 /** 01291 * Destroy an IsoReadImageFeatures object obtained with iso_image_import. 01292 * 01293 * @since 0.6.2 01294 */ 01295 void iso_read_image_features_destroy(IsoReadImageFeatures *f); 01296 01297 /** 01298 * Get the size (in 2048 byte block) of the image, as reported in the PVM. 01299 * 01300 * @since 0.6.2 01301 */ 01302 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f); 01303 01304 /** 01305 * Whether RockRidge extensions are present in the image imported. 01306 * 01307 * @since 0.6.2 01308 */ 01309 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f); 01310 01311 /** 01312 * Whether Joliet extensions are present in the image imported. 01313 * 01314 * @since 0.6.2 01315 */ 01316 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f); 01317 01318 /** 01319 * Whether the image is recorded according to ISO 9660:1999, i.e. it has 01320 * a version 2 Enhanced Volume Descriptor. 01321 * 01322 * @since 0.6.2 01323 */ 01324 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f); 01325 01326 /** 01327 * Whether El-Torito boot record is present present in the image imported. 01328 * 01329 * @since 0.6.2 01330 */ 01331 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f); 01332 01333 /** 01334 * Increments the reference counting of the given image. 01335 * 01336 * @since 0.6.2 01337 */ 01338 void iso_image_ref(IsoImage *image); 01339 01340 /** 01341 * Decrements the reference couting of the given image. 01342 * If it reaches 0, the image is free, together with its tree nodes (whether 01343 * their refcount reach 0 too, of course). 01344 * 01345 * @since 0.6.2 01346 */ 01347 void iso_image_unref(IsoImage *image); 01348 01349 /** 01350 * Attach user defined data to the image. Use this if your application needs 01351 * to store addition info together with the IsoImage. If the image already 01352 * has data attached, the old data will be freed. 01353 * 01354 * @param data 01355 * Pointer to application defined data that will be attached to the 01356 * image. You can pass NULL to remove any already attached data. 01357 * @param give_up 01358 * Function that will be called when the image does not need the data 01359 * any more. It receives the data pointer as an argumente, and eventually 01360 * causes data to be freed. It can be NULL if you don't need it. 01361 * @return 01362 * 1 on succes, < 0 on error 01363 * 01364 * @since 0.6.2 01365 */ 01366 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*)); 01367 01368 /** 01369 * The the data previously attached with iso_image_attach_data() 01370 * 01371 * @since 0.6.2 01372 */ 01373 void *iso_image_get_attached_data(IsoImage *image); 01374 01375 /** 01376 * Get the root directory of the image. 01377 * No extra ref is added to it, so you musn't unref it. Use iso_node_ref() 01378 * if you want to get your own reference. 01379 * 01380 * @since 0.6.2 01381 */ 01382 IsoDir *iso_image_get_root(const IsoImage *image); 01383 01384 /** 01385 * Fill in the volset identifier for a image. 01386 * 01387 * @since 0.6.2 01388 */ 01389 void iso_image_set_volset_id(IsoImage *image, const char *volset_id); 01390 01391 /** 01392 * Get the volset identifier. 01393 * The returned string is owned by the image and should not be freed nor 01394 * changed. 01395 * 01396 * @since 0.6.2 01397 */ 01398 const char *iso_image_get_volset_id(const IsoImage *image); 01399 01400 /** 01401 * Fill in the volume identifier for a image. 01402 * 01403 * @since 0.6.2 01404 */ 01405 void iso_image_set_volume_id(IsoImage *image, const char *volume_id); 01406 01407 /** 01408 * Get the volume identifier. 01409 * The returned string is owned by the image and should not be freed nor 01410 * changed. 01411 * 01412 * @since 0.6.2 01413 */ 01414 const char *iso_image_get_volume_id(const IsoImage *image); 01415 01416 /** 01417 * Fill in the publisher for a image. 01418 * 01419 * @since 0.6.2 01420 */ 01421 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id); 01422 01423 /** 01424 * Get the publisher of a image. 01425 * The returned string is owned by the image and should not be freed nor 01426 * changed. 01427 * 01428 * @since 0.6.2 01429 */ 01430 const char *iso_image_get_publisher_id(const IsoImage *image); 01431 01432 /** 01433 * Fill in the data preparer for a image. 01434 * 01435 * @since 0.6.2 01436 */ 01437 void iso_image_set_data_preparer_id(IsoImage *image, 01438 const char *data_preparer_id); 01439 01440 /** 01441 * Get the data preparer of a image. 01442 * The returned string is owned by the image and should not be freed nor 01443 * changed. 01444 * 01445 * @since 0.6.2 01446 */ 01447 const char *iso_image_get_data_preparer_id(const IsoImage *image); 01448 01449 /** 01450 * Fill in the system id for a image. Up to 32 characters. 01451 * 01452 * @since 0.6.2 01453 */ 01454 void iso_image_set_system_id(IsoImage *image, const char *system_id); 01455 01456 /** 01457 * Get the system id of a image. 01458 * The returned string is owned by the image and should not be freed nor 01459 * changed. 01460 * 01461 * @since 0.6.2 01462 */ 01463 const char *iso_image_get_system_id(const IsoImage *image); 01464 01465 /** 01466 * Fill in the application id for a image. Up to 128 chars. 01467 * 01468 * @since 0.6.2 01469 */ 01470 void iso_image_set_application_id(IsoImage *image, const char *application_id); 01471 01472 /** 01473 * Get the application id of a image. 01474 * The returned string is owned by the image and should not be freed nor 01475 * changed. 01476 * 01477 * @since 0.6.2 01478 */ 01479 const char *iso_image_get_application_id(const IsoImage *image); 01480 01481 /** 01482 * Fill copyright information for the image. Usually this refers 01483 * to a file on disc. Up to 37 characters. 01484 * 01485 * @since 0.6.2 01486 */ 01487 void iso_image_set_copyright_file_id(IsoImage *image, 01488 const char *copyright_file_id); 01489 01490 /** 01491 * Get the copyright information of a image. 01492 * The returned string is owned by the image and should not be freed nor 01493 * changed. 01494 * 01495 * @since 0.6.2 01496 */ 01497 const char *iso_image_get_copyright_file_id(const IsoImage *image); 01498 01499 /** 01500 * Fill abstract information for the image. Usually this refers 01501 * to a file on disc. Up to 37 characters. 01502 * 01503 * @since 0.6.2 01504 */ 01505 void iso_image_set_abstract_file_id(IsoImage *image, 01506 const char *abstract_file_id); 01507 01508 /** 01509 * Get the abstract information of a image. 01510 * The returned string is owned by the image and should not be freed nor 01511 * changed. 01512 * 01513 * @since 0.6.2 01514 */ 01515 const char *iso_image_get_abstract_file_id(const IsoImage *image); 01516 01517 /** 01518 * Fill biblio information for the image. Usually this refers 01519 * to a file on disc. Up to 37 characters. 01520 * 01521 * @since 0.6.2 01522 */ 01523 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id); 01524 01525 /** 01526 * Get the biblio information of a image. 01527 * The returned string is owned by the image and should not be freed nor 01528 * changed. 01529 * 01530 * @since 0.6.2 01531 */ 01532 const char *iso_image_get_biblio_file_id(const IsoImage *image); 01533 01534 /** 01535 * Create a bootable image by adding a El-Torito boot image. 01536 * 01537 * This also add a catalog boot node to the image filesystem tree. 01538 * 01539 * @param image 01540 * The image to make bootable. If it was already bootable this function 01541 * returns an error and the image remains unmodified. 01542 * @param image_path 01543 * The path on the image tree of a regular file to use as default boot 01544 * image. 01545 * @param type 01546 * The boot media type. This can be one of 3 types: 01547 * - Floppy emulation: Boot image file must be exactly 01548 * 1200 kB, 1440 kB or 2880 kB. 01549 * - Hard disc emulation: The image must begin with a master 01550 * boot record with a single image. 01551 * - No emulation. You should specify load segment and load size 01552 * of image. 01553 * @param catalog_path 01554 * The path on the image tree where the catalog will be stored. The 01555 * directory component of this path must be a directory existent on the 01556 * image tree, and the filename component must be unique among all 01557 * children of that directory on image. Otherwise a correspodent error 01558 * code will be returned. This function will add an IsoBoot node that acts 01559 * as a placeholder for the real catalog, that will be generated at image 01560 * creation time. 01561 * @param boot 01562 * Location where a pointer to the added boot image will be stored. That 01563 * object is owned by the IsoImage and should not be freed by the user, 01564 * nor dereferenced once the last reference to the IsoImage was disposed 01565 * via iso_image_unref(). A NULL value is allowed if you don't need a 01566 * reference to the boot image. 01567 * @return 01568 * 1 on success, < 0 on error 01569 * 01570 * @since 0.6.2 01571 */ 01572 int iso_image_set_boot_image(IsoImage *image, const char *image_path, 01573 enum eltorito_boot_media_type type, 01574 const char *catalog_path, 01575 ElToritoBootImage **boot); 01576 01577 /* TODO #00026 : add support for "hidden" bootable images. */ 01578 01579 /** 01580 * Get El-Torito boot image of an ISO image, if any. 01581 * 01582 * This can be useful, for example, to check if a volume read from a previous 01583 * session or an existing image is bootable. It can also be useful to get 01584 * the image and catalog tree nodes. An application would want those, for 01585 * example, to prevent the user removing it. 01586 * 01587 * Both nodes are owned by libisofs and should not be freed. You can get your 01588 * own ref with iso_node_ref(). You can can also check if the node is already 01589 * on the tree by getting its parent (note that when reading El-Torito info 01590 * from a previous image, the nodes might not be on the tree even if you haven't 01591 * removed them). Remember that you'll need to get a new ref 01592 * (with iso_node_ref()) before inserting them again to the tree, and probably 01593 * you will also need to set the name or permissions. 01594 * 01595 * @param image 01596 * The image from which to get the boot image. 01597 * @param boot 01598 * If not NULL, it will be filled with a pointer to the boot image, if 01599 * any. That object is owned by the IsoImage and should not be freed by 01600 * the user, nor dereferenced once the last reference to the IsoImage was 01601 * disposed via iso_image_unref(). 01602 * @param imgnode 01603 * When not NULL, it will be filled with the image tree node. No extra ref 01604 * is added, you can use iso_node_ref() to get one if you need it. 01605 * @param catnode 01606 * When not NULL, it will be filled with the catnode tree node. No extra 01607 * ref is added, you can use iso_node_ref() to get one if you need it. 01608 * @return 01609 * 1 on success, 0 is the image is not bootable (i.e., it has no El-Torito 01610 * image), < 0 error. 01611 * 01612 * @since 0.6.2 01613 */ 01614 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot, 01615 IsoFile **imgnode, IsoBoot **catnode); 01616 01617 /** 01618 * Removes the El-Torito bootable image. 01619 * 01620 * The IsoBoot node that acts as placeholder for the catalog is also removed 01621 * for the image tree, if there. 01622 * If the image is not bootable (don't have el-torito boot image) this function 01623 * just returns. 01624 * 01625 * @since 0.6.2 01626 */ 01627 void iso_image_remove_boot_image(IsoImage *image); 01628 01629 /** 01630 * Sets the load segment for the initial boot image. This is only for 01631 * no emulation boot images, and is a NOP for other image types. 01632 * 01633 * @since 0.6.2 01634 */ 01635 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment); 01636 01637 /** 01638 * Sets the number of sectors (512b) to be load at load segment during 01639 * the initial boot procedure. This is only for 01640 * no emulation boot images, and is a NOP for other image types. 01641 * 01642 * @since 0.6.2 01643 */ 01644 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors); 01645 01646 /** 01647 * Marks the specified boot image as not bootable 01648 * 01649 * @since 0.6.2 01650 */ 01651 void el_torito_set_no_bootable(ElToritoBootImage *bootimg); 01652 01653 /** 01654 * Specifies that this image needs to be patched. This involves the writting 01655 * of a 56 bytes boot information table at offset 8 of the boot image file. 01656 * The original boot image file won't be modified. 01657 * This is needed for isolinux boot images. 01658 * 01659 * @since 0.6.2 01660 */ 01661 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg); 01662 01663 /** 01664 * Increments the reference counting of the given node. 01665 * 01666 * @since 0.6.2 01667 */ 01668 void iso_node_ref(IsoNode *node); 01669 01670 /** 01671 * Decrements the reference couting of the given node. 01672 * If it reach 0, the node is free, and, if the node is a directory, 01673 * its children will be unref() too. 01674 * 01675 * @since 0.6.2 01676 */ 01677 void iso_node_unref(IsoNode *node); 01678 01679 /** 01680 * Get the type of an IsoNode. 01681 * 01682 * @since 0.6.2 01683 */ 01684 enum IsoNodeType iso_node_get_type(IsoNode *node); 01685 01686 /** 01687 * Set the name of a node. Note that if the node is already added to a dir 01688 * this can fail if dir already contains a node with the new name. 01689 * 01690 * @param node 01691 * The node whose name you want to change. Note that you can't change 01692 * the name of the root. 01693 * @param name 01694 * The name for the node. If you supply an empty string or a 01695 * name greater than 255 characters this returns with failure, and 01696 * node name is not modified. 01697 * @return 01698 * 1 on success, < 0 on error 01699 * 01700 * @since 0.6.2 01701 */ 01702 int iso_node_set_name(IsoNode *node, const char *name); 01703 01704 /** 01705 * Get the name of a node. 01706 * The returned string belongs to the node and should not be modified nor 01707 * freed. Use strdup if you really need your own copy. 01708 * 01709 * @since 0.6.2 01710 */ 01711 const char *iso_node_get_name(const IsoNode *node); 01712 01713 /** 01714 * Set the permissions for the node. This attribute is only useful when 01715 * Rock Ridge extensions are enabled. 01716 * 01717 * @param mode 01718 * bitmask with the permissions of the node, as specified in 'man 2 stat'. 01719 * The file type bitfields will be ignored, only file permissions will be 01720 * modified. 01721 * 01722 * @since 0.6.2 01723 */ 01724 void iso_node_set_permissions(IsoNode *node, mode_t mode); 01725 01726 /** 01727 * Get the permissions for the node 01728 * 01729 * @since 0.6.2 01730 */ 01731 mode_t iso_node_get_permissions(const IsoNode *node); 01732 01733 /** 01734 * Get the mode of the node, both permissions and file type, as specified in 01735 * 'man 2 stat'. 01736 * 01737 * @since 0.6.2 01738 */ 01739 mode_t iso_node_get_mode(const IsoNode *node); 01740 01741 /** 01742 * Set the user id for the node. This attribute is only useful when 01743 * Rock Ridge extensions are enabled. 01744 * 01745 * @since 0.6.2 01746 */ 01747 void iso_node_set_uid(IsoNode *node, uid_t uid); 01748 01749 /** 01750 * Get the user id of the node. 01751 * 01752 * @since 0.6.2 01753 */ 01754 uid_t iso_node_get_uid(const IsoNode *node); 01755 01756 /** 01757 * Set the group id for the node. This attribute is only useful when 01758 * Rock Ridge extensions are enabled. 01759 * 01760 * @since 0.6.2 01761 */ 01762 void iso_node_set_gid(IsoNode *node, gid_t gid); 01763 01764 /** 01765 * Get the group id of the node. 01766 * 01767 * @since 0.6.2 01768 */ 01769 gid_t iso_node_get_gid(const IsoNode *node); 01770 01771 /** 01772 * Set the time of last modification of the file 01773 * 01774 * @since 0.6.2 01775 */ 01776 void iso_node_set_mtime(IsoNode *node, time_t time); 01777 01778 /** 01779 * Get the time of last modification of the file 01780 * 01781 * @since 0.6.2 01782 */ 01783 time_t iso_node_get_mtime(const IsoNode *node); 01784 01785 /** 01786 * Set the time of last access to the file 01787 * 01788 * @since 0.6.2 01789 */ 01790 void iso_node_set_atime(IsoNode *node, time_t time); 01791 01792 /** 01793 * Get the time of last access to the file 01794 * 01795 * @since 0.6.2 01796 */ 01797 time_t iso_node_get_atime(const IsoNode *node); 01798 01799 /** 01800 * Set the time of last status change of the file 01801 * 01802 * @since 0.6.2 01803 */ 01804 void iso_node_set_ctime(IsoNode *node, time_t time); 01805 01806 /** 01807 * Get the time of last status change of the file 01808 * 01809 * @since 0.6.2 01810 */ 01811 time_t iso_node_get_ctime(const IsoNode *node); 01812 01813 /** 01814 * Set if the node will be hidden in RR/ISO tree, Joliet tree or both. 01815 * 01816 * If the file is setted as hidden in one tree, it won't be included there, so 01817 * it won't be visible in a OS accessing CD using that tree. For example, 01818 * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see 01819 * what is recorded on CD, while MS Windows make use of the Joliet tree. If a 01820 * file is hidden only in Joliet, it won't be visible in Windows systems, 01821 * while still visible in Linux. 01822 * 01823 * If a file is hidden in both trees, it won't be written to image. 01824 * 01825 * @param node 01826 * The node that is to be hidden. 01827 * @param hide_attrs 01828 * IsoHideNodeFlag's to set the trees in which file will be hidden. 01829 * 01830 * @since 0.6.2 01831 */ 01832 void iso_node_set_hidden(IsoNode *node, int hide_attrs); 01833 01834 /** 01835 * Add a new node to a dir. Note that this function don't add a new ref to 01836 * the node, so you don't need to free it, it will be automatically freed 01837 * when the dir is deleted. Of course, if you want to keep using the node 01838 * after the dir life, you need to iso_node_ref() it. 01839 * 01840 * @param dir 01841 * the dir where to add the node 01842 * @param child 01843 * the node to add. You must ensure that the node hasn't previously added 01844 * to other dir, and that the node name is unique inside the child. 01845 * Otherwise this function will return a failure, and the child won't be 01846 * inserted. 01847 * @param replace 01848 * if the dir already contains a node with the same name, whether to 01849 * replace or not the old node with this. 01850 * @return 01851 * number of nodes in dir if succes, < 0 otherwise 01852 * Possible errors: 01853 * ISO_NULL_POINTER, if dir or child are NULL 01854 * ISO_NODE_ALREADY_ADDED, if child is already added to other dir 01855 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 01856 * ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1) 01857 * 01858 * @since 0.6.2 01859 */ 01860 int iso_dir_add_node(IsoDir *dir, IsoNode *child, 01861 enum iso_replace_mode replace); 01862 01863 /** 01864 * Locate a node inside a given dir. 01865 * 01866 * @param dir 01867 * The dir where to look for the node. 01868 * @param name 01869 * The name of the node 01870 * @param node 01871 * Location for a pointer to the node, it will filled with NULL if the dir 01872 * doesn't have a child with the given name. 01873 * The node will be owned by the dir and shouldn't be unref(). Just call 01874 * iso_node_ref() to get your own reference to the node. 01875 * Note that you can pass NULL is the only thing you want to do is check 01876 * if a node with such name already exists on dir. 01877 * @return 01878 * 1 node found, 0 child has no such node, < 0 error 01879 * Possible errors: 01880 * ISO_NULL_POINTER, if dir or name are NULL 01881 * 01882 * @since 0.6.2 01883 */ 01884 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node); 01885 01886 /** 01887 * Get the number of children of a directory. 01888 * 01889 * @return 01890 * >= 0 number of items, < 0 error 01891 * Possible errors: 01892 * ISO_NULL_POINTER, if dir is NULL 01893 * 01894 * @since 0.6.2 01895 */ 01896 int iso_dir_get_children_count(IsoDir *dir); 01897 01898 /** 01899 * Removes a child from a directory. 01900 * The child is not freed, so you will become the owner of the node. Later 01901 * you can add the node to another dir (calling iso_dir_add_node), or free 01902 * it if you don't need it (with iso_node_unref). 01903 * 01904 * @return 01905 * 1 on success, < 0 error 01906 * Possible errors: 01907 * ISO_NULL_POINTER, if node is NULL 01908 * ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir 01909 * 01910 * @since 0.6.2 01911 */ 01912 int iso_node_take(IsoNode *node); 01913 01914 /** 01915 * Removes a child from a directory and free (unref) it. 01916 * If you want to keep the child alive, you need to iso_node_ref() it 01917 * before this call, but in that case iso_node_take() is a better 01918 * alternative. 01919 * 01920 * @return 01921 * 1 on success, < 0 error 01922 * 01923 * @since 0.6.2 01924 */ 01925 int iso_node_remove(IsoNode *node); 01926 01927 /* 01928 * Get the parent of the given iso tree node. No extra ref is added to the 01929 * returned directory, you must take your ref. with iso_node_ref() if you 01930 * need it. 01931 * 01932 * If node is the root node, the same node will be returned as its parent. 01933 * 01934 * This returns NULL if the node doesn't pertain to any tree 01935 * (it was removed/take). 01936 * 01937 * @since 0.6.2 01938 */ 01939 IsoDir *iso_node_get_parent(IsoNode *node); 01940 01941 /** 01942 * Get an iterator for the children of the given dir. 01943 * 01944 * You can iterate over the children with iso_dir_iter_next. When finished, 01945 * you should free the iterator with iso_dir_iter_free. 01946 * You musn't delete a child of the same dir, using iso_node_take() or 01947 * iso_node_remove(), while you're using the iterator. You can use 01948 * iso_node_take_iter() or iso_node_remove_iter() instead. 01949 * 01950 * You can use the iterator in the way like this 01951 * 01952 * IsoDirIter *iter; 01953 * IsoNode *node; 01954 * if ( iso_dir_get_children(dir, &iter) != 1 ) { 01955 * // handle error 01956 * } 01957 * while ( iso_dir_iter_next(iter, &node) == 1 ) { 01958 * // do something with the child 01959 * } 01960 * iso_dir_iter_free(iter); 01961 * 01962 * An iterator is intended to be used in a single iteration over the 01963 * children of a dir. Thus, it should be treated as a temporary object, 01964 * and free as soon as possible. 01965 * 01966 * @return 01967 * 1 success, < 0 error 01968 * Possible errors: 01969 * ISO_NULL_POINTER, if dir or iter are NULL 01970 * ISO_OUT_OF_MEM 01971 * 01972 * @since 0.6.2 01973 */ 01974 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter); 01975 01976 /** 01977 * Get the next child. 01978 * Take care that the node is owned by its parent, and will be unref() when 01979 * the parent is freed. If you want your own ref to it, call iso_node_ref() 01980 * on it. 01981 * 01982 * @return 01983 * 1 success, 0 if dir has no more elements, < 0 error 01984 * Possible errors: 01985 * ISO_NULL_POINTER, if node or iter are NULL 01986 * ISO_ERROR, on wrong iter usage, usual caused by modiying the 01987 * dir during iteration 01988 * 01989 * @since 0.6.2 01990 */ 01991 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node); 01992 01993 /** 01994 * Check if there're more children. 01995 * 01996 * @return 01997 * 1 dir has more elements, 0 no, < 0 error 01998 * Possible errors: 01999 * ISO_NULL_POINTER, if iter is NULL 02000 * 02001 * @since 0.6.2 02002 */ 02003 int iso_dir_iter_has_next(IsoDirIter *iter); 02004 02005 /** 02006 * Free a dir iterator. 02007 * 02008 * @since 0.6.2 02009 */ 02010 void iso_dir_iter_free(IsoDirIter *iter); 02011 02012 /** 02013 * Removes a child from a directory during an iteration, without freeing it. 02014 * It's like iso_node_take(), but to be used during a directory iteration. 02015 * The node removed will be the last returned by the iteration. 02016 * 02017 * The behavior on two call to this function without calling iso_dir_iter_next 02018 * between then is undefined, and should never occur. (TODO protect against this?) 02019 * 02020 * @return 02021 * 1 on succes, < 0 error 02022 * Possible errors: 02023 * ISO_NULL_POINTER, if iter is NULL 02024 * ISO_ERROR, on wrong iter usage, for example by call this before 02025 * iso_dir_iter_next. 02026 * 02027 * @since 0.6.2 02028 */ 02029 int iso_dir_iter_take(IsoDirIter *iter); 02030 02031 /** 02032 * Removes a child from a directory during an iteration and unref() it. 02033 * It's like iso_node_remove(), but to be used during a directory iteration. 02034 * The node removed will be the last returned by the iteration. 02035 * 02036 * The behavior on two call to this function without calling iso_tree_iter_next 02037 * between then is undefined, and should never occur. (TODO protect against this?) 02038 * 02039 * @return 02040 * 1 on succes, < 0 error 02041 * Possible errors: 02042 * ISO_NULL_POINTER, if iter is NULL 02043 * ISO_ERROR, on wrong iter usage, for example by call this before 02044 * iso_dir_iter_next. 02045 * 02046 * @since 0.6.2 02047 */ 02048 int iso_dir_iter_remove(IsoDirIter *iter); 02049 02050 /** 02051 * Get the destination of a node. 02052 * The returned string belongs to the node and should not be modified nor 02053 * freed. Use strdup if you really need your own copy. 02054 * 02055 * @since 0.6.2 02056 */ 02057 const char *iso_symlink_get_dest(const IsoSymlink *link); 02058 02059 /** 02060 * Set the destination of a link. 02061 * 02062 * @param dest 02063 * New destination for the link. It must be a non-empty string, otherwise 02064 * this function doesn't modify previous destination. 02065 * @return 02066 * 1 on success, < 0 on error 02067 * 02068 * @since 0.6.2 02069 */ 02070 int iso_symlink_set_dest(IsoSymlink *link, const char *dest); 02071 02072 /** 02073 * Sets the order in which a node will be written on image. High weihted files 02074 * will be written first, so in a disc them will be written near the center. 02075 * 02076 * @param node 02077 * The node which weight will be changed. If it's a dir, this function 02078 * will change the weight of all its children. For nodes other that dirs 02079 * or regular files, this function has no effect. 02080 * @param w 02081 * The weight as a integer number, the greater this value is, the 02082 * closer from the begining of image the file will be written. 02083 * 02084 * @since 0.6.2 02085 */ 02086 void iso_node_set_sort_weight(IsoNode *node, int w); 02087 02088 /** 02089 * Get the sort weight of a file. 02090 * 02091 * @since 0.6.2 02092 */ 02093 int iso_file_get_sort_weight(IsoFile *file); 02094 02095 /** 02096 * Get the size of the file, in bytes 02097 * 02098 * @since 0.6.2 02099 */ 02100 off_t iso_file_get_size(IsoFile *file); 02101 02102 /** 02103 * Add a new directory to the iso tree. Permissions, owner and hidden atts 02104 * are taken from parent, you can modify them later. 02105 * 02106 * @param parent 02107 * the dir where the new directory will be created 02108 * @param name 02109 * name for the new dir. If a node with same name already exists on 02110 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02111 * @param dir 02112 * place where to store a pointer to the newly created dir. No extra 02113 * ref is addded, so you will need to call iso_node_ref() if you really 02114 * need it. You can pass NULL in this parameter if you don't need the 02115 * pointer. 02116 * @return 02117 * number of nodes in parent if success, < 0 otherwise 02118 * Possible errors: 02119 * ISO_NULL_POINTER, if parent or name are NULL 02120 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02121 * ISO_OUT_OF_MEM 02122 * 02123 * @since 0.6.2 02124 */ 02125 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir); 02126 02127 /* 02128 TODO #00007 expose Stream and this function: 02129 int iso_tree_add_new_file(IsoDir *parent, const char *name, stream, file) 02130 */ 02131 02132 /** 02133 * Add a new symlink to the directory tree. Permissions are set to 0777, 02134 * owner and hidden atts are taken from parent. You can modify any of them 02135 * later. 02136 * 02137 * @param parent 02138 * the dir where the new symlink will be created 02139 * @param name 02140 * name for the new symlink. If a node with same name already exists on 02141 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02142 * @param dest 02143 * destination of the link 02144 * @param link 02145 * place where to store a pointer to the newly created link. No extra 02146 * ref is addded, so you will need to call iso_node_ref() if you really 02147 * need it. You can pass NULL in this parameter if you don't need the 02148 * pointer 02149 * @return 02150 * number of nodes in parent if success, < 0 otherwise 02151 * Possible errors: 02152 * ISO_NULL_POINTER, if parent, name or dest are NULL 02153 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02154 * ISO_OUT_OF_MEM 02155 * 02156 * @since 0.6.2 02157 */ 02158 int iso_tree_add_new_symlink(IsoDir *parent, const char *name, 02159 const char *dest, IsoSymlink **link); 02160 02161 /** 02162 * Add a new special file to the directory tree. As far as libisofs concerns, 02163 * an special file is a block device, a character device, a FIFO (named pipe) 02164 * or a socket. You can choose the specific kind of file you want to add 02165 * by setting mode propertly (see man 2 stat). 02166 * 02167 * Note that special files are only written to image when Rock Ridge 02168 * extensions are enabled. Moreover, a special file is just a directory entry 02169 * in the image tree, no data is written beyond that. 02170 * 02171 * Owner and hidden atts are taken from parent. You can modify any of them 02172 * later. 02173 * 02174 * @param parent 02175 * the dir where the new special file will be created 02176 * @param name 02177 * name for the new special file. If a node with same name already exists 02178 * on parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02179 * @param mode 02180 * file type and permissions for the new node. Note that you can't 02181 * specify any kind of file here, only special types are allowed. i.e, 02182 * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK, 02183 * S_IFREG and S_IFDIR aren't. 02184 * @param dev 02185 * device ID, equivalent to the st_rdev field in man 2 stat. 02186 * @param special 02187 * place where to store a pointer to the newly created special file. No 02188 * extra ref is addded, so you will need to call iso_node_ref() if you 02189 * really need it. You can pass NULL in this parameter if you don't need 02190 * the pointer. 02191 * @return 02192 * number of nodes in parent if success, < 0 otherwise 02193 * Possible errors: 02194 * ISO_NULL_POINTER, if parent, name or dest are NULL 02195 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02196 * ISO_WRONG_ARG_VALUE if you select a incorrect mode 02197 * ISO_OUT_OF_MEM 02198 * 02199 * @since 0.6.2 02200 */ 02201 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode, 02202 dev_t dev, IsoSpecial **special); 02203 02204 /** 02205 * Set whether to follow or not symbolic links when added a file from a source 02206 * to IsoImage. Default behavior is to not follow symlinks. 02207 * 02208 * @since 0.6.2 02209 */ 02210 void iso_tree_set_follow_symlinks(IsoImage *image, int follow); 02211 02212 /** 02213 * Get current setting for follow_symlinks. 02214 * 02215 * @see iso_tree_set_follow_symlinks 02216 * @since 0.6.2 02217 */ 02218 int iso_tree_get_follow_symlinks(IsoImage *image); 02219 02220 /** 02221 * Set whether to skip or not hidden files when adding a directory recursibely. 02222 * Default behavior is to not ignore them, i.e., to add hidden files to image. 02223 * 02224 * @since 0.6.2 02225 */ 02226 void iso_tree_set_ignore_hidden(IsoImage *image, int skip); 02227 02228 /** 02229 * Get current setting for ignore_hidden. 02230 * 02231 * @see iso_tree_set_ignore_hidden 02232 * @since 0.6.2 02233 */ 02234 int iso_tree_get_ignore_hidden(IsoImage *image); 02235 02236 /** 02237 * Set the replace mode, that defines the behavior of libisofs when adding 02238 * a node whit the same name that an existent one, during a recursive 02239 * directory addition. 02240 * 02241 * @since 0.6.2 02242 */ 02243 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode); 02244 02245 /** 02246 * Get current setting for replace_mode. 02247 * 02248 * @see iso_tree_set_replace_mode 02249 * @since 0.6.2 02250 */ 02251 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image); 02252 02253 /** 02254 * Set whether to skip or not special files. Default behavior is to not skip 02255 * them. Note that, despite of this setting, special files won't never be added 02256 * to an image unless RR extensions were enabled. 02257 * 02258 * @param skip 02259 * Bitmask to determine what kind of special files will be skipped: 02260 * bit0: ignore FIFOs 02261 * bit1: ignore Sockets 02262 * bit2: ignore char devices 02263 * bit3: ignore block devices 02264 * 02265 * @since 0.6.2 02266 */ 02267 void iso_tree_set_ignore_special(IsoImage *image, int skip); 02268 02269 /** 02270 * Get current setting for ignore_special. 02271 * 02272 * @see iso_tree_set_ignore_special 02273 * @since 0.6.2 02274 */ 02275 int iso_tree_get_ignore_special(IsoImage *image); 02276 02277 /** 02278 * Add a excluded path. These are paths that won't never added to image, 02279 * and will be excluded even when adding recursively its parent directory. 02280 * 02281 * For example, in 02282 * 02283 * iso_tree_add_exclude(image, "/home/user/data/private"); 02284 * iso_tree_add_dir_rec(image, root, "/home/user/data"); 02285 * 02286 * the directory /home/user/data/private won't be added to image. 02287 * 02288 * However, if you explicity add a deeper dir, it won't be excluded. i.e., 02289 * in the following example. 02290 * 02291 * iso_tree_add_exclude(image, "/home/user/data"); 02292 * iso_tree_add_dir_rec(image, root, "/home/user/data/private"); 02293 * 02294 * the directory /home/user/data/private is added. On the other, side, and 02295 * foollowing the the example above, 02296 * 02297 * iso_tree_add_dir_rec(image, root, "/home/user"); 02298 * 02299 * will exclude the directory "/home/user/data". 02300 * 02301 * Absolute paths are not mandatory, you can, for example, add a relative 02302 * path such as: 02303 * 02304 * iso_tree_add_exclude(image, "private"); 02305 * iso_tree_add_exclude(image, "user/data"); 02306 * 02307 * to excluve, respectively, all files or dirs named private, and also all 02308 * files or dirs named data that belong to a folder named "user". Not that the 02309 * above rule about deeper dirs is still valid. i.e., if you call 02310 * 02311 * iso_tree_add_dir_rec(image, root, "/home/user/data/music"); 02312 * 02313 * it is included even containing "user/data" string. However, a possible 02314 * "/home/user/data/music/user/data" is not added. 02315 * 02316 * Usual wildcards, such as * or ? are also supported, with the usual meaning 02317 * as stated in "man 7 glob". For example 02318 * 02319 * // to exclude backup text files 02320 * iso_tree_add_exclude(image, "*.~"); 02321 * 02322 * @return 02323 * 1 on success, < 0 on error 02324 * 02325 * @since 0.6.2 02326 */ 02327 int iso_tree_add_exclude(IsoImage *image, const char *path); 02328 02329 /** 02330 * Remove a previously added exclude. 02331 * 02332 * @see iso_tree_add_exclude 02333 * @return 02334 * 1 on success, 0 exclude do not exists, < 0 on error 02335 * 02336 * @since 0.6.2 02337 */ 02338 int iso_tree_remove_exclude(IsoImage *image, const char *path); 02339 02340 /** 02341 * Set a callback function that libisofs will call for each file that is 02342 * added to the given image by a recursive addition function. This includes 02343 * image import. 02344 * 02345 * @param report 02346 * pointer to a function that will be called just before a file will be 02347 * added to the image. You can control whether the file will be in fact 02348 * added or ignored. 02349 * This function should return 1 to add the file, 0 to ignore it and 02350 * continue, < 0 to abort the process 02351 * NULL is allowed if you don't want any callback. 02352 * 02353 * @since 0.6.2 02354 */ 02355 void iso_tree_set_report_callback(IsoImage *image, 02356 int (*report)(IsoImage*, IsoFileSource*)); 02357 02358 /** 02359 * Add a new node to the image tree, from an existing file. 02360 * 02361 * TODO comment Builder and Filesystem related issues when exposing both 02362 * 02363 * All attributes will be taken from the source file. The appropriate file 02364 * type will be created. 02365 * 02366 * @param image 02367 * The image 02368 * @param parent 02369 * The directory in the image tree where the node will be added. 02370 * @param path 02371 * The path of the file to add in the filesystem. 02372 * @param node 02373 * place where to store a pointer to the newly added file. No 02374 * extra ref is addded, so you will need to call iso_node_ref() if you 02375 * really need it. You can pass NULL in this parameter if you don't need 02376 * the pointer. 02377 * @return 02378 * number of nodes in parent if success, < 0 otherwise 02379 * Possible errors: 02380 * ISO_NULL_POINTER, if image, parent or path are NULL 02381 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02382 * ISO_OUT_OF_MEM 02383 * 02384 * @since 0.6.2 02385 */ 02386 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path, 02387 IsoNode **node); 02388 02389 /** 02390 * Add the contents of a dir to a given directory of the iso tree. 02391 * 02392 * There are several options to control what files are added or how they are 02393 * managed. Take a look at iso_tree_set_* functions to see diferent options 02394 * for recursive directory addition. 02395 * 02396 * TODO comment Builder and Filesystem related issues when exposing both 02397 * 02398 * @param image 02399 * The image to which the directory belong. 02400 * @param parent 02401 * Directory on the image tree where to add the contents of the dir 02402 * @param dir 02403 * Path to a dir in the filesystem 02404 * @return 02405 * number of nodes in parent if success, < 0 otherwise 02406 * 02407 * @since 0.6.2 02408 */ 02409 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir); 02410 02411 /** 02412 * Locate a node by its path on image. 02413 * 02414 * @param node 02415 * Location for a pointer to the node, it will filled with NULL if the 02416 * given path does not exists on image. 02417 * The node will be owned by the image and shouldn't be unref(). Just call 02418 * iso_node_ref() to get your own reference to the node. 02419 * Note that you can pass NULL is the only thing you want to do is check 02420 * if a node with such path really exists. 02421 * @return 02422 * 1 found, 0 not found, < 0 error 02423 * 02424 * @since 0.6.2 02425 */ 02426 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node); 02427 02428 /** 02429 * Increments the reference counting of the given IsoDataSource. 02430 * 02431 * @since 0.6.2 02432 */ 02433 void iso_data_source_ref(IsoDataSource *src); 02434 02435 /** 02436 * Decrements the reference counting of the given IsoDataSource, freeing it 02437 * if refcount reach 0. 02438 * 02439 * @since 0.6.2 02440 */ 02441 void iso_data_source_unref(IsoDataSource *src); 02442 02443 /** 02444 * Create a new IsoDataSource from a local file. This is suitable for 02445 * accessing regular .iso images, or to acces drives via its block device 02446 * and standard POSIX I/O calls. 02447 * 02448 * @param path 02449 * The path of the file 02450 * @param src 02451 * Will be filled with the pointer to the newly created data source. 02452 * @return 02453 * 1 on success, < 0 on error. 02454 * 02455 * @since 0.6.2 02456 */ 02457 int iso_data_source_new_from_file(const char *path, IsoDataSource **src); 02458 02459 /** 02460 * Get the status of the buffer used by a burn_source. 02461 * 02462 * @param b 02463 * A burn_source previously obtained with 02464 * iso_image_create_burn_source(). 02465 * @param size 02466 * Will be filled with the total size of the buffer, in bytes 02467 * @param free_bytes 02468 * Will be filled with the bytes currently available in buffer 02469 * @return 02470 * < 0 error, > 0 state: 02471 * 1="active" : input and consumption are active 02472 * 2="ending" : input has ended without error 02473 * 3="failing" : input had error and ended, 02474 * 5="abandoned" : consumption has ended prematurely 02475 * 6="ended" : consumption has ended without input error 02476 * 7="aborted" : consumption has ended after input error 02477 * 02478 * @since 0.6.2 02479 */ 02480 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size, 02481 size_t *free_bytes); 02482 02483 #define ISO_MSGS_MESSAGE_LEN 4096 02484 02485 /** 02486 * Control queueing and stderr printing of messages from libisofs. 02487 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 02488 * "NOTE", "UPDATE", "DEBUG", "ALL". 02489 * 02490 * @param queue_severity Gives the minimum limit for messages to be queued. 02491 * Default: "NEVER". If you queue messages then you 02492 * must consume them by iso_msgs_obtain(). 02493 * @param print_severity Does the same for messages to be printed directly 02494 * to stderr. 02495 * @param print_id A text prefix to be printed before the message. 02496 * @return >0 for success, <=0 for error 02497 * 02498 * @since 0.6.2 02499 */ 02500 int iso_set_msgs_severities(char *queue_severity, char *print_severity, 02501 char *print_id); 02502 02503 /** 02504 * Obtain the oldest pending libisofs message from the queue which has at 02505 * least the given minimum_severity. This message and any older message of 02506 * lower severity will get discarded from the queue and is then lost forever. 02507 * 02508 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 02509 * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 02510 * will discard the whole queue. 02511 * 02512 * @param error_code 02513 * Will become a unique error code as listed at the end of this header 02514 * @param imgid 02515 * Id of the image that was issued the message. 02516 * @param msg_text 02517 * Must provide at least ISO_MSGS_MESSAGE_LEN bytes. 02518 * @param severity 02519 * Will become the severity related to the message and should provide at 02520 * least 80 bytes. 02521 * @return 02522 * 1 if a matching item was found, 0 if not, <0 for severe errors 02523 * 02524 * @since 0.6.2 02525 */ 02526 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid, 02527 char msg_text[], char severity[]); 02528 02529 /** 02530 * Get the id of an IsoImage, used for message reporting. This message id, 02531 * retrieved with iso_obtain_msgs(), can be used to distinguish what 02532 * IsoImage has isssued a given message. 02533 * 02534 * @since 0.6.2 02535 */ 02536 int iso_image_get_msg_id(IsoImage *image); 02537 02538 /** 02539 * Get a textual description of a libisofs error. 02540 * 02541 * @since 0.6.2 02542 */ 02543 const char *iso_error_to_msg(int errcode); 02544 02545 /** 02546 * Get the severity of a given error code 02547 * @return 02548 * 0x10000000 -> DEBUG 02549 * 0x20000000 -> UPDATE 02550 * 0x30000000 -> NOTE 02551 * 0x40000000 -> HINT 02552 * 0x50000000 -> WARNING 02553 * 0x60000000 -> SORRY 02554 * 0x64000000 -> MISHAP 02555 * 0x68000000 -> FAILURE 02556 * 0x70000000 -> FATAL 02557 * 0x71000000 -> ABORT 02558 * 02559 * @since 0.6.2 02560 */ 02561 int iso_error_get_severity(int e); 02562 02563 /** 02564 * Get the priority of a given error. 02565 * @return 02566 * 0x00000000 -> ZERO 02567 * 0x10000000 -> LOW 02568 * 0x20000000 -> MEDIUM 02569 * 0x30000000 -> HIGH 02570 * 02571 * @since 0.6.2 02572 */ 02573 int iso_error_get_priority(int e); 02574 02575 /** 02576 * Get the message queue code of a libisofs error. 02577 */ 02578 int iso_error_get_code(int e); 02579 02580 /** 02581 * Set the minimum error severity that causes a libisofs operation to 02582 * be aborted as soon as possible. 02583 * 02584 * @param severity 02585 * one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE". 02586 * Severities greater or equal than FAILURE always cause program to abort. 02587 * Severities under NOTE won't never cause function abort. 02588 * @return 02589 * Previous abort priority on success, < 0 on error. 02590 * 02591 * @since 0.6.2 02592 */ 02593 int iso_set_abort_severity(char *severity); 02594 02595 /** 02596 * Return the messenger object handle used by libisofs. This handle 02597 * may be used by related libraries to their own compatible 02598 * messenger objects and thus to direct their messages to the libisofs 02599 * message queue. See also: libburn, API function burn_set_messenger(). 02600 * 02601 * @return the handle. Do only use with compatible 02602 * 02603 * @since 0.6.2 02604 */ 02605 void *iso_get_messenger(); 02606 02607 /** 02608 * Take a ref to the given IsoFileSource. 02609 * 02610 * @since 0.6.2 02611 */ 02612 void iso_file_source_ref(IsoFileSource *src); 02613 02614 /** 02615 * Drop your ref to the given IsoFileSource, eventually freeing the associated 02616 * system resources. 02617 * 02618 * @since 0.6.2 02619 */ 02620 void iso_file_source_unref(IsoFileSource *src); 02621 02622 /* 02623 * this are just helpers to invoque methods in class 02624 */ 02625 02626 /** 02627 * Get the path, relative to the filesystem this file source 02628 * belongs to. 02629 * 02630 * @return 02631 * the path of the FileSource inside the filesystem, it should be 02632 * freed when no more needed. 02633 * 02634 * @since 0.6.2 02635 */ 02636 char* iso_file_source_get_path(IsoFileSource *src); 02637 02638 /** 02639 * Get the name of the file, with the dir component of the path. 02640 * 02641 * @return 02642 * the name of the file, it should be freed when no more needed. 02643 * 02644 * @since 0.6.2 02645 */ 02646 char* iso_file_source_get_name(IsoFileSource *src); 02647 02648 /** 02649 * Get information about the file. 02650 * @return 02651 * 1 success, < 0 error 02652 * Error codes: 02653 * ISO_FILE_ACCESS_DENIED 02654 * ISO_FILE_BAD_PATH 02655 * ISO_FILE_DOESNT_EXIST 02656 * ISO_OUT_OF_MEM 02657 * ISO_FILE_ERROR 02658 * ISO_NULL_POINTER 02659 * 02660 * @since 0.6.2 02661 */ 02662 int iso_file_source_lstat(IsoFileSource *src, struct stat *info); 02663 02664 /** 02665 * Check if the process has access to read file contents. Note that this 02666 * is not necessarily related with (l)stat functions. For example, in a 02667 * filesystem implementation to deal with an ISO image, if the user has 02668 * read access to the image it will be able to read all files inside it, 02669 * despite of the particular permission of each file in the RR tree, that 02670 * are what the above functions return. 02671 * 02672 * @return 02673 * 1 if process has read access, < 0 on error 02674 * Error codes: 02675 * ISO_FILE_ACCESS_DENIED 02676 * ISO_FILE_BAD_PATH 02677 * ISO_FILE_DOESNT_EXIST 02678 * ISO_OUT_OF_MEM 02679 * ISO_FILE_ERROR 02680 * ISO_NULL_POINTER 02681 * 02682 * @since 0.6.2 02683 */ 02684 int iso_file_source_access(IsoFileSource *src); 02685 02686 /** 02687 * Get information about the file. If the file is a symlink, the info 02688 * returned refers to the destination. 02689 * 02690 * @return 02691 * 1 success, < 0 error 02692 * Error codes: 02693 * ISO_FILE_ACCESS_DENIED 02694 * ISO_FILE_BAD_PATH 02695 * ISO_FILE_DOESNT_EXIST 02696 * ISO_OUT_OF_MEM 02697 * ISO_FILE_ERROR 02698 * ISO_NULL_POINTER 02699 * 02700 * @since 0.6.2 02701 */ 02702 int iso_file_source_stat(IsoFileSource *src, struct stat *info); 02703 02704 /** 02705 * Opens the source. 02706 * @return 1 on success, < 0 on error 02707 * Error codes: 02708 * ISO_FILE_ALREADY_OPENNED 02709 * ISO_FILE_ACCESS_DENIED 02710 * ISO_FILE_BAD_PATH 02711 * ISO_FILE_DOESNT_EXIST 02712 * ISO_OUT_OF_MEM 02713 * ISO_FILE_ERROR 02714 * ISO_NULL_POINTER 02715 * 02716 * @since 0.6.2 02717 */ 02718 int iso_file_source_open(IsoFileSource *src); 02719 02720 /** 02721 * Close a previuously openned file 02722 * @return 1 on success, < 0 on error 02723 * Error codes: 02724 * ISO_FILE_ERROR 02725 * ISO_NULL_POINTER 02726 * ISO_FILE_NOT_OPENNED 02727 * 02728 * @since 0.6.2 02729 */ 02730 int iso_file_source_close(IsoFileSource *src); 02731 02732 /** 02733 * Attempts to read up to count bytes from the given source into 02734 * the buffer starting at buf. 02735 * 02736 * The file src must be open() before calling this, and close() when no 02737 * more needed. Not valid for dirs. On symlinks it reads the destination 02738 * file. 02739 * 02740 * @param src 02741 * The given source 02742 * @param buf 02743 * Pointer to a buffer of at least count bytes where the read data will be 02744 * stored 02745 * @param count 02746 * Bytes to read 02747 * @return 02748 * number of bytes read, 0 if EOF, < 0 on error 02749 * Error codes: 02750 * ISO_FILE_ERROR 02751 * ISO_NULL_POINTER 02752 * ISO_FILE_NOT_OPENNED 02753 * ISO_WRONG_ARG_VALUE -> if count == 0 02754 * ISO_FILE_IS_DIR 02755 * ISO_OUT_OF_MEM 02756 * ISO_INTERRUPTED 02757 * 02758 * @since 0.6.2 02759 */ 02760 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count); 02761 02762 /** 02763 * Read a directory. 02764 * 02765 * Each call to this function will return a new children, until we reach 02766 * the end of file (i.e, no more children), in that case it returns 0. 02767 * 02768 * The dir must be open() before calling this, and close() when no more 02769 * needed. Only valid for dirs. 02770 * 02771 * Note that "." and ".." children MUST NOT BE returned. 02772 * 02773 * @param child 02774 * pointer to be filled with the given child. Undefined on error or OEF 02775 * @return 02776 * 1 on success, 0 if EOF (no more children), < 0 on error 02777 * Error codes: 02778 * ISO_FILE_ERROR 02779 * ISO_NULL_POINTER 02780 * ISO_FILE_NOT_OPENNED 02781 * ISO_FILE_IS_NOT_DIR 02782 * ISO_OUT_OF_MEM 02783 * 02784 * @since 0.6.2 02785 */ 02786 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child); 02787 02788 /** 02789 * Read the destination of a symlink. You don't need to open the file 02790 * to call this. 02791 * 02792 * @param src 02793 * An IsoFileSource corresponding to a symbolic link. 02794 * @param buf 02795 * allocated buffer of at least bufsiz bytes. 02796 * The dest. will be copied there, and it will be NULL-terminated 02797 * @param bufsiz 02798 * characters to be copied. Destination link will be truncated if 02799 * it is larger than given size. This include the '\0' character. 02800 * @return 02801 * 1 on success, < 0 on error 02802 * Error codes: 02803 * ISO_FILE_ERROR 02804 * ISO_NULL_POINTER 02805 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 02806 * ISO_FILE_IS_NOT_SYMLINK 02807 * ISO_OUT_OF_MEM 02808 * ISO_FILE_BAD_PATH 02809 * ISO_FILE_DOESNT_EXIST 02810 * 02811 * @since 0.6.2 02812 */ 02813 int iso_file_source_readlink(IsoFileSource *src, char *buf, size_t bufsiz); 02814 02815 /** 02816 * Get the filesystem for this source. No extra ref is added, so you 02817 * musn't unref the IsoFilesystem. 02818 * 02819 * @return 02820 * The filesystem, NULL on error 02821 * 02822 * @since 0.6.2 02823 */ 02824 IsoFilesystem* iso_file_source_get_filesystem(IsoFileSource *src); 02825 02826 /** 02827 * Take a ref to the given IsoFilesystem 02828 * 02829 * @since 0.6.2 02830 */ 02831 void iso_filesystem_ref(IsoFilesystem *fs); 02832 02833 /** 02834 * Drop your ref to the given IsoFilesystem, evetually freeing associated 02835 * resources. 02836 * 02837 * @since 0.6.2 02838 */ 02839 void iso_filesystem_unref(IsoFilesystem *fs); 02840 02841 /** 02842 * Create a new IsoFilesystem to access a existent ISO image. 02843 * 02844 * @param src 02845 * Data source to access data. 02846 * @param opts 02847 * Image read options 02848 * @param msgid 02849 * An image identifer, obtained with iso_image_get_msg_id(), used to 02850 * associated messages issued by the filesystem implementation with an 02851 * existent image. If you are not using this filesystem in relation with 02852 * any image context, just use 0x1fffff as the value for this parameter. 02853 * @param fs 02854 * Will be filled with a pointer to the filesystem that can be used 02855 * to access image contents. 02856 * @param 02857 * 1 on success, < 0 on error 02858 * 02859 * @since 0.6.2 02860 */ 02861 int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid, 02862 IsoImageFilesystem **fs); 02863 02864 /** 02865 * Get the volset identifier for an existent image. The returned string belong 02866 * to the IsoImageFilesystem and shouldn't be free() nor modified. 02867 * 02868 * @since 0.6.2 02869 */ 02870 const char *iso_image_fs_get_volset_id(IsoImageFilesystem *fs); 02871 02872 /** 02873 * Get the volume identifier for an existent image. The returned string belong 02874 * to the IsoImageFilesystem and shouldn't be free() nor modified. 02875 * 02876 * @since 0.6.2 02877 */ 02878 const char *iso_image_fs_get_volume_id(IsoImageFilesystem *fs); 02879 02880 /** 02881 * Get the publisher identifier for an existent image. The returned string 02882 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02883 * 02884 * @since 0.6.2 02885 */ 02886 const char *iso_image_fs_get_publisher_id(IsoImageFilesystem *fs); 02887 02888 /** 02889 * Get the data preparer identifier for an existent image. The returned string 02890 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02891 * 02892 * @since 0.6.2 02893 */ 02894 const char *iso_image_fs_get_data_preparer_id(IsoImageFilesystem *fs); 02895 02896 /** 02897 * Get the system identifier for an existent image. The returned string belong 02898 * to the IsoImageFilesystem and shouldn't be free() nor modified. 02899 * 02900 * @since 0.6.2 02901 */ 02902 const char *iso_image_fs_get_system_id(IsoImageFilesystem *fs); 02903 02904 /** 02905 * Get the application identifier for an existent image. The returned string 02906 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02907 * 02908 * @since 0.6.2 02909 */ 02910 const char *iso_image_fs_get_application_id(IsoImageFilesystem *fs); 02911 02912 /** 02913 * Get the copyright file identifier for an existent image. The returned string 02914 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02915 * 02916 * @since 0.6.2 02917 */ 02918 const char *iso_image_fs_get_copyright_file_id(IsoImageFilesystem *fs); 02919 02920 /** 02921 * Get the abstract file identifier for an existent image. The returned string 02922 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02923 * 02924 * @since 0.6.2 02925 */ 02926 const char *iso_image_fs_get_abstract_file_id(IsoImageFilesystem *fs); 02927 02928 /** 02929 * Get the biblio file identifier for an existent image. The returned string 02930 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 02931 * 02932 * @since 0.6.2 02933 */ 02934 const char *iso_image_fs_get_biblio_file_id(IsoImageFilesystem *fs); 02935 02936 /************ Error codes and return values for libisofs ********************/ 02937 02938 /** successfully execution */ 02939 #define ISO_SUCCESS 1 02940 02941 /** 02942 * special return value, it could be or not an error depending on the 02943 * context. 02944 */ 02945 #define ISO_NONE 0 02946 02947 /** Operation canceled (FAILURE,HIGH, -1) */ 02948 #define ISO_CANCELED 0xE830FFFF 02949 02950 /** Unknown or unexpected fatal error (FATAL,HIGH, -2) */ 02951 #define ISO_FATAL_ERROR 0xF030FFFE 02952 02953 /** Unknown or unexpected error (FAILURE,HIGH, -3) */ 02954 #define ISO_ERROR 0xE830FFFD 02955 02956 /** Internal programming error. Please report this bug (FATAL,HIGH, -4) */ 02957 #define ISO_ASSERT_FAILURE 0xF030FFFC 02958 02959 /** 02960 * NULL pointer as value for an arg. that doesn't allow NULL (FAILURE,HIGH, -5) 02961 */ 02962 #define ISO_NULL_POINTER 0xE830FFFB 02963 02964 /** Memory allocation error (FATAL,HIGH, -6) */ 02965 #define ISO_OUT_OF_MEM 0xF030FFFA 02966 02967 /** Interrupted by a signal (FATAL,HIGH, -7) */ 02968 #define ISO_INTERRUPTED 0xF030FFF9 02969 02970 /** Invalid parameter value (FAILURE,HIGH, -8) */ 02971 #define ISO_WRONG_ARG_VALUE 0xE830FFF8 02972 02973 /** Can't create a needed thread (FATAL,HIGH, -9) */ 02974 #define ISO_THREAD_ERROR 0xF030FFF7 02975 02976 /** Write error (FAILURE,HIGH, -10) */ 02977 #define ISO_WRITE_ERROR 0xE830FFF6 02978 02979 /** Buffer read error (FAILURE,HIGH, -11) */ 02980 #define ISO_BUF_READ_ERROR 0xE830FFF5 02981 02982 /** Trying to add to a dir a node already added to a dir (FAILURE,HIGH, -64) */ 02983 #define ISO_NODE_ALREADY_ADDED 0xE830FFC0 02984 02985 /** Node with same name already exists (FAILURE,HIGH, -65) */ 02986 #define ISO_NODE_NAME_NOT_UNIQUE 0xE830FFBF 02987 02988 /** Trying to remove a node that was not added to dir (FAILURE,HIGH, -65) */ 02989 #define ISO_NODE_NOT_ADDED_TO_DIR 0xE830FFBE 02990 02991 /** A requested node does not exist (FAILURE,HIGH, -66) */ 02992 #define ISO_NODE_DOESNT_EXIST 0xE830FFBD 02993 02994 /** 02995 * Try to set the boot image of an already bootable image (FAILURE,HIGH, -67) 02996 */ 02997 #define ISO_IMAGE_ALREADY_BOOTABLE 0xE830FFBC 02998 02999 /** Trying to use an invalid file as boot image (FAILURE,HIGH, -68) */ 03000 #define ISO_BOOT_IMAGE_NOT_VALID 0xE830FFBB 03001 03002 /** 03003 * Error on file operation (FAILURE,HIGH, -128) 03004 * (take a look at more specified error codes below) 03005 */ 03006 #define ISO_FILE_ERROR 0xE830FF80 03007 03008 /** Trying to open an already openned file (FAILURE,HIGH, -129) */ 03009 #define ISO_FILE_ALREADY_OPENNED 0xE830FF7F 03010 03011 /** Access to file is not allowed (FAILURE,HIGH, -130) */ 03012 #define ISO_FILE_ACCESS_DENIED 0xE830FF7E 03013 03014 /** Incorrect path to file (FAILURE,HIGH, -131) */ 03015 #define ISO_FILE_BAD_PATH 0xE830FF7D 03016 03017 /** The file does not exist in the filesystem (FAILURE,HIGH, -132) */ 03018 #define ISO_FILE_DOESNT_EXIST 0xE830FF7C 03019 03020 /** Trying to read or close a file not openned (FAILURE,HIGH, -133) */ 03021 #define ISO_FILE_NOT_OPENNED 0xE830FF7B 03022 03023 /** Directory used where no dir is expected (FAILURE,HIGH, -134) */ 03024 #define ISO_FILE_IS_DIR 0xE830FF7A 03025 03026 /** Read error (FAILURE,HIGH, -135) */ 03027 #define ISO_FILE_READ_ERROR 0xE830FF79 03028 03029 /** Not dir used where a dir is expected (FAILURE,HIGH, -136) */ 03030 #define ISO_FILE_IS_NOT_DIR 0xE830FF78 03031 03032 /** Not symlink used where a symlink is expected (FAILURE,HIGH, -137) */ 03033 #define ISO_FILE_IS_NOT_SYMLINK 0xE830FF77 03034 03035 /** Can't seek to specified location (FAILURE,HIGH, -138) */ 03036 #define ISO_FILE_SEEK_ERROR 0xE830FF76 03037 03038 /** File not supported in ECMA-119 tree and thus ignored (HINT,MEDIUM, -139) */ 03039 #define ISO_FILE_IGNORED 0xC020FF75 03040 03041 /* A file is bigger than supported by used standard (HINT,MEDIUM, -140) */ 03042 #define ISO_FILE_TOO_BIG 0xC020FF74 03043 03044 /* File read error during image creation (MISHAP,HIGH, -141) */ 03045 #define ISO_FILE_CANT_WRITE 0xE430FF73 03046 03047 /* Can't convert filename to requested charset (HINT,MEDIUM, -142) */ 03048 #define ISO_FILENAME_WRONG_CHARSET 0xC020FF72 03049 03050 /* File can't be added to the tree (SORRY,HIGH, -143) */ 03051 #define ISO_FILE_CANT_ADD 0xE030FF71 03052 03053 /** 03054 * File path break specification constraints and will be ignored 03055 * (HINT,MEDIUM, -141) 03056 */ 03057 #define ISO_FILE_IMGPATH_WRONG 0xC020FF70 03058 03059 /** Charset conversion error (FAILURE,HIGH, -256) */ 03060 #define ISO_CHARSET_CONV_ERROR 0xE830FF00 03061 03062 /** 03063 * Too much files to mangle, i.e. we cannot guarantee unique file names 03064 * (FAILURE,HIGH, -257) 03065 */ 03066 #define ISO_MANGLE_TOO_MUCH_FILES 0xE830FEFF 03067 03068 /* image related errors */ 03069 03070 /** 03071 * Wrong or damaged Primary Volume Descriptor (FAILURE,HIGH, -320) 03072 * This could mean that the file is not a valid ISO image. 03073 */ 03074 #define ISO_WRONG_PVD 0xE830FEC0 03075 03076 /** Wrong or damaged RR entry (SORRY,HIGH, -321) */ 03077 #define ISO_WRONG_RR 0xE030FEBF 03078 03079 /** Unsupported RR feature (SORRY,HIGH, -322) */ 03080 #define ISO_UNSUPPORTED_RR 0xE030FEBE 03081 03082 /** Wrong or damaged ECMA-119 (FAILURE,HIGH, -323) */ 03083 #define ISO_WRONG_ECMA119 0xE830FEBD 03084 03085 /** Unsupported ECMA-119 feature (FAILURE,HIGH, -324) */ 03086 #define ISO_UNSUPPORTED_ECMA119 0xE830FEBC 03087 03088 /** Wrong or damaged El-Torito catalog (SORRY,HIGH, -325) */ 03089 #define ISO_WRONG_EL_TORITO 0xE030FEBB 03090 03091 /** Unsupported El-Torito feature (SORRY,HIGH, -326) */ 03092 #define ISO_UNSUPPORTED_EL_TORITO 0xE030FEBA 03093 03094 /** Can't patch an isolinux boot image (SORRY,HIGH, -327) */ 03095 #define ISO_ISOLINUX_CANT_PATCH 0xE030FEB9 03096 03097 /** Unsupported SUSP feature (SORRY,HIGH, -328) */ 03098 #define ISO_UNSUPPORTED_SUSP 0xE030FEB8 03099 03100 /** Error on a RR entry that can be ignored (WARNING,HIGH, -329) */ 03101 #define ISO_WRONG_RR_WARN 0xD030FEB7 03102 03103 /** Error on a RR entry that can be ignored (HINT,MEDIUM, -330) */ 03104 #define ISO_SUSP_UNHANDLED 0xC020FEB6 03105 03106 /** Multiple ER SUSP entries found (WARNING,HIGH, -331) */ 03107 #define ISO_SUSP_MULTIPLE_ER 0xD030FEB5 03108 03109 /** Unsupported volume descriptor found (HINT,MEDIUM, -332) */ 03110 #define ISO_UNSUPPORTED_VD 0xC020FEB4 03111 03112 /** El-Torito related warning (WARNING,HIGH, -333) */ 03113 #define ISO_EL_TORITO_WARN 0xD030FEB3 03114 03115 /** Image write cancelled (MISHAP,HIGH, -334) */ 03116 #define ISO_IMAGE_WRITE_CANCELED 0xE430FEB2 03117 03118 /** El-Torito image is hidden (WARNING,HIGH, -335) */ 03119 #define ISO_EL_TORITO_HIDDEN 0xD030FEB1 03120 03121 #endif /*LIBISO_LIBISOFS_H_*/