libisoburn/xorriso/xorriso.h

/* xorriso - libisoburn higher level API which creates, loads, manipulates
             and burns ISO 9660 filesystem images.

   Copyright 2007-2020 Thomas Schmitt, <scdbackup@gmx.net>

   Provided under GPL version 2 or later.

   This file contains the public API of xorriso which covers all of its
   operations.

   An example of its usage is xorriso_main.c which checks version compatibility,
   creates a xorriso object, initializes the libraries, and runs the command
   interpreters of the API to constitute the command line oriented batch and
   dialog tool xorriso.

   Alternatively to command interpreters it is possible to run all options of
   xorriso directly via the calls of the "Command API". 
   The "Problem Status and Message API" shall then be used to obtain the
   text output of the options.

   Mandatory calls are:
     Xorriso_new(), Xorriso_startup_libraries(), Xorriso_destroy()

   This architecture is fully public since version 0.5.8. From then on, new
   features get marked by
     @since major.minor.micro
   The option calls may have older "since" marks which then tell when the
   corresponding command was introduced in the command interpreter.

   Please note that struct XorrisO and its API calls are _not_ thread-safe in
   general. It is not permissible to run two API calls on the same
   XorrisO object concurrently.
   The only exception is
     Xorriso_fetch_outlists()
   in order to learn about the ongoing text output of other API calls.


   There is a lower level of API which consists of libisofs.h, libburn.h and
   libisoburn.h. One should not mix those calls with the ones of xorriso.h .
*/

/* Important: If you add a public API function then add its name to file
                  libisoburn/libisoburn.ver
*/


#ifndef Xorriso_includeD
#define Xorriso_includeD yes

#ifdef __cplusplus
extern "C" {
#endif


/** Opaque handle of the xorriso runtime context */
struct XorrisO; 



/* This may be changed to Xorriso_GNU_xorrisO in order to create GNU xorriso
   under GPLv3+ derived from above GPLv2+.
*/
#define Xorriso_libburnia_xorrisO yes


/* --------------------- Fundamental Management ------------------- */


/** These three release version numbers tell the revision of this header file
    and of the API which it describes. They shall be memorized by applications
    at build time.
    @since 0.5.8
*/
#define Xorriso_header_version_majoR  1
#define Xorriso_header_version_minoR  5
#define Xorriso_header_version_micrO  3


/** If needed: Something like ".pl01" to indicate a bug fix. Normally empty.
    @since 0.5.8
*/
#define Xorriso_program_patch_leveL ""


/** Obtain the three release version numbers of the library. These are the
    numbers encountered by the application when linking with libisoburn,
    i.e. possibly not before run time.
    Better do not base the fundamental compatibility decision of an application
    on these numbers. For a reliable check use Xorriso__is_compatible().
    @since 0.5.8
    @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.
                 Features of a pare release will stay available and ABI
                 compatible as long as the SONAME of libisoburn stays "1".
                 Currently there are no plans to ever change the SONAME.
                  
                 Odd numbers indicate that API upgrades are in progress.
                 I.e. new features might be already present or they might
                 be still missing. Newly introduced features may be changed
                 incompatibly or even be revoked before release of a pare
                 version.
                 So micro revisions {1,3,5,7,9} should never be used for
                 dynamic linking unless the proper library match can be
                 guaranteed by external circumstances.

    @return 1 success, <=0 might in future become an error indication
*/
void Xorriso__version(int *major, int *minor, int *micro);


/** Check whether all features of header file xorriso.h from the given
    major.minor.micro revision triple can be delivered by the library version
    which is performing this call.
        if (! Xorriso__is_compatible(Xorriso_header_version_majoR,
                                     Xorriso_header_version_minoR,
                                     Xorriso_header_version_micrO, 0))
           ...refuse to start the program with this dynamic library version...
    @since 0.5.8
    @param major obtained at build time
    @param minor obtained at build time
    @param micro obtained at build time
    @param flag Bitfield for control purposes. Unused yet. Submit 0.
    @return 1= library can work for caller
            0= library is not usable in some aspects. Caller must restrict
               itself to an earlier API version or must not use this library
               at all.
*/
int Xorriso__is_compatible(int major, int minor, int micro, int flag);


/* Get the patch level text (e.g. "" or ".pl01") of the program code.
   @param flag     unused yet, submit 0
   @return         readonly character string
*/
char *Xorriso__get_patch_level_text(int flag);


/* Choose how Xorriso_startup_libraries() and the XorrisO object shall
   prepare for eventual signals.
   @param behavior Default is behavior 1.
                   0= no own signal handling. The main application has to do
                      that. Do not start burn runs without any handling !
                   1= use libburn signal handler. Most time with action
                      0. During writing, formatting, blanking: 0x30.
                      Only usable with a single xorriso object.
                   2= Enable system default reaction on all signals
                      @since 1.0.9
                   3= Try to ignore nearly all signals
                      @since 1.0.9
   @param flag     unused yet, submit 0
   @return         <= 0 is error, >0 is success
*/
int Xorriso__preset_signal_behavior(int behavior, int flag);


/* Mandatory call:
   Create a new xorriso object and tell it the program name to be used
   with messages and for decision of special behavior.
   @param xorriso  returns the newly created XorrisO object 
   @param progname typically argv[0] of main(). Some leafnames of the progname
                   path have special meaning and trigger special behavior:
                    "osirrox"    allows image-to-disk copying: -osirrox "on" 
                    "xorrisofs"  activates -as "mkisofs" emulation from start
                    "genisofs"   alias of "xorrisofs"
                    "mkisofs"    alias of "xorrisofs"
                    "genisoimage"  alias of "xorrisofs"
                    "xorrecord"  activates -as "cdrecord" emulation from start
                    "cdrecord"   alias of "xorrecord"
                    "wodim"      alias of "xorrecord"
                    "cdrskin"    alias of "xorrecord"
   @param flag     unused yet, submit 0
   @return         >0 success , <=0 failure, no object created
*/
int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag);


