|
|
|
|
@ -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.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
