libisoburn/libisoburn/libisoburn.h

158 lines
5.6 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
>>> to come: and even plain disk files or other random access file types.
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
idocumentation.
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.
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".
>>> Technical remark:
>>> For full support of plain files, libburn needs to get a null-drive
>>> which swallows all libburn calls which are not wrapped in isoburn calls.
>>> I had a count: ~ 50 API calls with struct burn_drive or
>>> struct burn_write_opts to curb :))
*/
/* 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);
/** 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);
/** 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);
/** 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 libburn.
*/
int isoburn_activate_session(struct burn_drive *drive);
/** 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);
/** 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);