223 lines
8.4 KiB
C
223 lines
8.4 KiB
C
|
|
/*
|
|
API definition of libisoburn.
|
|
|
|
Copyright 2007 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
|
|
and Thomas Schmitt <scdbackup@gmx.net>
|
|
*/
|
|
|
|
/**
|
|
|
|
libisoburn is a frontend for libraries libburn and libisofs which enables
|
|
creation and expansion of ISO-9660 filesystems on all CD/DVD media supported
|
|
by libburn. This includes media like DVD+RW, which do not support multi-session
|
|
management on media level and even plain disk files or block devices.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
E.g. call isoburn_initialize() rather than iso_init(); burn_initialize()
|
|
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".
|
|
|
|
*/
|
|
|
|
|
|
/* API functions */
|
|
|
|
|
|
/** Initialize libisoburn, libisofs and libburn.
|
|
Wrapper for : iso_init() and burn_initialize()
|
|
@return 1 indicates success, 0 is failure
|
|
*/
|
|
int isoburn_initialize(void);
|
|
|
|
|
|
/** Aquire a target drive by its filesystem path resp. libburn persistent
|
|
address.
|
|
Wrapper for: burn_drive_scan_and_grab()
|
|
*/
|
|
int isoburn_drive_scan_and_grab(struct burn_drive_info *drive_infos[],
|
|
char* adr, int load);
|
|
|
|
|
|
/** Aquire a drive from the burn_drive_info[] array which was obtained by
|
|
a previous call of burn_drive_scan().
|
|
Wrapper for: burn_drive_grab()
|
|
*/
|
|
int isoburn_drive_grab(struct burn_drive *drive, int load);
|
|
|
|
|
|
/** Inquire the media status. Expect the whole spectrum of libburn BURN_DISC_*
|
|
with multi-session media. Emulated states with random access media are
|
|
BURN_DISC_BLANK and BURN_DISC_APPENDABLE.
|
|
Wrapper for: burn_disc_get_status()
|
|
*/
|
|
enum burn_disc_status isoburn_disc_get_status(struct burn_drive *drive);
|
|
|
|
|
|
/** Tells whether the media can be treated by isoburn_disc_erase().
|
|
Wrapper for: burn_disc_erasable()
|
|
*/
|
|
int isoburn_disc_erasable(struct burn_drive *d);
|
|
|
|
|
|
/** Mark the media as blank. With multi-session media this will call
|
|
burn_disc_erase(). With random access media, an eventual ISO-9660
|
|
filesystem will get invalidated by altering its start blocks on media.
|
|
In case of success, the media is in status BURN_DISC_BLANK afterwards.
|
|
Wrapper for: burn_disc_erase()
|
|
*/
|
|
void isoburn_disc_erase(struct burn_drive *drive, int fast);
|
|
|
|
/**
|
|
* Options for image reading.
|
|
*/
|
|
struct isoburn_read_opts {
|
|
unsigned int norock:1; /*< Do not read Rock Ridge extensions */
|
|
unsigned int nojoliet:1; /*< Do not read Joliet extensions */
|
|
unsigned int preferjoliet:1;
|
|
/*< When both Joliet and RR extensions are present, the RR
|
|
* tree is used. If you prefer using Joliet, set this to 1. */
|
|
uid_t uid; /**< Default uid when no RR */
|
|
gid_t gid; /**< Default uid when no RR */
|
|
mode_t mode; /**< Default mode when no RR (only permissions) */
|
|
|
|
/* modified by the function isoburn_read_volset */
|
|
unsigned int hasRR:1; /*< It will be set to 1 if RR extensions are present,
|
|
to 0 if not. */
|
|
unsigned int hasJoliet:1; /*< It will be set to 1 if Joliet extensions are
|
|
present, to 0 if not. */
|
|
uint32_t size; /**< Will be filled with the size (in 2048 byte block) of
|
|
* the image, as reported in the PVM. */
|
|
};
|
|
|
|
|
|
/** Load the ISO filesystem directory tree from the media in the given drive.
|
|
This will give libisoburn the base on which it can let libisofs perform
|
|
image growing or image modification. The loaded volset gets attached
|
|
to the drive object and is not publicly available.
|
|
Not a wrapper, but peculiar to libisoburn.
|
|
@param d The drive which holds an existing ISO filesystem
|
|
@param read_opts The read options which can be chosen by the application
|
|
@param volset the volset that represents the image, or NULL if the image is
|
|
empty.
|
|
<<<<< What about return a volset without file if image is
|
|
empty <<<<<<<<<
|
|
@return <=0 error , 1 = success
|
|
>>>>> error means damaged or unsupported image
|
|
error code is stored in ecma119_read_opts in libisofs
|
|
also error msgs are enqueued. Any need to pass them to usr? <<<<<<
|
|
*/
|
|
int isoburn_read_volset(struct burn_drive *d, struct isoburn_read_opts *read_opts,
|
|
struct iso_volset **volset);
|
|
|
|
|
|
/** Obtain the start block number of the most recent session on media. In
|
|
case of random access media this will always be 0. Succesfull return is
|
|
not a guarantee that there is a ISO-9660 image at all. The call will fail,
|
|
nevertheless,if isoburn_disc_get_status() returns not BURN_DISC_APPENDABLE.
|
|
Wrapper for: burn_disc_get_msc1()
|
|
*/
|
|
int isoburn_disc_get_msc1(struct burn_drive *d, int *start_lba);
|
|
|
|
|
|
/** Use this with trackno==0 to obtain the predicted start block number of the
|
|
new session. The interesting number is returned in parameter nwa.
|
|
Wrapper for: burn_disc_track_lba_nwa()
|
|
*/
|
|
int isoburn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o,
|
|
int trackno, int *lba, int *nwa);
|
|
|
|
|
|
/** Prepare a disc for writting the new session.
|
|
@param disc A burn_disc suitable to pass to isoburn_disc_write.
|
|
@return <=0 error , 1 = success
|
|
*/
|
|
int isoburn_prepare_disc(struct burn_drive *d, struct burn_disc **disc);
|
|
|
|
/** Start writing of the new session.
|
|
This call is asynchrounous. I.e. it returns quite soon and the progress has
|
|
to be watched by a loop with call burn_drive_get_status() until
|
|
BURN_DRIVE_IDLE is returned.
|
|
Wrapper for: burn_disc_write()
|
|
*/
|
|
void isoburn_disc_write(struct burn_write_opts *o, struct burn_disc *disc);
|
|
|
|
|
|
/** Call this after isoburn_disc_write has finished and burn_drive_wrote_well()
|
|
indicates success. It will eventually complete the emulation of
|
|
multi-session functionality, if needed at all. Let libisoburn decide.
|
|
Not a wrapper, but peculiar to libisoburn.
|
|
*/
|
|
int isoburn_activate_session(struct burn_drive *drive);
|
|
|
|
/** Write a new session to a disc.
|
|
This is a synchrounous call equivalent to isoburn_prepare_disc +
|
|
isoburn_disc_write + isoburn_activate_session
|
|
@param pacifier_func If not NULL: a function to produce appeasing messages.
|
|
See burn_abort_pacifier() in libburn.h for an example.
|
|
*/
|
|
int isoburn_perform_write(struct burn_write_opts *o,
|
|
int (*pacifier_func)(void *handle, int patience,
|
|
int elapsed));
|
|
|
|
|
|
/** Release an aquired drive.
|
|
Wrapper for: burn_drive_release()
|
|
*/
|
|
void isoburn_drive_release(struct burn_drive *drive, int eject);
|
|
|
|
|
|
/** Shutdown all three libraries.
|
|
Wrapper for : iso_finish() and burn_finish().
|
|
*/
|
|
void isoburn_finish(void);
|
|
|
|
|
|
/*
|
|
The following two calls are for expert applications only.
|
|
An application should have a special reason to use them.
|
|
*/
|
|
|
|
|
|
/** Inquire wether the media needs emulation or would be suitable for
|
|
generic multi-session via libburn.
|
|
@return 0 is generic multi-session
|
|
1 is emulated multi-session
|
|
-1 is not suitable for isoburn
|
|
*/
|
|
int isoburn_needs_emulation(struct burn_drive *drive);
|
|
|
|
|
|
#ifdef Libburn_obsoleted_on_its_way_ouT
|
|
|
|
/** Caution: Use this with great care. It is not needed normally.
|
|
|
|
This call can set the nwa block number to an arbitrary value. If ever, do
|
|
this before preparing the session by libisofs. The drive must be grabbed,
|
|
though. This overrides the automated address computation. Call
|
|
isoburn_disc_track_lba_nwa() afterwards to learn the effective new
|
|
address which might be somewhat higher than set by parameter value.
|
|
Wrapper for: burn_write_opts_set_start_byte (if ever)
|
|
*/
|
|
void isoburn_write_opts_set_start_byte(struct burn_write_opts *opts,
|
|
off_t value);
|
|
|
|
#endif /* Libburn_obsoleted_on_its_way_ouT */
|
|
|