/* Note: Between Xorriso_new() and the next call Xorriso_startup_libraries()
         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 Command 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 Command API.

         Wenn all desired activities are done, you may check whether there are
         uncommitted changes 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    @since 0.6.6
                  bit0= do not return 1 if -as mkisofs -print-size was
                        performed on the current image.
   @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 may be 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 ,
     -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:
     -no_rc
   Some get examined for the need to redirect stdout messages:
     -dev , -outdev , -indev , -as 
   Commands
     -backslash_codes , -list_delimiter , -add_plainly
   get into effect during this call. But their setting at begin of the call
   gets restored before the call returns.
   @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.
                  argv[1] to argv[argc-1] contain commands and parameters.
   @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.
   @param flag    bit0= do not interpret argv[1]
                  bit1= produce FAILURE events on unknown commands
                        @since 1.1.0
   @return        <0 error
                   0 end program
                   1 ok, go on 
*/
int Xorriso_prescan_args(struct XorrisO *xorriso, int argc, char **argv,
                         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.
   @param flag    unused yet, submit 0
   @return <=0 = error
             1 = success
             3 = end program run (e.g. because command -end was encountered)
*/
int Xorriso_read_rc(struct XorrisO *xorriso, int flag);


/* Check whether program arguments shall be backslash decoded. If so, then
   replace *argv by a new argument vector. The old one will not be freed
   by this call. If it is dynamic memory then you need to keep a copy of
   the pointer and free it yourself after this call.

   @since 1.3.2:
   This call internally interprets the commands -backslash_codes and
   -list_delimiter if it encounters them among the arguments. The
   decoding of backslashes can thus be enabled and disabled by the
   arguments themselves. The state of the xorriso object in respect
   to these commands gets preserved at the start of the call and restored
   when the call ends.
   (*argv)[0] never gets decoded.
   The old *argv will always be replaced by a new one.

   @param xorriso The context object
   @param argc    Number of arguments.
   @param argv    The arguments. (*argv)[0] contains the program name.
                  (*argv)[1] to (*argv)[argc-1] contain commands and parameters
                  If argv after the call differs from argv before the call,
                  then one should dispose it later by:
                    Xorriso__dispose_words(argc, argv);
   @param flag    unused yet, submit 0
   @return        <= 0 error , > 0 success
*/
int Xorriso_program_arg_bsl(struct XorrisO *xorriso, int argc, char ***argv,
                            int flag);


/* Interpret argv as xorriso command options and their parameters.
   (An alternative is to call functions of the options API directly and to
    perform own error status evaluation. See below: Command 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 for
   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.
                  argv[1] to argv[argc-1] contain commands and parameters.
   @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, 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. 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 successful. 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
             3 = end program run (e.g. because command -end was encountered)
*/
int Xorriso_interpreter(struct XorrisO *xorriso,
                        int argc, char **argv, int *idx, int flag);


/* Parse a command line into words and use them as argv for a call of
   Xorriso_interpreter(). Put out some info lines about the outcome.
   @param xorriso The context object in which to perform the commands.
   @param line    A text of one or more words according to man xorriso
                  paragraph "Command processing" up to and including
                  "Backslash Interpretation".
   @param flag    bit0 to bit15 are forwarded to Xorriso_interpreter()
                  bit16= no pageing of info lines
                  bit17= print === bar even if xorriso->found<0
   @return        see return of Xorriso_interpreter()
*/
int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag);


