Worked on failure severities, message system, program abort decision

test/xorriso.h

@@ -16,8 +16,107 @@
 struct XorrisO; 
 
 
+/* --------------------- 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", "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);
+
+
+/** 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 ot the
+    option function to evaluate the situation.
+    @param xorriso    The environment handle
+    @param ret        The return value of the prviously called option function
+    @param flag       Unused yet. Submit 0.
+    @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
+*/
+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 two functions are part of Xorriso_eval_problem_status().
+   You may use them to build an own advisor function or to drain the
+   library message queues more frequently.
+*/
+
+/** 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 occured.
+*/
+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".
+    So it is essential that they get  
+    @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);
+
+
+
 /* ---------------------------- Options API ------------------------ */
 /*    See man 1 xorriso for explanation of the particular options    */
+/*
+   Before each call to an option function, there should happen:
+   Xorriso_set_problem_status() with empty severity text.
+
+   After each call to an option function, there should happen:
+   Xorriso_eval_problem_status()
+   One should follow its eventual advice to abort.
+*/
+
 
 /* Option -abort_on */
 int Xorriso_option_abort_on(struct XorrisO *xorriso, char *severity, int flag);