libburnia/legacy
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

New API calls Xorriso_sieve_add_filter, Xorriso_sieve_get_result, Xorriso_sieve_clear_results, Xorriso_sieve_dispose, Xorriso_sieve_big

Browse Source
This commit is contained in:
Thomas Schmitt
2012-12-06 13:22:13 +00:00
parent 5f3dcc3904
commit 0bd83b3a73
9 changed files with 933 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
libisoburn/trunk/xorriso/xorriso.h
View File

@ -429,7 +429,7 @@ int Xorriso_parse_line(struct XorrisO *xorriso, char *line,
/* Dispose a list of strings as allocated by Xorriso_parse_line() or
Xorriso_program_arg_bsl().
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.
@ -583,6 +583,303 @@ int Xorriso_process_errfile(struct XorrisO *xorriso,
int flag);
/* -------------------- Message output evaluation API -------------------- */
/* 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 API approaches how a program 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 result channel of information
commands with large uniform output like -lsl, -getfacl, -status.
- 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.
The main motivation for the message watcher is to inspect and display
messages of long lasting xorriso commands like -commit, -blank, -format.
The 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.
@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.
*/
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"
(Note: prefix is "-changes_pending ")
"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: ")
"DVD obs 64 kB:" up to 1 result from -list_extras
argv[0]= "yes" or "no"
"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
"Ext. filters :" up to 1 result from -list_extras
argv[0]= "yes" or "no" , possibly more info
(Note: prefix is "Ext. filters : ")
"Format idx :" up to 100 results from -list_formats
argv[0]= index
argv[1]= MMC code
argv[2]= number of blocks with "s" appended
argv[3]= roughly the size in MiB
(Note: prefix is "Format idx ")
"Format status:" up to 1 result from -list_formats
argv[0]= status
argv[1]= capacity
"Image size :" up to 1 result from -print_size
argv[0]= number of blocks with "s" appended
"ISO session :" up to 10000 results from -toc
argv[0]= Idx
argv[1]= sbsector
argv[2]= Size
argv[3]= Volume Id
"Jigdo files :" up to 1 result from -list_extras
argv[0]= "yes" or "no"
"Local ACL :" up to 1 result from -list_extras
argv[0]= "yes" or "no"
"Local xattr :" up to 1 result from -list_extras
argv[0]= "yes" or "no"
"MD5 tag range:" up to 10000 results from -check_media
argv[0]= lba
argv[1]= size in blocks
argv[2]= result text (starting with "+", "-", or "0")
"Media blocks :" up to 2 results from -toc
argv[0]= readable
argv[1]= writable
argv[2]= overall
"Media current:" up to 2 results from -dev, -indev, -toc, others
argv[0]= media type / MMC profile name
(Note: prefix is "Media current: " which eats extra blank)
"Media nwa :" up to 1 result from -toc
argv[0]= next writable address
"Media region :" up to 10000 results from -check_media
argv[0]= lba
argv[1]= size in blocks
argv[2]= quality text (starting with "+", "-", or "0")
"Media space :" up to 1 result from -tell_media_space
argv[0]= number of blocks with "s" appended
"Media status :" up to 2 results from -dev, -indev, -toc, others
argv[0]= status description
(Note: prefix is "Media status : ")
"Media summary:" up to 2 results from -dev, -indev, -toc, others
argv[0]= sessions
argv[1]= data blocks (full count)
argv[2]= data (with unit letter k,m,g)
argv[3]= free (with unit letter k,m,g)
"PVD address :" up to 1 result from -pvd_info
argv[0]= block address with "s" appended
"Preparer Id :" up to 1 result from -pvd_info
argv[0]= id
(Note: prefix is "Preparer Id : ")
"Profile :" up to 256 results from -list_profiles
argv[0]= MMC code
argv[1]= profile name in round brackets
possibly appended: " (current)"
"Publisher Id :" up to 1 result from -pvd_info
argv[0]= id
(Note: prefix is "Publisher Id : ")
"Readline :" up to 1 result from -list_extras
argv[0]= "yes" or "no"
"System Id :" up to 1 result from -pvd_info
argv[0]= id
(Note: prefix is "System Id : ")
"Version timestamp :" up to 1 result from -version
argv[0]= timestamp
"Volume Id :" up to 1 result from -pvd_info
argv[0]= id
(Note: Not output from -dev or -toc but from -pvd_info)
"Volume Set Id:" up to 1 result from -pvd_info
argv[0]= id
(Note: prefix is "Volume Set Id: ")
"Volume id :" up to 2 results from -dev, -indev, -toc, others
argv[0]= volume id
(Note: Not output from -pvd_info but from -dev or -toc)
"Write speed :" up to 100 results from -list_speeds
argv[0]= kilobytes per second
argv[1]= speed factor
"Write speed H:" up to 1 result from -list_speeds
see "Write speed :"
"Write speed L:" up to 1 result from -list_speeds
see "Write speed :"
"Write speed h:" up to 1 result from -list_speeds
see "Write speed :"
"Write speed l:" up to 1 result from -list_speeds
see "Write speed :"
"libburn in use :" up to 1 result from -version
argv[0]= version text
argv[1]= minimum version requirement
"libburn OS adapter:" up to 1 result from -version
argv[0]= adapter description
(Note: prefix is "libburn OS adapter: ")
"libisoburn in use :" up to 1 result from -version
argv[0]= version text
argv[1]= minimum version requirement
"libisofs in use :" up to 1 result from -version
argv[0]= version text
argv[1]= minimum version requirement
"libjte in use :" up to 1 result from -version
argv[0]= version text
argv[1]= minimum version requirement
"xorriso version :" up to 1 result from -version
argv[0]= version text
"zisofs :" up to 1 result from -list_extras
argv[0]= "yes" or "no"
------------------------------------------------------------------------
@since 1.2.6
@param xorriso The environment handle
@param flag Unused yet. Submit 0.
@return <=0 error , >0 success
*/
int Xorriso_sieve_big(struct XorrisO *xorriso, 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
later time be retrieved by the application.