From 4697182efd91ce744f931e2efaf2db7497868a5d Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Mon, 28 Jan 2008 14:02:48 +0000 Subject: [PATCH] Updated API introduction and marked API instabilities for mending (soon) --- libisoburn/libisoburn.h | 127 ++++++++++++++++++++++++++++++------ xorriso/xorriso_timestamp.h | 2 +- 2 files changed, 108 insertions(+), 21 deletions(-) diff --git a/libisoburn/libisoburn.h b/libisoburn/libisoburn.h index 2506debc..f181bdf7 100644 --- a/libisoburn/libisoburn.h +++ b/libisoburn/libisoburn.h @@ -2,11 +2,11 @@ /* API definition of libisoburn. - Copyright 2007 Vreixo Formoso Lopes - and Thomas Schmitt + Copyright 2007-2008 Vreixo Formoso Lopes + and Thomas Schmitt */ -/** +/** 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. */ diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index 93298d93..13c192e2 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2008.01.28.105404" +#define Xorriso_timestamP "2008.01.28.140149"