New commands -x, -list_arg_sorting

libisoburn/trunk/xorriso/xorriso.h

@@ -236,6 +236,8 @@ int Xorriso_destroy(struct XorrisO **xorriso, int flag);
    get into effect before the libraries get initialized:
      -abort_on , -report_about , -return_with , -list_delimiter ,
      -scsi_log , -signal_handling
+   This is the only occasion where command -x has an effect:
+     -x
    Some commands get executed only if they are the only command in argv:
      -prog_help , -help
    The following is recognized only if it is the first of all arguments:
@@ -301,6 +303,12 @@ int Xorriso_program_arg_bsl(struct XorrisO *xorriso, int argc, char ***argv,
     perform own error status evaluation. See below: Options API.) 
    After the first command and its parameters there may be more commands and
    parameters. All parameters must be given in the same call as their command.
+   @since 1.2.2:
+   Commands may get arranged in a sequence that is most likely to make sense.
+   E.g. image loading settings before drive aquiration, then commands fori
+   adding files, then settings for writing, then writing.
+   This feature may be enabled by command "-x" in Xorriso_prescan_args()
+   or by parameter flag of this call.
    @param xorriso The context object in which to perform the commands.
    @param argc    Number of arguments.
    @param argv    The arguments. argv[0] contains the program name.
@@ -308,10 +316,24 @@ int Xorriso_program_arg_bsl(struct XorrisO *xorriso, int argc, char ***argv,
    @param idx     Argument cursor. When this function is called, *idx must
                   be at least 1, argv[*idx] must be a command.
                   *idx will iterate over commands and parameters until this
-                  function aborts or until argc is reached.
+                  function aborts, or until argc is reached, or only once if
+                  flag bit2 is set.
    @param flag    bit0= reserved. Indicates recursion. Submit 0. 
                   bit1= Indicates that these are the main() program start
-                        arguments
+                        arguments. This enables their use with emulations
+                        which where set with Xorriso_new(), or argument
+                        arranging.
+                  bit2= Only execute the one command argv[*idx] and advance
+                        *idx to the next command if sucessful. Then return.
+                        This prevents any argument arranging.
+                        @since 1.2.2
+                  bit3= With bit1 and not bit2:
+                        Enable argument arranging as with
+                        Xorriso_prescan_args() and command "-x".
+                        @since 1.2.2
+                  bit4= With bit1:
+                        Surely disable argument arranging.
+                        @since 1.2.2
    @return <=0 = error
              1 = success
              2 = problem event ignored
@@ -918,11 +940,16 @@ int Xorriso_option_jigdo(struct XorrisO *xorriso, char *aspect, char *arg,
 /* Option -joliet "on"|"off" */
 int Xorriso_option_joliet(struct XorrisO *xorriso, char *mode, int flag);
 
+/* Option -list_arg_sorting */
+/* @since 1.2.2 */
+int Xorriso_option_list_arg_sorting(struct XorrisO *xorriso, int flag);
+
 /* Option -list_delimiter */
 int Xorriso_option_list_delimiter(struct XorrisO *xorriso, char *text,
                                   int flag);
 
 /* Option -list_extras */
+/* @since 1.1.6 */
 int Xorriso_option_list_extras(struct XorrisO *xorriso, char *mode, int flag);
 
 /* Option -list_formats */
@@ -933,6 +960,7 @@ int Xorriso_option_list_profiles(struct XorrisO *xorriso, char *which,
                                  int flag);
 
 /* Option -list_speeds */
+/* @since 1.1.2 */
 int Xorriso_option_list_speeds(struct XorrisO *xorriso, int flag);
 
 /* Option -load session|track|sbsector value */
@@ -1174,11 +1202,13 @@ int Xorriso_option_set_filter(struct XorrisO *xorriso, char *name,
 
 /* Option -signal_handling */
 /* @param flag bit0= do not yet install the eventual handler
+   @since 1.1.0
 */
 int Xorriso_option_signal_handling(struct XorrisO *xorriso, char *mode,
                                    int flag);
 
 /* Option -sleep */
+/* @since 1.1.8 */
 int Xorriso_option_sleep(struct XorrisO *xorriso, char *duration, int flag);
 
 /* Option -speed */
@@ -1248,6 +1278,11 @@ int Xorriso_option_volset_id(struct XorrisO *xorriso, char *name, int flag);
 int Xorriso_option_volume_date(struct XorrisO *xorriso,
                                char *time_type, char *timestring, int flag);
 
+/* There is no Xorriso_option_x() because -x has an effect only in
+   Xorriso_prescan_args(). Use the flag bits of Xorriso_interpreter() if
+   you want to impose command sorting on your own.
+*/
+
 /* Option -xattr "on"|"off" */
 int Xorriso_option_xattr(struct XorrisO *xorriso, char *mode, int flag);