You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
libisofs/libisofs/libisofs.h

5468 lines
176 KiB

/*
* Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic
* Copyright (c) 2009 Thomas Schmitt
*
* This file is part of the libisofs project; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation. See COPYING file for details.
*/
/*
*
* Applications must use 64 bit off_t, e.g. on 32-bit Linux by defining
* #define _LARGEFILE_SOURCE
* #define _FILE_OFFSET_BITS 64
* or take special precautions to interface with the library by 64 bit integers
* where this .h files prescribe off_t. Not to use 64 bit file i/o will keep
* the application from producing and processing ISO images of more than 2 GB
* size.
*
*/
#ifndef LIBISO_LIBISOFS_H_
#define LIBISO_LIBISOFS_H_
#include <sys/stat.h>
#include <stdint.h>
#include <stdlib.h>
struct burn_source;
/**
* Context for image creation. It holds the files that will be added to image,
* and several options to control libisofs behavior.
*
* @since 0.6.2
*/
typedef struct Iso_Image IsoImage;
/*
* A node in the iso tree, i.e. a file that will be written to image.
*
* It can represent any kind of files. When needed, you can get the type with
* iso_node_get_type() and cast it to the appropiate subtype. Useful macros
* are provided, see below.
*
* @since 0.6.2
*/
typedef struct Iso_Node IsoNode;
15 years ago
/**
* A directory in the iso tree. It is an special type of IsoNode and can be
* casted to it in any case.
*
* @since 0.6.2
*/
typedef struct Iso_Dir IsoDir;
/**
* A symbolic link in the iso tree. It is an special type of IsoNode and can be
* casted to it in any case.
*
* @since 0.6.2
*/
typedef struct Iso_Symlink IsoSymlink;
/**
* A regular file in the iso tree. It is an special type of IsoNode and can be
* casted to it in any case.
*
* @since 0.6.2
*/
typedef struct Iso_File IsoFile;
/**
* An special file in the iso tree. This is used to represent any POSIX file
* other that regular files, directories or symlinks, i.e.: socket, block and
* character devices, and fifos.
* It is an special type of IsoNode and can be casted to it in any case.
*
* @since 0.6.2
*/
typedef struct Iso_Special IsoSpecial;
/**
* The type of an IsoNode.
*
* When an user gets an IsoNode from an image, (s)he can use
* iso_node_get_type() to get the current type of the node, and then
* cast to the appropriate subtype. For example:
*
* ...
* IsoNode *node;
* res = iso_dir_iter_next(iter, &node);
* if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) {
* IsoDir *dir = (IsoDir *)node;
* ...
* }
*
* @since 0.6.2
*/
enum IsoNodeType {
LIBISO_DIR,
LIBISO_FILE,
LIBISO_SYMLINK,
LIBISO_SPECIAL,
LIBISO_BOOT
};
/* macros to check node type */
#define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR)
#define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE)
#define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK)
#define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL)
#define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT)
/* macros for safe downcasting */
#define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL))
#define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL))
#define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL))
#define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL))
#define ISO_NODE(n) ((IsoNode*)n)
/**
* File section in an old image.
*
* @since 0.6.8
*/
struct iso_file_section
{
uint32_t block;
uint32_t size;
};
/**
* Context for iterate on directory children.
* @see iso_dir_get_children()
*
* @since 0.6.2
*/
typedef struct Iso_Dir_Iter IsoDirIter;
/**
* It represents an El-Torito boot image.
*
* @since 0.6.2
*/
typedef struct el_torito_boot_image ElToritoBootImage;
/**
* An special type of IsoNode that acts as a placeholder for an El-Torito
* boot catalog. Once written, it will appear as a regular file.
*
* @since 0.6.2
*/
typedef struct Iso_Boot IsoBoot;
/**
* Flag used to hide a file in the RR/ISO or Joliet tree.
*
* @see iso_node_set_hidden
* @since 0.6.2
*/
enum IsoHideNodeFlag {
/** Hide the node in the ECMA-119 / RR tree */
LIBISO_HIDE_ON_RR = 1 << 0,
/** Hide the node in the Joliet tree, if Joliet extension are enabled */
LIBISO_HIDE_ON_JOLIET = 1 << 1,
/** Hide the node in the ISO-9660:1999 tree, if that format is enabled */
LIBISO_HIDE_ON_1999 = 1 << 2
};
/**
* El-Torito bootable image type.
*
* @since 0.6.2
*/
enum eltorito_boot_media_type {
ELTORITO_FLOPPY_EMUL,
ELTORITO_HARD_DISC_EMUL,
ELTORITO_NO_EMUL
};
/**
* Replace mode used when addding a node to a file.
* This controls how libisofs will act when you tried to add to a dir a file
* with the same name that an existing file.
*
* @since 0.6.2
*/
enum iso_replace_mode {
/**
* Never replace an existing node, and instead fail with
* ISO_NODE_NAME_NOT_UNIQUE.
*/
ISO_REPLACE_NEVER,
/**
* Always replace the old node with the new.
*/
ISO_REPLACE_ALWAYS,
/**
* Replace with the new node if it is the same file type
*/
ISO_REPLACE_IF_SAME_TYPE,
/**
* Replace with the new node if it is the same file type and its ctime
* is newer than the old one.
*/
ISO_REPLACE_IF_SAME_TYPE_AND_NEWER,
/**
* Replace with the new node if its ctime is newer than the old one.
*/
ISO_REPLACE_IF_NEWER
/*
* TODO #00006 define more values
* -if both are dirs, add contents (and what to do with conflicts?)
*/
};
/**
* Options for image written.
* @see iso_write_opts_new()
* @since 0.6.2
*/
typedef struct iso_write_opts IsoWriteOpts;
/**
* Options for image reading or import.
* @see iso_read_opts_new()
* @since 0.6.2
*/
typedef struct iso_read_opts IsoReadOpts;
/**
* Source for image reading.
*
* @see struct iso_data_source
* @since 0.6.2
*/
typedef struct iso_data_source IsoDataSource;
/**
* Data source used by libisofs for reading an existing image.
*
* It offers homogeneous read access to arbitrary blocks to different sources
* for images, such as .iso files, CD/DVD drives, etc...
*
* To create a multisession image, libisofs needs a IsoDataSource, that the
* user must provide. The function iso_data_source_new_from_file() constructs
* an IsoDataSource that uses POSIX I/O functions to access data. You can use
* it with regular .iso images, and also with block devices that represent a
* drive.
*
* @since 0.6.2
*/
struct iso_data_source
{
/* reserved for future usage, set to 0 */
int version;
/**
* Reference count for the data source. Should be 1 when a new source
* is created. Don't access it directly, but with iso_data_source_ref()
* and iso_data_source_unref() functions.
*/
unsigned int refcount;
/**
* Opens the given source. You must open() the source before any attempt
* to read data from it. The open is the right place for grabbing the
* underlying resources.
*
* @return
* 1 if success, < 0 on error (has to be a valid libisofs error code)
*/
int (*open)(IsoDataSource *src);
/**
* Close a given source, freeing all system resources previously grabbed in
* open().
*
* @return
* 1 if success, < 0 on error (has to be a valid libisofs error code)
*/
int (*close)(IsoDataSource *src);
/**
* Read an arbitrary block (2048 bytes) of data from the source.
*
* @param lba
* Block to be read.
* @param buffer
* Buffer where the data will be written. It should have at least
* 2048 bytes.
* @return
* 1 if success,
* < 0 if error. This function has to emit a valid libisofs error code.
* Predifined (but not mandatory) for this purpose are:
* ISO_DATA_SOURCE_SORRY , ISO_DATA_SOURCE_MISHAP,
* ISO_DATA_SOURCE_FAILURE , ISO_DATA_SOURCE_FATAL
*/
int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer);
/**
* Clean up the source specific data. Never call this directly, it is
* automatically called by iso_data_source_unref() when refcount reach
* 0.
*/
void (*free_data)(IsoDataSource *);
/** Source specific data */
void *data;
};
/**
* Return information for image. This is optionally allocated by libisofs,
* as a way to inform user about the features of an existing image, such as
* extensions present, size, ...
*
* @see iso_image_import()
* @since 0.6.2
*/
typedef struct iso_read_image_features IsoReadImageFeatures;
/**
* POSIX abstraction for source files.
*
* @see struct iso_file_source
* @since 0.6.2
*/
typedef struct iso_file_source IsoFileSource;
/**
* Abstract for source filesystems.
*
* @see struct iso_filesystem
* @since 0.6.2
*/
typedef struct iso_filesystem IsoFilesystem;
/**
* Interface that defines the operations (methods) available for an
* IsoFileSource.
*
* @see struct IsoFileSource_Iface
* @since 0.6.2
*/
typedef struct IsoFileSource_Iface IsoFileSourceIface;
/**
* IsoFilesystem implementation to deal with ISO images, and to offer a way to
* access specific information of the image, such as several volume attributes,
* extensions being used, El-Torito artifacts...
*
* @since 0.6.2
*/
typedef IsoFilesystem IsoImageFilesystem;
/**
* See IsoFilesystem->get_id() for info about this.
* @since 0.6.2
*/
extern unsigned int iso_fs_global_id;
/**
* An IsoFilesystem is a handler for a source of files, or a "filesystem".
* That is defined as a set of files that are organized in a hierarchical
* structure.
*
* A filesystem allows libisofs to access files from several sources in
* an homogeneous way, thus abstracting the underlying operations needed to
* access and read file contents. Note that this doesn't need to be tied
* to the disc filesystem used in the partition being accessed. For example,
* we have an IsoFilesystem implementation to access any mounted filesystem,
* using standard Linux functions. It is also legal, of course, to implement
* an IsoFilesystem to deal with a specific filesystem over raw partitions.
* That is what we do, for example, to access an ISO Image.
*
* Each file inside an IsoFilesystem is represented as an IsoFileSource object,
* that defines POSIX-like interface for accessing files.
*
* @since 0.6.2
*/
struct iso_filesystem
{
/**
* Type of filesystem.
* "file" -> local filesystem
* "iso " -> iso image filesystem
*/
char type[4];
/* reserved for future usage, set to 0 */
int version;
/**
* Get the root of a filesystem.
*
* @return
* 1 on success, < 0 on error (has to be a valid libisofs error code)
*/
int (*get_root)(IsoFilesystem *fs, IsoFileSource **root);
/**
* Retrieve a file from its absolute path inside the filesystem.
*
* @return
* 1 success, < 0 error (has to be a valid libisofs error code)
* Error codes:
* ISO_FILE_ACCESS_DENIED
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
* ISO_OUT_OF_MEM
* ISO_FILE_ERROR
* ISO_NULL_POINTER
*/
int (*get_by_path)(IsoFilesystem *fs, const char *path,
IsoFileSource **file);
/**
* Get filesystem identifier.
*
* If the filesystem is able to generate correct values of the st_dev
* and st_ino fields for the struct stat of each file, this should
* return an unique number, greater than 0.
*
* To get a identifier for your filesystem implementation you should
* use iso_fs_global_id, incrementing it by one each time.
*
* Otherwise, if you can't ensure values in the struct stat are valid,
* this should return 0.
*/
unsigned int (*get_id)(IsoFilesystem *fs);
/**
* Opens the filesystem for several read operations. Calling this funcion
* is not needed at all, each time that the underlying system resource
* needs to be accessed, it is openned propertly.
* However, if you plan to execute several operations on the filesystem,
* it is a good idea to open it previously, to prevent several open/close
* operations to occur.
*
* @return 1 on success, < 0 on error (has to be a valid libisofs error code)
*/
int (*open)(IsoFilesystem *fs);
/**
* Close the filesystem, thus freeing all system resources. You should
* call this function if you have previously open() it.
* Note that you can open()/close() a filesystem several times.
*
* @return 1 on success, < 0 on error (has to be a valid libisofs error code)
*/
int (*close)(IsoFilesystem *fs);
/**
* Free implementation specific data. Should never be called by user.
* Use iso_filesystem_unref() instead.
*/
void (*free)(IsoFilesystem *fs);
/* internal usage, do never access them directly */
unsigned int refcount;
void *data;
};
/**
* Interface definition for an IsoFileSource. Defines the POSIX-like function
* to access files and abstract underlying source.
*
* @since 0.6.2
*/
struct IsoFileSource_Iface
{
/**
* Tells the version of the interface:
* Version 0 provides functions up to (*lseek)().
* @since 0.6.2
* Version 1 additionally provides function *(get_aa_string)().
* @since 0.6.14
*/
int version;
/**
* Get the path, relative to the filesystem this file source belongs to.
*
* @return
* the path of the FileSource inside the filesystem, it should be
* freed when no more needed.
*/
char* (*get_path)(IsoFileSource *src);
/**
* Get the name of the file, with the dir component of the path.
*
* @return
* the name of the file, it should be freed when no more needed.
*/
char* (*get_name)(IsoFileSource *src);
/**
* Get information about the file. It is equivalent to lstat(2).
*
* @return
* 1 success, < 0 error (has to be a valid libisofs error code)
* Error codes:
* ISO_FILE_ACCESS_DENIED
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
* ISO_OUT_OF_MEM
* ISO_FILE_ERROR
* ISO_NULL_POINTER
*/
int (*lstat)(IsoFileSource *src, struct stat *info);
/**
* Get information about the file. If the file is a symlink, the info
* returned refers to the destination. It is equivalent to stat(2).
*
* @return
* 1 success, < 0 error
* Error codes:
* ISO_FILE_ACCESS_DENIED
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
* ISO_OUT_OF_MEM
* ISO_FILE_ERROR
* ISO_NULL_POINTER
*/
int (*stat)(IsoFileSource *src, struct stat *info);
/**
* Check if the process has access to read file contents. Note that this
* is not necessarily related with (l)stat functions. For example, in a
* filesystem implementation to deal with an ISO image, if the user has
* read access to the image it will be able to read all files inside it,
* despite of the particular permission of each file in the RR tree, that
* are what the above functions return.
*
* @return
* 1 if process has read access, < 0 on error (has to be a valid
* libisofs error code)
* Error codes:
* ISO_FILE_ACCESS_DENIED
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
* ISO_OUT_OF_MEM
* ISO_FILE_ERROR
* ISO_NULL_POINTER
*/
int (*access)(IsoFileSource *src);
/**
* Opens the source.
* @return 1 on success, < 0 on error (has to be a valid libisofs error code)
* Error codes:
* ISO_FILE_ALREADY_OPENED
* ISO_FILE_ACCESS_DENIED
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
* ISO_OUT_OF_MEM
* ISO_FILE_ERROR
* ISO_NULL_POINTER
*/
int (*open)(IsoFileSource *src);
/**
* Close a previuously openned file
* @return 1 on success, < 0 on error
* Error codes:
* ISO_FILE_ERROR
* ISO_NULL_POINTER
* ISO_FILE_NOT_OPENED
*/
int (*close)(IsoFileSource *src);
/**
* Attempts to read up to count bytes from the given source into
* the buffer starting at buf.
*
* The file src must be open() before calling this, and close() when no
* more needed. Not valid for dirs. On symlinks it reads the destination
* file.
*
* @return
* number of bytes read, 0 if EOF, < 0 on error (has to be a valid
* libisofs error code)
* Error codes:
* ISO_FILE_ERROR
* ISO_NULL_POINTER
* ISO_FILE_NOT_OPENED
* ISO_WRONG_ARG_VALUE -> if count == 0
* ISO_FILE_IS_DIR
* ISO_OUT_OF_MEM
* ISO_INTERRUPTED
*/
int (*read)(IsoFileSource *src, void *buf, size_t count);
/**
* Read a directory.
*
* Each call to this function will return a new children, until we reach
* the end of file (i.e, no more children), in that case it returns 0.
*
* The dir must be open() before calling this, and close() when no more
* needed. Only valid for dirs.
*
* Note that "." and ".." children MUST NOT BE returned.
*
* @param child
* pointer to be filled with the given child. Undefined on error or OEF
* @return
* 1 on success, 0 if EOF (no more children), < 0 on error (has to be
* a valid libisofs error code)
* Error codes:
* ISO_FILE_ERROR
* ISO_NULL_POINTER
* ISO_FILE_NOT_OPENED
* ISO_FILE_IS_NOT_DIR
* ISO_OUT_OF_MEM
*/
int (*readdir)(IsoFileSource *src, IsoFileSource **child);
/**
* Read the destination of a symlink. You don't need to open the file
* to call this.
*
* @param buf
* allocated buffer of at least bufsiz bytes.
* The dest. will be copied there, and it will be NULL-terminated
* @param bufsiz
* characters to be copied. Destination link will be truncated if
* it is larger than given size. This include the \0 character.
* @return
* 1 on success, < 0 on error (has to be a valid libisofs error code)
* Error codes:
* ISO_FILE_ERROR
* ISO_NULL_POINTER
* ISO_WRONG_ARG_VALUE -> if bufsiz <= 0
* ISO_FILE_IS_NOT_SYMLINK
* ISO_OUT_OF_MEM
* ISO_FILE_BAD_PATH
* ISO_FILE_DOESNT_EXIST
*
*/
int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz);
/**
* Get the filesystem for this source. No extra ref is added, so you
* musn't unref the IsoFilesystem.
*
* @return
* The filesystem, NULL on error
*/
IsoFilesystem* (*get_filesystem)(IsoFileSource *src);
/**
* Free implementation specific data. Should never be called by user.
* Use iso_file_source_unref() instead.
*/
void (*free)(IsoFileSource *src);
/**
* Repositions the offset of the IsoFileSource (must be opened) to the
* given offset according to the value of flag.
*
* @param offset
* in bytes
* @param flag
* 0 The offset is set to offset bytes (SEEK_SET)
* 1 The offset is set to its current location plus offset bytes
* (SEEK_CUR)
* 2 The offset is set to the size of the file plus offset bytes
* (SEEK_END).
* @return
* Absolute offset position of the file, or < 0 on error. Cast the
* returning value to int to get a valid libisofs error.
*
* @since 0.6.4
*/
off_t (*lseek)(IsoFileSource *src, off_t offset, int flag);
/* Add-ons of .version 1 begin here */
/**
* Valid only if .version is > 0. See above.
* Get the AAIP string with encoded ACL and xattr.
* (Not to be confused with ECMA-119 Extended Attributes).
*
* bit1 and bit2 of flag should be implemented so that freshly fetched
* info does not include the undesired ACL or xattr. Nevertheless if the
* aa_string is cached, then it is permissible that ACL and xattr are still
* delivered.
*
* @param flag Bitfield for control purposes
* bit0= Transfer ownership of AAIP string data.
* src will free the eventual cached data and might
* not be able to produce it again.
* bit1= No need to get ACL (no guarantee of exclusion)
* bit2= No need to get xattr (no guarantee of exclusion)
* @param aa_string Returns a pointer to the AAIP string data. If no AAIP
* string is available, *aa_string becomes NULL.
* (See doc/susp_aaip_*_*.txt for the meaning of AAIP and
* libisofs/aaip_0_2.h for encoding and decoding.)
* The caller is responsible for finally calling free()
* on non-NULL results.
* @return 1 means success (*aa_string == NULL is possible)
* <0 means failure and must b a valid libisofs error code
* (e.g. ISO_FILE_ERROR if no better one can be found).
* @since 0.6.14
*/
int (*get_aa_string)(IsoFileSource *src,
unsigned char **aa_string, int flag);
/*
* TODO #00004 Add a get_mime_type() function.
* This can be useful for GUI apps, to choose the icon of the file
*/
};
/**
* An IsoFile Source is a POSIX abstraction of a file.
*
* @since 0.6.2
*/
struct iso_file_source
{
const IsoFileSourceIface *class;
int refcount;
void *data;
};
/**
* Representation of file contents. It is an stream of bytes, functionally
* like a pipe.
*
* @since 0.6.4
*/
typedef struct iso_stream IsoStream;
/**
* Interface that defines the operations (methods) available for an
* IsoStream.
*
* @see struct IsoStream_Iface
* @since 0.6.4
*/
typedef struct IsoStream_Iface IsoStreamIface;
/**
* Serial number to be used when you can't get a valid id for a Stream by other
* means. If you use this, both fs_id and dev_id should be set to 0.