Updated docs about existence of xorriso API in libisoburn

This commit is contained in:
Thomas Schmitt 2010-06-13 11:04:08 +00:00
parent 2f95cea15f
commit a9f63919f6
4 changed files with 93 additions and 46 deletions

View File

@ -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 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. 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, Currently they are fully supported on Linux with kernels >= 2.4,
on FreeBSD with ATAPI/CAM support enabled in the kernel, see atapicam(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 Compilation, First Glimpse, Installation
Dynamic library and compile time header requirements for libisoburn-0.5.6 : 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 - libisofs.so.6 , version libisofs-0.6.32 or higher
libisoburn and xorriso will not start with libraries which are older than their libisoburn and xorriso will not start with libraries which are older than their
headers seen at compile time. 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 --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 <libisoburn/xorriso.h>
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 Drives and Disk File Objects
The user of libisoburn applications needs rw-permission for the CD/DVD/BD The user of libisoburn applications needs rw-permission for the CD/DVD/BD
drives which shall be used, even if only reading is intended. drives which shall be used, even if only reading is intended.
A list of rw-accessible drives can be obtained by A list of rw-accessible drives can be obtained by
xorriso -devices xorriso -devices
resp. by xorriso API call
Xorriso_option_devices()
resp. by libburn API call resp. by libburn API call
burn_drive_scan() burn_drive_scan()

View File

@ -152,8 +152,71 @@ int Xorriso__preset_signal_behavior(int behavior, int flag);
int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag); int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag);
/* Interpret certain commands which shall get into effect before the /* Note: Between Xorriso_new() and the next call Xorriso_startup_libraries()
libraries get initialized: 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 -abort_on , -report_about , -return_with , -list_delimiter
Some commands get executed only if they are the only command in argv: Some commands get executed only if they are the only command in argv:
-prog_help , -help , -no_rc -prog_help , -help , -no_rc
@ -176,19 +239,6 @@ int Xorriso_prescan_args(struct XorrisO *xorriso, int argc, char **argv,
int flag); 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 /* Read and interpret commands from eventual startup files as listed in
man xorriso. man xorriso.
@param xorriso The context object in which to perform the commands. @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); 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 ------------------- */ /* --------------------- Problem Status and Message API ------------------- */

View File

@ -96,7 +96,7 @@
/* xorriso_main.c includes the internal copy of the API definition */ /* xorriso_main.c includes the internal copy of the API definition */
/* The official xorriso options API is defined in <xorriso/xorriso.h> */ /* The official xorriso options API is defined in <libisoburn/xorriso.h> */
#include "xorriso.h" #include "xorriso.h"

View File

@ -1 +1 @@
#define Xorriso_timestamP "2010.06.13.105645" #define Xorriso_timestamP "2010.06.13.110316"