458 lines
19 KiB
C
458 lines
19 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()
|
|
@param reason A character array for eventual messages (e.g. with errors)
|
|
@param flag Bitfield for control purposes (unused yet, submit 0)
|
|
@return 1 indicates success, 0 is failure
|
|
*/
|
|
int isoburn_initialize(char msg[1024], int flag);
|
|
|
|
|
|
/** Obtain the three release version numbers of the library.
|
|
@param major The maturity version (0 for now, as we are still learning)
|
|
@param minor The development goal version.
|
|
@param micro The development step version. This has an additional meaning:
|
|
Pare numbers indicate a version with frozen API. I.e. you can
|
|
rely on the same set of features to be present in all
|
|
published releases with that major.minor.micro combination.
|
|
Odd numbers indicate that API upgrades are in progress.
|
|
I.e. new features might be already present or they might
|
|
be still missing. You need to check before compiling an
|
|
application which relies on freshly introduced features.
|
|
*/
|
|
void isoburn_version(int *major, int *minor, int *micro);
|
|
|
|
|
|
|
|
/** 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 noiso1999:1; /*< Do not read ISO 9660:1999 enhanced tree */
|
|
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) */
|
|
|
|
/**
|
|
* Input charset for RR file names. NULL to use default locale charset.
|
|
*/
|
|
char *input_charset;
|
|
|
|
/* modified by the function isoburn_read_image */
|
|
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. */
|
|
|
|
/**
|
|
* It will be set to 1 if the image is an ISO 9660:1999, i.e. it has
|
|
* a version 2 Enhanced Volume Descriptor.
|
|
*/
|
|
unsigned int hasIso1999:1;
|
|
|
|
/** It will be set to 1 if El-Torito boot record is present, to 0 if not.*/
|
|
unsigned int hasElTorito:1;
|
|
|
|
uint32_t size; /**< Will be filled with the size (in 2048 byte block) of
|
|
* the image, as reported in the PVM. */
|
|
unsigned int pretend_blank:1; /* always create empty image */
|
|
};
|
|
|
|
/**
|
|
* Options for image generation by libisofs and image transport to libburn.
|
|
*/
|
|
struct isoburn_source_opts {
|
|
|
|
/* Options for image generation */
|
|
|
|
int level; /**< ISO level to write at. */
|
|
|
|
/** Which extensions to support. */
|
|
unsigned int rockridge :1;
|
|
unsigned int joliet :1;
|
|
unsigned int iso1999 :1;
|
|
|
|
/* relaxed constraints */
|
|
|
|
/*
|
|
* Relaxed constraints. Setting any of these to 1 break the specifications,
|
|
* but it is supposed to work on most moderns systems. Use with caution.
|
|
*/
|
|
|
|
/**
|
|
* Omit the version number (";1") at the end of the ISO-9660 identifiers.
|
|
* Version numbers are usually not used.
|
|
*/
|
|
unsigned int omit_version_numbers :1;
|
|
|
|
/**
|
|
* Allow ISO-9660 directory hierarchy to be deeper than 8 levels.
|
|
*/
|
|
unsigned int allow_deep_paths :1;
|
|
|
|
/**
|
|
* Allow path in the ISO-9660 tree to have more than 255 characters.
|
|
*/
|
|
unsigned int allow_longer_paths :1;
|
|
|
|
/**
|
|
* Allow a single file or directory hierarchy to have up to 37 characters.
|
|
* This is larger than the 31 characters allowed by ISO level 2, and the
|
|
* extra space is taken from the version number, so this also forces
|
|
* omit_version_numbers.
|
|
*/
|
|
unsigned int max_37_char_filenames :1;
|
|
|
|
/**
|
|
* ISO-9660 forces filenames to have a ".", that separates file name from
|
|
* extension. libisofs adds it if original filename doesn't has one. Set
|
|
* this to 1 to prevent this behavior
|
|
*/
|
|
unsigned int no_force_dots :1;
|
|
|
|
/**
|
|
* Allow lowercase characters in ISO-9660 filenames. By default, only
|
|
* uppercase characters, numbers and a few other characters are allowed.
|
|
*/
|
|
unsigned int allow_lowercase :1;
|
|
|
|
/**
|
|
* Allow all ASCII characters to be appear on an ISO-9660 filename. Note
|
|
* that "/" and "\0" characters are never allowed, even in RR names.
|
|
*/
|
|
unsigned int allow_full_ascii :1;
|
|
|
|
/**
|
|
* Allow paths in the Joliet tree to have more than 240 characters.
|
|
*/
|
|
unsigned int joliet_longer_paths :1;
|
|
|
|
unsigned int sort_files:1;
|
|
/**< If files should be sorted based on their weight. */
|
|
|
|
/**
|
|
* The following options set the default values for files and directory
|
|
* permissions, gid and uid. All these take one of three values: 0, 1 or 2.
|
|
* If 0, the corresponding attribute will be kept as set in the IsoNode.
|
|
* Unless you have changed it, it corresponds to the value on disc, so it
|
|
* is suitable for backup purposes. If set to 1, the corresponding attrib.
|
|
* will be changed by a default suitable value. Finally, if you set it to
|
|
* 2, the attrib. will be changed with the value specified in the options
|
|
* below. Note that for mode attributes, only the permissions are set, the
|
|
* file type remains unchanged.
|
|
*/
|
|
unsigned int replace_dir_mode :2;
|
|
unsigned int replace_file_mode :2;
|
|
unsigned int replace_uid :2;
|
|
unsigned int replace_gid :2;
|
|
|
|
mode_t dir_mode; /** Mode to use on dirs when replace_dir_mode == 2. */
|
|
mode_t file_mode; /** Mode to use on files when replace_file_mode == 2. */
|
|
uid_t uid; /** uid to use when replace_uid == 2. */
|
|
gid_t gid; /** gid to use when replace_gid == 2. */
|
|
|
|
char *output_charset; /**< NULL to use default charset */
|
|
|
|
|
|
/* Options for image transport */
|
|
|
|
/** The number of bytes to be used for the fifo which decouples libisofs
|
|
and libburn for better throughput and for reducing the risk of
|
|
interrupting signals hitting the libburn thread which operates the
|
|
MMC drive.
|
|
The size will be rounded up to the next full 2048.
|
|
Minimum is 64kiB, maximum is 1 GiB (but that is too much anyway).
|
|
*/
|
|
int fifo_size;
|
|
|
|
};
|
|
|
|
/** 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()
|
|
when it is not longer needed.
|
|
*/
|
|
IsoImage *isoburn_get_attached_image(struct burn_drive *d);
|
|
|
|
/** 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 handed out to the application.
|
|
Not a wrapper, but peculiar to libisoburn.
|
|
@param d The drive which holds an existing ISO filesystem or blank media.
|
|
d is allowed to be NULL which produces an empty ISO image. In
|
|
this case one has to call before writing isoburn_attach_volset()
|
|
with the volset from this call and with the intended output
|
|
drive.
|
|
@param read_opts The read options which can be chosen by the application
|
|
@param image the image read, if the disc is blank it will have no files.
|
|
This reference needs to be released via iso_image_unref() when
|
|
it is not longer needed. The drive, if not NULL, will hold an
|
|
own reference which it will release when it gets a new volset
|
|
or when it gets released via isoburn_drive_release().
|
|
You can pass NULL if you already have a reference or you plan to
|
|
obtain it later with isoburn_get_attached_image(). Of course, if
|
|
you haven't specified a valid drive (i.e., if d == NULL), this
|
|
parameter can't be NULL.
|
|
@return <=0 error , 1 = success
|
|
*/
|
|
int isoburn_read_image(struct burn_drive *d,
|
|
struct isoburn_read_opts *read_opts,
|
|
IsoImage **image);
|
|
|
|
|
|
/** Set the IsoImage to be used with a drive. This eventually releases
|
|
the reference to the old IsoImage attached to the drive.
|
|
Caution: Use with care. It hardly makes sense to replace an image that
|
|
reflects a valid ISO image on media.
|
|
This call is rather intended for writing a newly created and populated
|
|
image to blank media. The use case in xorriso is to let an image survive
|
|
the change or demise of the outdev target drive.
|
|
@param d The drive which shall be write target of the volset.
|
|
@param image The image that represents the image to be written.
|
|
This image pointer MUST already be a valid reference suitable
|
|
for iso_image_unref().
|
|
It may have been obtained by appropriate libisofs calls or by
|
|
isoburn_read_image() with d==NULL.
|
|
@return <=0 error , 1 = success
|
|
*/
|
|
int isoburn_attach_image(struct burn_drive *d, IsoImage *image);
|
|
|
|
|
|
/** 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);
|
|
|
|
|
|
/** Obtain the size which was attributed to an emulated appendable on actually
|
|
overwriteable media. This value is supposed to be <= 2048 * nwa as of
|
|
isoburn_disc_track_lba_nwa().
|
|
@param drive The drive holding the media.
|
|
@param start_byte The reply value counted in bytes, not in sectors.
|
|
@param flag Unused yet. Submit 0.
|
|
@return 1=stat_byte is valid, 0=not an emulated appendable, -1=error
|
|
*/
|
|
int isoburn_get_min_start_byte(struct burn_drive *d, off_t *start_byte,
|
|
int flag);
|
|
|
|
|
|
/** Create a disc object for writing the new session from the created or loaded
|
|
iso_volset which has been manipulated via libisofs, to the same media from
|
|
where the image was eventually loaded. This struct burn_disc is ready for
|
|
use by a subsequent call to isoburn_disc_write().
|
|
After this asynchronous writing has ended and the drive is BURN_DRIVE_IDLE
|
|
again, the burn_disc object has to be disposed by burn_disc_free().
|
|
@param drive The combined source and target drive, grabbed with
|
|
isoburn_drive_scan_and_grab(). .
|
|
@param disc Returns the newly created burn_disc object.
|
|
@return <=0 error , 1 = success
|
|
*/
|
|
int isoburn_prepare_disc(struct burn_drive *d, struct burn_disc **disc,
|
|
struct isoburn_source_opts *opts);
|
|
|
|
|
|
/** 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.
|
|
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 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.
|
|
@return <=0 error , 1 = success
|
|
*/
|
|
int isoburn_prepare_new_image(struct burn_drive *d, struct burn_disc **disc,
|
|
struct isoburn_source_opts *opts,
|
|
struct burn_drive *out_drive);
|
|
|
|
/** 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);
|
|
|
|
|
|
/** Inquire state and fill parameters of the fifo which is attached to
|
|
the emerging track. This should be done in the pacifier loop while
|
|
isoburn_disc_write() or burn_disc_write() are active.
|
|
This works only with drives obtained by isoburn_drive_scan_and_grab()
|
|
or isoburn_drive_grab(). If isoburn_prepare_new_image() was used, then
|
|
parameter out_drive must have announced the track output drive.
|
|
Hint: If only burn_write_opts and not burn_drive is known, then the drive
|
|
can be obtained by burn_write_opts_get_drive().
|
|
@parm d The drive to which the track with the fifo gets burned.
|
|
@param size The total size of the fifo
|
|
@param free_bytes The current free capacity of the fifo
|
|
@param status_text Returns a pointer to a constant text, see below
|
|
@return <0 reply invalid, >=0 fifo status code:
|
|
bit0+1=input status, bit2=consumption status, i.e:
|
|
0="standby" : data processing not started yet
|
|
1="active" : input and consumption are active
|
|
2="ending" : input has ended without error
|
|
3="failing" : input had error and ended,
|
|
4="unused" : ( consumption has ended before processing start )
|
|
5="abandoned" : consumption has ended prematurely
|
|
6="ended" : consumption has ended without input error
|
|
7="aborted" : consumption has ended after input error
|
|
*/
|
|
int isoburn_get_fifo_status(struct burn_drive *d, int *size, int *free_bytes,
|
|
char **status_text);
|
|
|
|
|
|
/** Inquire whether the most recent write run was successful.
|
|
Wrapper for: burn_drive_wrote_well()
|
|
*/
|
|
int isoburn_drive_wrote_well(struct burn_drive *d);
|
|
|
|
|
|
/** 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 synchronous 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.
|
|
*/
|
|
/* TODO implement this */
|
|
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);
|
|
|
|
|