New command -msg_op

libisoburn/trunk/xorriso/xorriso.1

@@ -9,7 +9,7 @@
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
-.TH XORRISO 1 "Version 1.2.5, Nov 05, 2012"
+.TH XORRISO 1 "Version 1.2.5, Dec 08, 2012"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -4465,6 +4465,83 @@ If text is not empty it will get put out on "M" channel each time
 \fBxorriso\fR is ready for the next dialog line or before
 \fBxorriso\fR performs a command that was entered to the pager prompt.
 .TP
+\fB\-msg_op\fR opcode parameter_text
+This command shall facilitate extraction of particular information from
+the message output of other commands. It gives access to the C API function
+Xorriso_parse_line and to the message sieve that is provided by the C API.
+Please refer to their description in file xorriso.h.
+.br
+Intended users are frontend programs which operate xorriso in dialog mode.
+.br
+The result output of this command is not caught by the message sieve.
+.br
+The following opcodes are defined:
+.br
+\fBstart_sieve\fR
+.br
+Install the message sieve as of Xorriso_sieve_big() and start watching
+program messages. The parameter_text has no meaning.
+.br
+\fBshow_sieve\fR
+.br
+Show a list of filter rule names. The parameter_text has no meaning.
+The list begins by a line with the return value of Xorriso_sieve_get_result()
+with flag bit3. If this value is larger than 0, then the next line tells
+the number of names. The following lines show one name each.
+.br
+\fBread_sieve\fR
+.br
+Use the parameter_text as name of a filter rule and inquire its next
+recorded result.
+See Xorriso_sieve_big() for a list of names and reply strings.
+.br
+The recorded strings are put out on result channel. They get wrapped
+into lines which tell their structure.
+The first line tells the return value of Xorriso_sieve_get_result().
+The next line tells the number of strings. Each string begins by a line that
+tells the number of lines of the string. Then follow these lines. They are to
+be concatenated with a newline character inbetween each of them.
+Finally the number of still available recorded results of the given name
+is put out.
+.br
+\fBclear_sieve\fR
+.br
+Dispose all recorded strings and continue watching program messages.
+The parameter_text has no meaning.
+.br
+\fBend_sieve\fR
+.br
+Dispose the sieve with its filter rules and stop watching program messages.
+The parameter_text has no meaning.
+.br
+\fBparse\fR
+.br
+Read a text from dialog input and submit it to Xorriso_parse_line().
+The parameter_text word shall consist of several words separated by blanks.
+It will be necessary to use both kinds of quotation marks.
+.br
+E.g. "'ISO session  :' '' 0 0 1"
+.br
+The five parameter words are: prefix, separators, max_words, flag,
+number_of_input_lines.
+The former four are handed over to Xorriso_parse_line(). The number of
+input lines minus one tells xorriso how many newline characters are
+part of the input text.
+.br
+The announced number of text lines will be read from dialog input,
+concatenated with a newline character inbetween each of them,
+and submitted to Xorriso_parse_line() as parameter line.
+Note that newlines outside of quotation marks are
+interpreted as separators if the separators parameter is empty.
+.br
+The parsed strings are put out on result channel. They get wrapped
+into lines which tell their structure.
+The first line tells the return value of Xorriso_parse_line().
+The next line tells the number of strings. Each string begins by a line that
+tells the number of lines of the string. Then follow these lines. They are to 
+be concatenated with a newline character inbetween each of them.
+.br
+.TP
 \fB\-prog\fR text
 Use text as name of this program in subsequent messages
 .TP