From 97e4d355958293ea55bea90aea21469a3b1b2d67 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sun, 13 Jun 2010 11:04:08 +0000 Subject: [PATCH] Updated docs about existence of xorriso API in libisoburn --- README | 28 +++++++++- xorriso/xorriso.h | 107 ++++++++++++++++++++++-------------- xorriso/xorriso_main.c | 2 +- xorriso/xorriso_timestamp.h | 2 +- 4 files changed, 93 insertions(+), 46 deletions(-) diff --git a/README b/README index 7257df34..3c184fcf 100644 --- a/README +++ b/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 + +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() diff --git a/xorriso/xorriso.h b/xorriso/xorriso.h index 8d16f76b..b835a45c 100644 --- a/xorriso/xorriso.h +++ b/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 - libraries get initialized: +/* 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 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 ------------------- */ diff --git a/xorriso/xorriso_main.c b/xorriso/xorriso_main.c index 9b1e6e83..b557365b 100644 --- a/xorriso/xorriso_main.c +++ b/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 */ +/* The official xorriso options API is defined in */ #include "xorriso.h" diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index 9baebba7..07782371 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2010.06.13.105645" +#define Xorriso_timestamP "2010.06.13.110316"