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