/* Parse a text line into words. This parsing obeys the same rules as
   command line parsing but allows to skip a prefix, to use a user provided
   set of separator characters, and to restrict the number of parsed words.

   If parameter xorriso is NULL, then this call is safe for usage by
   a concurrent thread while a xorriso API call is being executed.

   @since 1.2.6
   @param xorriso     The context object which provides settings for parsing
                      and output channels for error messages.
                      May be NULL in order to allow concurrent execution e.g.
                      by a callback function of Xorriso_start_msg_watcher().
                      If xorriso is NULL then:
                        flag bit1-bit4 are in effect even if bit0 is not set.
                        flag bit5 and bit6 may not be set.
   @param line        A text of one or more words according to man xorriso
                      paragraph "Command processing" up to and including
                      "Backslash Interpretation".
   @param prefix      If not empty then the line will only be parsed if it
                      begins by the prefix text. Parsing will then begin after
                      the end of the prefix.
                      If the prefix does not match, then 0 will be returned
                      in *argc, argv will be NULL, and the return value will
                      be 2.
   @param separators  If not empty this overrides the default list of word
                      separating characters. Default set is the one of
                      isspace(3).
   @param max_words   If not 0: Maximum number of words to parse. If there
                      remains line text after the last parsed word and its
                      following separators, then this remainder is copied
                      unparsed into a final result word. In this case *argc
                      will be larger than max_words by one. Note that trailing
                      separators are considered to be followed by an empty
                      word.
   @param argc        Will return the number of allocated and filled word
                      strings.
   @param argv        Will return the array of word strings.
                      Do not forget to dispose the allocated memory by a
                      call to Xorriso__dispose_words().
   @param flag        Bitfield for control purposes
                      bit0=   Override setting of -backslash_codes.
                      bit1-4= With bit0: backslash behavior
                              0= off
                              1= in_double_quotes
                              2= in_quotes
                              3= with_quoted_input
                      bit5=   Prepend the program name as (*argv)[0], so that
                              *argv is suitable for Xorriso_interpreter()
                              and other calls which expect this.
                              Not allowed if xorriso is NULL.
                      bit6=   Issue failure message in case of return 0
                              Not allowed if xorriso is NULL.
   @return            <=0 means error and invalidity of *argv:
                              0 = Input format error. E.g. bad quotation mark.
                             -1 = Lack of resources. E.g. memory.
                             -2 = Improper combination of call parameters.
                      >0 means success but not necessarily a valid result:
                              1 = Result in argc and argv is valid (but may
                                  be empty by argc == 0, argv == NULL).
                              2 = Line did not match prefix. Result is invalid
                                  and empty.
*/
int Xorriso_parse_line(struct XorrisO *xorriso, char *line,
                       char *prefix, char *separators, int max_words,
                       int *argc, char ***argv, int flag);


