diff --git a/xorriso/xorriso.h b/xorriso/xorriso.h index 52dcb266..839ba5da 100644 --- a/xorriso/xorriso.h +++ b/xorriso/xorriso.h @@ -18,7 +18,16 @@ struct XorrisO; /* --------------------- Fundamental Management ------------------- */ -/* Create a new xorriso object and tell it the program name to be used + +/* Get the version text (e.g. "0.3.9") of the program code. + @param flag unused yet, submit 0 + @return readonly character string +*/ +char *Xorriso__get_version_text(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 @@ -28,20 +37,19 @@ struct XorrisO; "genisofs" alias of "xorrisofs" "mkisofs" alias of "xorrisofs" "genisoimage" alias of "xorrisofs" - @parm flag unused yet, submit 0 + @param flag unused yet, submit 0 @return >0 success , <=0 failure, no object created */ int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag); -/* 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). -*/ -int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag); - - -/* Interpret argv as xorriso command options and their parameters. +/* Interpret 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 + Some get examined for the need to redirect stdout messages + -dev , -outdev , -indev , -as @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. @@ -50,9 +58,69 @@ int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag); be at least 1, argv[*idx] must be to a command. *idx will iterate over commands and parameters until this function aborts or until argc is reached. - @param flag ( Do Not Set: bit0= recursion ) - ( Do Not Set: bit1= these are command line arguments - (for xorriso->argument_emulation) ) + @param flag bit0= do not interpret argv[1] + @return <0 error + 0 end program + 1 ok, go on +*/ +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. + @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 and eventually + 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. + @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 + @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: 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. + @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= recursion + bit1= these are the main() program start arguments @return <=0 = error 1 = success 2 = problem event ignored @@ -76,6 +144,17 @@ int Xorriso_interpreter(struct XorrisO *xorriso, int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag); +/* Enter xorriso command line dialog mode, eventually using libreadline. + 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 +*/ +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 @@ -85,10 +164,20 @@ int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag); int Xorriso_change_is_pending(struct XorrisO *xorriso, int flag); -/* Destroy xorriso object when it is no longer needed. - @param flag bit0= Make global librariy shutdown. - Use only with last xorriso object to be destroyed. - +/* 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); @@ -193,6 +282,23 @@ int Xorriso_get_problem_status(struct XorrisO *xorriso, char severity[80], 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); + /* The outlist stack allows to redirect the info and result messages from their normal channels into a pair of string lists which can at some @@ -301,6 +407,16 @@ int Xorriso_lst_destroy_all(struct Xorriso_lsT **lstring, int flag); After each call to an option function, there should happen: Xorriso_eval_problem_status() One should follow its eventual advice to abort. + + Options with a varying number of arguments get them passed like + Xorriso_interpreter(). E.g.: + int Xorriso_option_add(struct XorrisO *xorriso, int argc, char **argv, + int *idx, int flag); + They begin to read the arguments at position *idx and will see the list + end either at the next argv which contains the -list_delimiter text or + at argv[argc-1]. After the call, *idx will be the index of the first not + yet interpreted argv. + */ diff --git a/xorriso/xorriso_private.h b/xorriso/xorriso_private.h index 88b311af..fbc557df 100644 --- a/xorriso/xorriso_private.h +++ b/xorriso/xorriso_private.h @@ -431,22 +431,6 @@ struct XorrisO { /* the global context of xorriso */ }; -int Xorriso_prescan_args(struct XorrisO *xorriso, int argc, char **argv, - int flag); - -int Xorriso_read_rc(struct XorrisO *xorriso, int flag); - -int Xorriso_dialog(struct XorrisO *xorriso, int flag); - -/* @param flag bit0-7= purpose - 0= ERRFILE - 1= mark line (only to be put out if enabled) -*/ -int Xorriso_process_errfile(struct XorrisO *xorriso, - int error_code, char msg_text[], int os_errno, - int flag); - -int Xorriso_make_return_value(struct XorrisO *xorriso, int flag); int Xorriso_prepare_regex(struct XorrisO *xorriso, char *adr, int flag); diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index 45707565..066e012c 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2009.06.23.070934" +#define Xorriso_timestamP "2009.06.23.123147"