libburnia/legacy
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updated API introduction and marked API instabilities for mending (soon)

Browse Source
This commit is contained in:
Thomas Schmitt 2008-01-28 14:02:48 +00:00
parent 68a942495f
commit fd8282b58c
2 changed files with 108 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
libisoburn/trunk/libisoburn/libisoburn.h
View File

@ -2,11 +2,11 @@
/*
API definition of libisoburn.
Copyright 2007 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
and Thomas Schmitt <scdbackup@gmx.net>
Copyright 2007-2008 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
and Thomas Schmitt <scdbackup@gmx.net>
*/
/**
/** Overview
libisoburn is a frontend for libraries libburn and libisofs which enables
creation and expansion of ISO-9660 filesystems on all CD/DVD media supported
@ -17,6 +17,8 @@ The price for that is thorough specialization on data files in ISO-9660
filesystem images. So libisoburn is not suitable for audio (CD-DA) or any
other CD layout which does not entirely consist of ISO-9660 sessions.
Wrapper functions
The priciple of this frontend is that you may use any call of libisofs or
libburn unless it has a isoburn_*() wrapper listed in the following function
documentation.
@ -26,13 +28,80 @@ and call isoburn_drive_scan_and_grab() rather than burn_drive_scan_and_grab().
But you may call burn_disc_get_profile() directly if you want to display
the media type.
>>>
>>> Take into respect Vreixo's (mandatory ?) shortcuts which are to come
>>>
The usage model is like with libburn: the target is a "media" in a "drive".
The wrappers will transparently provide the necessary emulations which
are appropriate for particular target "drives".
are appropriate for particular target "drives" and media states.
To learn about them you have to read both API descriptions: the one of
the wrapper and the one of the underlying libburn or libisofs call.
Usage model
Additionally there are own libisoburn API calls which allow to implement the
following usage model (see also man xorriso for a end user's view):
There may be an input drive and an output drive. Either of them may be missing
with the consequence that no reading resp. writing is possible.
Both drive roles can be fulfilled by the same drive.
Input can be a random access readable libburn drive:
optical media, regular files, block devices.
Output can be any writeable libburn drive:
writeable optical media in burner, writeable file objects (no directories).\
libburn needs rw-permissions to drive device file resp. file object.
If the input drive provides a suitable ISO RockRidge image, then its tree
may be loaded into memory and can then be manipulated by libisofs API calls.
The loading is done by isoburn_read_image() under control of
struct isoburn_read_opts
>>> which the application obtains from libisoburn.
Writing of result images is controlled by libisofs related parameters
in struct isoburn_source_opts
>>> which the application obtains from libisoburn.
All multi-session aspects are handled by libisoburn according to these
settings. The application does not have to analyze media state and write
job parameters.
Setup for Growing or Modifying
There are two alternative API calls for performing the setup for two
alternative image generation strategies.
Growing:
If input and output drive is the same, then isoburn_prepare_disc() is to
be used. It will lead to an add-on session on appendable or overwriteable
media with existing ISO image. With blank media it will produce a first
session.
Modifying:
If the output drive is not the input drive, then it has to bear blank media
or overwriteable without a valid ISO image. To prepare for such an image
generation run, use isoburn_prepare_new_image(). The run will copy file data
from an eventual input drive with valid image, add any newly introduced data
from the local filesystem, and produce a first session on output media.
After either of these setups, some peripheral libburn drive parameter settings
like burn_write_opts_set_simulate(), burn_write_opts_set_multi(),
burn_drive_set_speed(), burn_write_opts_set_underrun_proof() should be made.
Do not set the write mode. It will be chosen by libisoburn so it matches job
and media state.
Writing the image
Then one may start image generation and write threads by isoburn_disc_write().
Progress may be watched at the output drive by burn_drive_get_status() and
isoburn_get_fifo_status().
At some time, the output drive will be BURN_DRIVE_IDLE indicating that
writing has ended.
One should inquire isoburn_drive_wrote_well() to learn about overall success.
Finally one must call isoburn_activate_session() which will finalize any
eventual multi-session emulation.
*/
@ -64,6 +133,8 @@ int isoburn_initialize(char msg[1024], int flag);
void isoburn_version(int *major, int *minor, int *micro);
/* >>> isoburn_is_compatible() */
/** Aquire a target drive by its filesystem path resp. libburn persistent
address.
@ -102,6 +173,8 @@ int isoburn_disc_erasable(struct burn_drive *d);
*/
void isoburn_disc_erase(struct burn_drive *drive, int fast);
/* >>> this goes to isoburn.h */
/**
* Options for image reading.
*/
@ -141,6 +214,7 @@ struct isoburn_read_opts {
unsigned int pretend_blank:1; /* always create empty image */
};
/* >>> this goes to isoburn.h */
/**
* Options for image generation by libisofs and image transport to libburn.
*/
@ -250,6 +324,11 @@ struct isoburn_source_opts {
};
/* >>> Opaque definitions of isoburn_read_opts and isoburn_source_opts */
/* >>> Constructors, destructors, getters, setters. */
/* >>> Learn what libisofs does */
/** Get the image attached to a drive, if any.
@return A reference to attached image, or NULL if the drive has no image
attached. This reference needs to be released via iso_image_unref()
@ -348,22 +427,26 @@ int isoburn_prepare_disc(struct burn_drive *d, struct burn_disc **disc,
/** Create a disc object for producing a new image from a previous image
plus the changes made by user. The generated burn_disc is suitable
to be written to any other libburn drive. You must not use the same drive
for writing as you are using here as source, because data will be
read from the source drive while the target drive gets written to.
to be written to any grabbed libburn drive with blank writeable media.
But you must not use the same drive for input and output, because data
will be read from the source drive while at the same time the target
drive is already writing.
The resulting burn_disc object has to be disposed when all its writing
is done and the drive is BURN_DRIVE_IDLE again after asynchronous
burn_disc_write().
@param d The source drive, grabbed with isoburn_drive_scan_and_grab().
@param disc Returns the newly created burn_disc object.
@param opts Options for image generation and data transport to media
@param in_drive The input drive,grabbed with isoburn_drive_scan_and_grab().
@param disc Returns the newly created burn_disc object.
@param opts Options for image generation and data transport to media.
@param out_drive The libburn drive which shall be write target.
Submit libisoburn drives to later get access to libisofs
source fifo via isoburn_get_fifo_status().
If that is not desired, then out_drive may be NULL.
If the drive was grabbed via libisoburn then it can later
access the libisofs source fifo via
isoburn_get_fifo_status().
Mere libburn drives cannot obtain this info.
In that case out_drive may be NULL, as well.
@return <=0 error , 1 = success
*/
int isoburn_prepare_new_image(struct burn_drive *d, struct burn_disc **disc,
int isoburn_prepare_new_image(struct burn_drive *in_drive,
struct burn_disc **disc,
struct isoburn_source_opts *opts,
struct burn_drive *out_drive);
@ -417,6 +500,8 @@ int isoburn_drive_wrote_well(struct burn_drive *d);
int isoburn_activate_session(struct burn_drive *drive);
#if 0
/* >>> NOT YET IMPLEMENTED <<< */
/** Write a new session to a disc.
This is a synchronous call equivalent to isoburn_prepare_disc +
isoburn_disc_write + isoburn_activate_session
@ -427,6 +512,8 @@ int isoburn_activate_session(struct burn_drive *drive);
int isoburn_perform_write(struct burn_write_opts *o,
int (*pacifier_func)(void *handle, int patience,
int elapsed));
#endif /* 0 */
/** Release an aquired drive.
Wrapper for: burn_drive_release()
@ -441,7 +528,7 @@ void isoburn_finish(void);
/*
The following two calls are for expert applications only.
The following calls are for expert applications only.
An application should have a special reason to use them.
*/

2
libisoburn/trunk/xorriso/xorriso_timestamp.h
View File

@ -1 +1 @@
#define Xorriso_timestamP "2008.01.28.105404"
#define Xorriso_timestamP "2008.01.28.140149"