/* Dispose a list of strings as allocated by Xorriso_parse_line() or
   Xorriso_program_arg_bsl(), or Xorriso_sieve_get_result().
   @since 1.2.6
   @param argc        A pointer to the number of allocated and filled word
                      strings. *argc will be set to 0 by this call.
   @param argv        A pointer to the array of word strings.
                      *argv will be set to NULL by this call.
*/
void Xorriso__dispose_words(int *argc, char ***argv);


/* Enter xorriso command line dialog mode, using libreadline if configured
   at build time and not disabled at run time.
   This call returns immediately if not option -dialog "on" was performed
   before.
   @param xorriso The context object in which to perform the commands.
   @param flag    unused yet, submit 0
   @return        <=0 error, 1= dialog mode ended normally ,
                  3= dialog mode ended normally,interpreter asks to end program
*/
/* @since 0.1.0 */
int Xorriso_dialog(struct XorrisO *xorriso, int flag);


/* --------------------- Problem Status and Message API ------------------- */


/** Submit a problem message to the xorriso problem reporting and handling
    system. This will eventually increase problem status rank, which may
    at certain stages in the program be pardoned and reset to 0.
    The pardon is governed by Xorriso_option_abort_on() and by the anger
    of the affected program part. If no pardon has been given, then the problem
    status reaches the caller of option functions.
    Problem status should be inquired by Xorriso_eval_problem_status() and be
    reset before next option execution by Xorriso_set_problem_status().
    The problem status itself does not cause the failure of option functions.
    But in case of failures for other reasons, a remnant overly severe problem
    status can cause overly harsh program reactions.
    @param xorriso    The environment handle
    @param error_code The unique error code of your message.
                      Submit 0 if you do not have reserved error codes within
                      the libburnia project.
    @param msg_text   Not more than 8196 characters of message text.
                      A final newline character gets appended automatically.
    @param os_errno   Eventual errno related to the message. Submit 0 if
                      the message is not related to a operating system error.
    @param severity   One of "ABORT", "FATAL", "FAILURE", "MISHAP", "SORRY",
                      "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG".
                      Defaults to "FATAL".
    @param flag       Bitfield for control purposes
                        bit0= use pager (as with result)
                        bit1= permission to suppress output
    @return           1 if message was delivered, <=0 if failure
*/
int Xorriso_msgs_submit(struct XorrisO *xorriso,
                        int error_code, char msg_text[], int os_errno,
                        char severity[], int flag);

/** Alternative call interface of Xorriso_msgs_submit with void* instead
    of struct XorrisO*
*/
int Xorriso_msgs_submit_void(void *xorriso,
                        int error_code, char msg_text[], int os_errno,
                        char severity[], int flag);


/** Evaluate an advise whether to abort or whether to go on with option
    processing. This should be called after any option function was processed.
    It updates the problem status by processing the library message queues
    and then it uses this status and the submitted return value of the
    option function to evaluate the situation.
    @param xorriso    The environment handle
    @param ret        The return value of the previously called option function
    @param flag       bit0= do not issue own event messages
                      bit1= take xorriso->request_to_abort as reason for abort
    @return           Gives the advice:
                        2= pardon was given, go on
                        1= no problem, go on
                        0= function failed but xorriso would not abort, go on
                       <0= do abort
                           -1 = due to xorriso->problem_status
                                or due to ret<0
                           -2 = due to xorriso->request_to_abort
*/
int Xorriso_eval_problem_status(struct XorrisO *xorriso, int ret, int flag);


/** Set the current problem status of the xorriso handle.
    @param xorriso    The environment handle
    @param severity   A severity text. Empty text resets to "No Problem". 
    @param flag       Unused yet. Submit 0.
    @return           <=0 failure (e.g. wrong severity text), 1 success.
*/
int Xorriso_set_problem_status(struct XorrisO *xorriso, char *severity,
                               int flag);


/* The next three functions are part of Xorriso_eval_problem_status().
   You may use them to build an own advisor function.
*/

