Updated docs about existence of xorriso API in libisoburn

README

@@ -18,7 +18,9 @@ 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.
 
-xorriso is a command line application of libisoburn, libisofs, and libburn.
+xorriso is an application of libisoburn, libisofs, and libburn, which reads
+commands from program arguments, files, stdin, or readline.
+Its features are also available via a C language API of libisoburn.
 
 Currently they are fully supported on Linux with kernels >= 2.4,
 on FreeBSD with ATAPI/CAM support enabled in the kernel, see atapicam(4),
@@ -33,7 +35,7 @@ By using this software you agree to the disclaimer at the end of this text:
                    Compilation, First Glimpse, Installation
 
 Dynamic library and compile time header requirements for libisoburn-0.5.6 :
-- libburn.so.4  , version libburn-0.7.8 or higher
+- libburn.so.4  , version libburn-0.8.2 or higher
 - libisofs.so.6 , version libisofs-0.6.32 or higher
 libisoburn and xorriso will not start with libraries which are older than their
 headers seen at compile time.
@@ -101,12 +103,34 @@ if 64 KB rather than 32 KB are transmitted in each write operation.
     --enable-dvd-obs-64k
 
 
+                      xorriso C language API
+
+Actually the dynamically linked xorriso binary is only a small start program
+for the xorriso API that is implemented inside libisoburn.
+There are API calls for command readers and interpreters, and there are
+API calls for each single command of xorriso.
+
+Interested programmers should have a look into the API definition at
+  xorriso/xorriso.h
+and the start program
+  xorriso/xorriso_main.c
+
+The header file  xorriso.h  gets installed suitable for
+  #include <libisoburn/xorriso.h>
+
+So after installation of a binary libisoburn package you may find it e.g. as
+  /usr/local/include/libisoburn/xorriso.h
+
+
+
                        Drives and Disk File Objects 
 
 The user of libisoburn applications needs rw-permission for the CD/DVD/BD
 drives which shall be used, even if only reading is intended.
 A list of rw-accessible drives can be obtained by
     xorriso -devices
+resp. by xorriso API call
+    Xorriso_option_devices()
 resp. by libburn API call
     burn_drive_scan()
 

xorriso/xorriso.h

@@ -152,8 +152,71 @@ int Xorriso__preset_signal_behavior(int behavior, int flag);
 int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag);
 
 
-/* Interpret certain commands which shall get into effect before the
+/* Note: Between Xorriso_new() and the next call Xorriso_startup_libraries()
-   libraries get initialized:
+         there may be called the special command interpreter
+         Xorriso_prescan_args().
+         The other command interpreters may be used only after
+         Xorriso_startup_libraries(). The same restriction applies to the
+         calls of the Options API further below.
+*/
+
+
+/* Mandatory call:
+   It has to be made before calling any function listed below this point.
+   Only exception is the special command interpreter Xorriso_prescan_args().
+
+   Make global library initializations.
+   This must be done with the first xorriso object that gets created and
+   with the first xorriso object that gets created after Xorriso_destroy(,1).
+   @param xorriso The context object.
+   @param flag    unused yet, submit 0
+   @return        <=0 error , >0 success
+*/ 
+int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag);
+
+
+/* Note: After library startup, you may run Command Interpreters or call
+         functions from the Options API.
+
+         Wenn all desired activities are done, you may check whether there are
+         uncommited chages pending, compute an exit value, destroy the XorrisO
+         object, and exit your program.
+*/
+
+
+/* Inquire whether option -commit would make sense.
+   @param xorriso The context object to inquire.
+   @param flag    unused yet, submit 0
+   @return        0= -commit would have nothing to do
+                  1= a new image session would emerge at -commit
+*/
+int Xorriso_change_is_pending(struct XorrisO *xorriso, int flag);
+
+
+/* Compute the exit value from the recorded maximum event severity.
+   @param xorriso The context object to inquire.
+   @param flag    unused yet, submit 0
+   @return        The computed exit value
+*/
+int Xorriso_make_return_value(struct XorrisO *xorriso, int flag);
+
+
+/* Mandatory call:
+   Destroy xorriso object when it is no longer needed.
+   @param xorriso  The context object to destroy. *xorriso will become NULL.
+   @param flag     bit0= Perform global library shutdown.
+                         Use only with last xorriso object to be destroyed.
+   @return         <=0 error, >0 success
+*/
+int Xorriso_destroy(struct XorrisO **xorriso, int flag);
+
+
+/* --------------------- Command Interpreters ------------------- */
+
+
+/* This special interpreter is eventually called between Xorriso_new() and
+   Xorriso_startup_libraries(). It interprets certain commands which shall
+   get into effect before the libraries get initialized:
      -abort_on , -report_about , -return_with , -list_delimiter
    Some commands get executed only if they are the only command in argv:
      -prog_help , -help , -no_rc
@@ -176,19 +239,6 @@ int Xorriso_prescan_args(struct XorrisO *xorriso, int argc, char **argv,
                          int flag);
 
 
-/* Mandatory call:
-   It has to be made before calling any function listed below this point.
-
-   Make global library initializations.
-   This must be done with the first xorriso object that gets created and
-   with the first xorriso object that gets created after Xorriso_destroy(,1).
-   @param xorriso The context object.
-   @param flag    unused yet, submit 0
-   @return        <=0 error , >0 success
-*/ 
-int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag);
-
-
 /* Read and interpret commands from eventual startup files as listed in
    man xorriso.
    @param xorriso The context object in which to perform the commands.
@@ -270,33 +320,6 @@ int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag);
 int Xorriso_dialog(struct XorrisO *xorriso, int flag);
 
 
-/* Inquire whether option -commit would make sense.
-   @param xorriso The context object to inquire.
-   @param flag    unused yet, submit 0
-   @return        0= -commit would have nothing to do
-                  1= a new image session would emerge at -commit
-*/
-int Xorriso_change_is_pending(struct XorrisO *xorriso, int flag);
-
-
-/* Compute the exit value from the recorded maximum event severity.
-   @param xorriso The context object to inquire.
-   @param flag    unused yet, submit 0
-   @return        The computed exit value
-*/
-int Xorriso_make_return_value(struct XorrisO *xorriso, int flag);
-
-
-/* Mandatory call:
-   Destroy xorriso object when it is no longer needed.
-   @param xorriso  The context object to destroy. *xorriso will become NULL.
-   @param flag     bit0= Perform global library shutdown.
-                         Use only with last xorriso object to be destroyed.
-   @return         <=0 error, >0 success
-*/
-int Xorriso_destroy(struct XorrisO **xorriso, int flag);
-
-
 /* --------------------- Problem Status and Message API ------------------- */
 
 

xorriso/xorriso_main.c

@@ -96,7 +96,7 @@
 
 
 /* xorriso_main.c includes the internal copy of the API definition */
-/* The official xorriso options API is defined in <xorriso/xorriso.h> */
+/* The official xorriso options API is defined in <libisoburn/xorriso.h> */
 #include "xorriso.h"
 
 

xorriso/xorriso_timestamp.h

@@ -1 +1 @@
-#define Xorriso_timestamP "2010.06.13.105645"
+#define Xorriso_timestamP "2010.06.13.110316"