Documentation improvements.
This commit is contained in:
Vreixo Formoso
parent
1c13429348
commit
2d4ed82048
60
doc/Tutorial
60
doc/Tutorial
@ -53,7 +53,7 @@ Thus, the first you need to do is to get your own IsoImage object:
|
||||
IsoImage *my_image;
|
||||
iso_image_new("NEW DISC", &my_image);
|
||||
|
||||
An IsoImage is a context for image creation. It holds the files than will be
|
||||
An IsoImage is a context for image creation. It holds the files that will be
|
||||
added to image, other related information and several options to customize
|
||||
the behavior of libisofs when working with such Image. i.e., an IsoImage is
|
||||
a context for libisofs operations. As such, you can work with several image
|
||||
@ -104,17 +104,23 @@ and that way distinguish what image has issued the message.
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
An image is built from a set of files that you want to store together in an
|
||||
ISO-9660 volume.
|
||||
ISO-9660 volume. We call the "iso tree" to the file hierarchy that will be
|
||||
written to image. The image context, IsoImage, holds that tree, together with
|
||||
configuration options and other properties of the image, that provide info
|
||||
about the volume (such as the identifier, author, etc...).
|
||||
|
||||
[TODO]
|
||||
All configuration options and volume properties are set by its corresponding
|
||||
setters (iso_image_set_volset_id(), iso_image_set_publisher_id()...)
|
||||
|
||||
[explain volume properties]
|
||||
|
||||
phases [TODO]:
|
||||
To create an image, you have to follow the following steps:
|
||||
|
||||
* Obtain the image context.
|
||||
See "1.2 Image context" for details of how to obtain the IsoImage.
|
||||
* Set the desired properties
|
||||
* Prepare the iso tree with the files you want to add to image.
|
||||
See "2.1 Image tree manipulation" for details
|
||||
* Select the options for image generation.
|
||||
See "2.2 Set the write options"
|
||||
* Get the burn_source used to actually write the image.
|
||||
|
||||
|
||||
@ -175,15 +181,29 @@ subtype, you can downcast a given IsoNode to the specific subtype.
|
||||
...
|
||||
}
|
||||
|
||||
or with the provided macros:
|
||||
|
||||
IsoDir *dir;
|
||||
IsoNode *node;
|
||||
|
||||
node = ISO_NODE(dir);
|
||||
|
||||
if (ISO_NODE_IS_DIR(node)) {
|
||||
dir = ISO_DIR(node);
|
||||
...
|
||||
}
|
||||
|
||||
* Adding files to the image
|
||||
|
||||
Files can be added to the image or iso tree either as new files or as files
|
||||
"imported" from the filesystem.
|
||||
from the filesystem.
|
||||
|
||||
In the first case, files are created directly on the image. They do not
|
||||
correspond to any file in the filesystem.
|
||||
correspond to any file in the filesystem. Provided functions are:
|
||||
|
||||
[...explain this kind of functions...]
|
||||
- iso_tree_add_new_dir()
|
||||
- iso_tree_add_new_symlink()
|
||||
- iso_tree_add_new_special()
|
||||
|
||||
On the other side, you can add local files to the image, either with the
|
||||
|
||||
@ -209,18 +229,36 @@ after adding them to the IsoImage.
|
||||
|
||||
* Recursive directory addition.
|
||||
|
||||
[TODO]
|
||||
One common use case is to add a local directory to the image. While this can
|
||||
be done with iso_tree_add_node(), handling the addition of directory children
|
||||
in the application, libisofs provides a function suitable for this case:
|
||||
|
||||
iso_tree_add_dir_rec()
|
||||
|
||||
that takes care of adding all files inside a directory, recursing on directory
|
||||
children. By default, this function adds all children. However, it is usual
|
||||
that you don't want really this. For example, you may want to exclude some
|
||||
kind of files (backup files, application sockets,...). Libisofs provides
|
||||
several functions to customize the behavior of that function:
|
||||
|
||||
- iso_tree_set_follow_symlinks()
|
||||
- iso_tree_set_ignore_hidden()
|
||||
- iso_tree_set_ignore_special()
|
||||
- iso_tree_add_exclude()
|
||||
|
||||
* Operations on iso tree
|
||||
|
||||
[TODO briefly explain how to add node, change attributes, ...]
|
||||
|
||||
* Replace mode
|
||||
|
||||
[TODO]
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
2.2 Set the write options
|
||||
|
||||
|
||||
Once you have prepared the iso tree, it is time to select the options for the
|
||||
image writing.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -68,32 +68,41 @@ struct burn_source;
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
typedef struct Iso_Node IsoNode;
|
||||
|
||||
/**
|
||||
* A directory in the iso tree. It is an special type of IsoNode and can be
|
||||
* casted to it in any case.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
typedef struct Iso_Special IsoSpecial;
|
||||
|
||||
/* 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)
|
||||
|
||||
typedef struct Iso_Dir_Iter IsoDirIter;
|
||||
|
||||
typedef struct el_torito_boot_image ElToritoBootImage;
|
||||
typedef struct Iso_Boot IsoBoot;
|
||||
|
||||
/**
|
||||
* The type of an IsoNode.
|
||||
*
|
||||
@ -117,6 +126,38 @@ enum IsoNodeType {
|
||||
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)
|
||||
|
||||
/**
|
||||
* Context for iterate on directory children.
|
||||
* @see iso_dir_get_children()
|
||||
*/
|
||||
typedef struct Iso_Dir_Iter IsoDirIter;
|
||||
|
||||
/**
|
||||
* It represents an El-Torito boot image.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
typedef struct Iso_Boot IsoBoot;
|
||||
|
||||
/**
|
||||
* Flag used to hide a file in the RR/ISO or Joliet tree.
|
||||
*
|
||||
@ -174,8 +215,23 @@ enum iso_replace_mode {
|
||||
*/
|
||||
};
|
||||
|
||||
/**
|
||||
* Options for image written.
|
||||
* @see iso_write_opts_new()
|
||||
*/
|
||||
typedef struct iso_write_opts IsoWriteOpts;
|
||||
|
||||
/**
|
||||
* Options for image reading or import.
|
||||
* @see iso_read_opts_new()
|
||||
*/
|
||||
typedef struct iso_read_opts IsoReadOpts;
|
||||
|
||||
/**
|
||||
* Source for image reading.
|
||||
*
|
||||
* @see struct iso_data_source
|
||||
*/
|
||||
typedef struct iso_data_source IsoDataSource;
|
||||
|
||||
/**
|
||||
@ -275,8 +331,26 @@ struct iso_read_image_features
|
||||
unsigned int hasElTorito :1;
|
||||
};
|
||||
|
||||
/**
|
||||
* POSIX abstraction for source files.
|
||||
*
|
||||
* @see struct iso_file_source
|
||||
*/
|
||||
typedef struct iso_file_source IsoFileSource;
|
||||
|
||||
/**
|
||||
* Abstract for source filesystems.
|
||||
*
|
||||
* @see struct iso_filesystem
|
||||
*/
|
||||
typedef struct iso_filesystem IsoFilesystem;
|
||||
|
||||
/**
|
||||
* Interface that defines the operations (methods) available for an
|
||||
* IsoFileSource.
|
||||
*
|
||||
* @see struct IsoFileSource_Iface
|
||||
*/
|
||||
typedef struct IsoFileSource_Iface IsoFileSourceIface;
|
||||
|
||||
/**
|
||||
@ -637,6 +711,10 @@ int iso_lib_is_compatible(int major, int minor, int micro);
|
||||
* Options by default are determined by the selected profile. Fifo size is set
|
||||
* by default to 2 MB.
|
||||
*
|
||||
* @param opts
|
||||
* Pointer to the location where the newly created IsoWriteOpts will be
|
||||
* stored. You should free it with iso_write_opts_free() when no more
|
||||
* needed.
|
||||
* @param profile
|
||||
* Default profile for image creation. For now the following values are
|
||||
* defined:
|
||||
@ -948,7 +1026,8 @@ int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size);
|
||||
* @param image
|
||||
* The image to write.
|
||||
* @param opts
|
||||
* The options for image generation.
|
||||
* The options for image generation. All needed data will be copied, so
|
||||
* you can free the given struct once this function returns.
|
||||
* @param burn_src
|
||||
* Location where the pointer to the burn_source will be stored
|
||||
* @return
|
||||
@ -964,6 +1043,10 @@ int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts,
|
||||
*
|
||||
* Options by default are determined by the selected profile.
|
||||
*
|
||||
* @param opts
|
||||
* Pointer to the location where the newly created IsoReadOpts will be
|
||||
* stored. You should free it with iso_read_opts_free() when no more
|
||||
* needed.
|
||||
* @param profile
|
||||
* Default profile for image reading. For now the following values are
|
||||
* defined:
|
||||
@ -1058,7 +1141,8 @@ int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset);
|
||||
* Data Source from which old image will be read. A extra reference is
|
||||
* added, so you still need to iso_data_source_unref() yours.
|
||||
* @param opts
|
||||
* Options for image import
|
||||
* Options for image import. All needed data will be copied, so you
|
||||
* can free the given struct once this function returns.
|
||||
* @param features
|
||||
* If not NULL, a new struct iso_read_image_features will be allocated
|
||||
* and filled with the features of the old image. It should be freed when
|
||||
|
||||
Loading…
Reference in New Issue
Block a user