/** Compare two severity texts for their severeness.
    Unknown severity texts get defaulted to "FATAL".
    @since 1.2.6
    @param sev1  First severity text to compare
    @param sev2  Second severity text to compare
    @return      -1 sev1 is less severe than sev2
                  0 sev1 is equally severe to sev2
                  1 sev1 is more severe than sev2
*/
int Xorriso__severity_cmp(char *sev1, char *sev2);


/** Return a blank separated list of severity names. Sorted from low
    to high severity.
    @since 1.2.6
    @param flag Bitfield for control purposes (unused yet, submit 0)
    @return  A constant string with the severity names
*/
char *Xorriso__severity_list(int flag);



/** Obtain the current problem status of the xorriso handle.
    @param xorriso    The environment handle
    @param severity   The severity text matching the current problem status
    @param flag       Unused yet. Submit 0.
    @return           The severity rank number. 0= no problem occurred.
*/
int Xorriso_get_problem_status(struct XorrisO *xorriso, char severity[80],
                               int flag);


/** Forward any pending messages from the library message queues to the
    xorriso message system which puts out on info channel. This registers
    the severity of the library events like the severity of a message submitted
    via Xorriso_msgs_submit().
    xorriso sets the message queues of the libraries to queuing "ALL".
    Many inner functions of xorriso call Xorriso_process_msg_queues() on their
    own because they expect library output pending. Nevertheless, a loop of
    xorriso option calls should either call Xorriso_eval_problem_status() or
    Xorriso_process_msg_queues() with each cycle.
    @param xorriso    The environment handle
    @param flag       Unused yet. Submit 0.
    @return           1 on success, <=0 if failure
*/
int Xorriso_process_msg_queues(struct XorrisO *xorriso, int flag);


/** Write a message for option -errfile_log. 
    @param xorriso    The environment handle
    @param error_code The unique error code of your message.
                      Submit 0 if you do not have reserved error codes within
                      the libburnia project.
    @param msg_text   Not more than 8196 characters of message text.
    @param os_errno   Eventual errno related to the message. Submit 0 if
                      the message is not related to a operating system error.
    @param flag       bit0-7= meaning of msg_text
                      ( 0= ERRFILE path , for internal use mainly )
                        1= mark line text (only to be put out if enabled)
    @return <=0 error , >0 success
*/
int Xorriso_process_errfile(struct XorrisO *xorriso,
                            int error_code, char msg_text[], int os_errno,
                            int flag);


/*
                           Message output evaluation

   xorriso is basically a dialog software which reacts on commands by
   side effects and by messages. The side effects manipulate the state of
   the ISO image model and of drives. This state can be inquired by commands
   which emit messages.

   There are several approaches how a program that uses xorriso via this API
   can receive and use the message output of xorriso.

   - The message sieve may be programmed to pick certain information snippets
     out of the visible message stream. This covers all messages on the
     result channel and those info channel messages which get not suppressed
     by command -report_about. All important info messages have severity NOTE
     or higher.
     Much of the message interpretation is supposed to happen by the sieve
     filter rules which describe the interesting message lines and the
     positions of the interesting message parts.
     The call Xorriso_sieve_big() installs a sieve that looks out for most
     model state messages which xorriso can emit. After a few commands
     the user will ask the sieve for certain text pieces that might have been
     caught.

   - The outlist stack may be used to catch messages in linked lists rather
     than putting them out on the message channels.
     All interpretation of the messages has to be done by the user of the
     xorriso API. Function Xorriso_parse_line() is intended to help with
     splitting up messages into words.
     The outlist stack is handy for catching the results of information
     commands with large uniform output or no well recognizable message
     prefix. Like -lsl, -getfacl, -status, -find ... -exec get_md5.
     One should push the stack before the command, pull it afterwards, examine
     the text list by Xorriso_lst_get_*(), and finally dispose the list.

   - The message watcher is a separate program thread which uses the outlist
     stack to catch the messages and to call user provided handler functions.
     These functions can use Xorriso_parse_line() too, if they submit the
     xorriso parameter as NULL. They may not use the struct XorrisO object
     in any way.
     Synchronization between watcher and emitters of commands can be achieved
     by Xorriso_peek_outlists().
     The main motivation for the message watcher is to inspect and display
     messages of long lasting xorriso commands while they are still executing.
     E.g. of -commit, -blank, -format.
     One would normally start it before such a command and stop it afterwards.
     But of course, the watcher can stay activated all the time and process
     all message output via its handler calls.

   The message sieve does not interfere with outlists and message watcher.
   The message watcher will only see messages which are not caught by outlists
   which were enabled after the watcher thread was started.
     
*/

