Updated API introduction and marked API instabilities for mending (soon)

libisoburn/libisoburn.h

@@ -2,11 +2,11 @@
 /*
   API definition of libisoburn.
 
-  Copyright 2007 Vreixo Formoso Lopes <metalpain2002@yahoo.es>
+  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
+    to be written to any grabbed libburn drive with blank writeable media.
-    for writing as you are using here as source, because data will be
+    But you must not use the same drive for input and output, because data
-    read from the source drive while the target drive gets written to.
+    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 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 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
+                     If the drive was grabbed via libisoburn then it can later
-                     source fifo via isoburn_get_fifo_status().
+                     access the libisofs source fifo via
-                     If that is not desired, then out_drive may be NULL.
+                     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.
 */
 

xorriso/xorriso_timestamp.h

@@ -1 +1 @@
-#define Xorriso_timestamP "2008.01.28.105404"
+#define Xorriso_timestamP "2008.01.28.140149"