/* The programmable message sieve picks words out of the program messages
   of xorriso.
   The sieve is a collection of filter rules. Each one is defined by a call of
   Xorriso_sieve_add_filter(). The sieve watches the given output channels for
   messages which begin by the given text prefixes of the filters.
   Matching lines get split into words by Xorriso_parse_line() using
   the given separators. The words described by the filter's word index array
   get recorded by the filter and can be inquired by Xorriso_sieve_get_result()
   after one or more xorriso commands have been performed.
   The recorded results may be disposed by Xorriso_sieve_clear_results without
   giving up the sieve.
   The whole sieve may be disposed by Xorriso_sieve_dispose().
   Default at library start is an inactive sieve without any filter rules.
*/

/** Add a filter rule to the message sieve.
    Start watching output messages, if this is not already enabled.
    @since 1.2.6
    @param xorriso    The environment handle
    @param name       The filter name by which its recorded results shall
                      be inquired via Xorriso_sieve_get_result()
    @param channels   Which of the output channels the filter shall watch
                      bit0= result channel
                      bit1= info channel
                      bit2= mark channel
    @param prefix     The line start to watch for. Will also be handed over
                      to Xorriso_parse_line(). Empty text matches all lines. 
                      If the prefix begins by '?' characters, then these
                      match any character at the beginning of a message.
                      The prefix of the filter rule will then be adapted
                      to really match the line, before it gets handed over
                      to Xorriso_parse_line().
    @param separators List of separator characters for Xorriso_parse_line()
    @param num_words  Number of word indice in word_idx
    @param word_idx   Array with the argv indice to be picked from the
                      the result of Xorriso_parse_line(). Must at least
                      contain num_words elements.
    @param max_results If not 0, then the maximum number of line results that
                      shall be recorded by the filter. When this number is
                      exceeded, then results of older lines get discarded
                      when new results get recorded.
    @param flag       Bitfield for control purposes
                      bit0= Last result word shall contain the remainder of
                            the message line
    @return           <=0 error , >0 success
*/
int Xorriso_sieve_add_filter(struct XorrisO *xorriso, char *name,
                             int channels, char *prefix, char *separators,
                             int num_words, int *word_idx, int max_results,
                             int flag);


/** Inquire recorded results from a particular filter rule.
    @param xorriso    The environment handle
    @param name       The filter name as given by Xorriso_sieve_add_filter()
    @param argc       Will return the number of allocated and filled word
                      strings.
    @param argv       Will return the array of word strings.
                      Do not forget to dispose the allocated memory by a
                      call to Xorriso__dispose_words().
    @param available  Will return the number of results which are still
                      available for further calls of Xorriso_sieve_get_result()
                      with the given name.
    @param flag       Bitfield for control purposes:
                      bit0= Reset reading to first matching result.
                      bit1= Only inquire number of available results.
                            Do not allocate memory.
                      bit2= If *argv is not NULL, then free it before attaching
                            new memory.
                      bit3= Do not read recorded data but rather list all
                            filter names.
    @return           <0 error: -1 = memory shortage
                                -2 = no filter rule found
                       0 No more data available for the given name
                         With bit3: No filter rules installed.
                      >0 argc and argv are valid
*/
int Xorriso_sieve_get_result(struct XorrisO *xorriso, char *name,
                             int *argc, char ***argv, int *available,
                             int flag);


/** Dispose all recorded results. Keep filter rules. Continue watching
    and recording.
    @since 1.2.6
    @param xorriso    The environment handle
    @param flag       Unused yet. Submit 0.
    @return           <=0 error , >0 success
*/
int Xorriso_sieve_clear_results(struct XorrisO *xorriso, int flag);


/** Dispose all filter rules. End watching and recording.
    This is the default state at library startup.
    @since 1.2.6
    @param xorriso    The environment handle
    @param flag       Unused yet. Submit 0.
    @return           <=0 error , >0 success
*/
int Xorriso_sieve_dispose(struct XorrisO *xorriso, int flag);


/** Install a large sieve with filters for about any interesting message
    of xorriso. The filter rule names are mostly the same as the prefixes they
    search for. If you do not find the message prefix of your desire, then
    you may add a filter rule by Xorriso_sieve_add_filter().
    If you do not want all these filter any more, call Xorriso_sieve_dispose().

    You should obtain your recorded data often and then call
    Xorriso_sieve_clear_results(). It is nevertheless ok to perform several
    different xorriso information commands and to then obtain results from the
    sieve.

    The installed filters in particular:
    Name             Recorded values, returned by Xorriso_sieve_get_result()
    ------------------------------------------------------------------------
    "-changes_pending" up to 1 result from -changes_pending show_status
                     argv[0]= "yes" or "no"
    "?  -dev"        up to 10 results from -devices or -device_links
                     (records drives with single digit index number)
                     argv[0]= drive address
                     argv[1]= permissions
                     argv[2]= drive vendor
                     argv[3]= product id
    "??  -dev"       up to 90 results from -devices or -device_links
                     (records drives with double digit index number)
                     argv[0]= drive address
                     argv[1]= permissions
                     argv[2]= drive vendor
                     argv[3]= product id
    "Abstract File:" up to 1 result from -pvd_info
                     argv[0]= file name
                     (Note: prefix is "Abstract File: ")
    "After commit :" up to 1 result from -tell_media_space
                     argv[0]= number of blocks with "s" appended
    "App Id       :" up to 1 result from -pvd_info
                     argv[0]= id
                     (Note: prefix is "App Id       : ")
    "Biblio File  :" up to 1 result from -pvd_info
                     argv[0]= file name
                     (Note: prefix is "Biblio File  : ")
    "Build timestamp   :" up to 1 result from -version
                     argv[0]= timestamp
                     (Note: prefix is "Build timestamp   :  ")
    "CopyrightFile:" up to 1 result from -pvd_info
                     argv[0]= file name
                     (Note: prefix is "CopyrightFile: ")
    "Creation Time:" up to 1 result from -pvd_info
                     argv[0]= YYYYMMDDhhmmsscc
                     (Note: prefix is "Creation Time: ")
    "DVD obs 64 kB:" up to 1 result from -list_extras
                     argv[0]= "yes" or "no"
    "Drive access: " up to 2 result from -dev, -indev, -toc
                     argv[0]= "exclusive", "shared"
                     argv[1]= "readonly","restricted"
    "Drive current:" up to 2 results from -dev, -indev, -toc, others
                     argv[0]= command ("-dev", "-outdev", "-indev")
                     argv[1]= drive address
    "Drive type   :" up to 2 results from -toc
                     argv[0]= vendor
                     argv[1]= product
                     argv[2]= revision
    "Eff. Time    :" up to 1 result from -pvd_info
                     argv[0]= YYYYMMDDhhmmsscc
                     (Note: prefix is "EffectiveTime: ")
    "Expir. Time  :" up to 1 result from -pvd_info
                     argv[0]= YYYYMMDDhhmmsscc
                     (Note: prefix is "Expir. Time  : ")
    "Ext. filters :" up to 1 result from -list_extras
                     argv[0]= "yes" or "no" , possibly more info
                     (Note: prefix is "Ext. filters : ")
    "File damaged :" up to 10000 results from -find ... -exec report_damage
                     argv[0]= damage start byte in file
                     argv[1]= damage range size in file
                     argv[2]= file size
                     argv[3]= path in ISO image