manual_3.html

高效率的一种通用压缩/解压程序

<PRE>
   int bzCompress ( bz_stream *strm, int action );
</PRE>

<P>
Provides more input and/or output buffer space for the library.  The
caller maintains input and output buffers, and calls <CODE>bzCompress</CODE> to
transfer data between them.

</P>
<P>
Before each call to <CODE>bzCompress</CODE>, <CODE>next_in</CODE> should point at
the data to be compressed, and <CODE>avail_in</CODE> should indicate how many
bytes the library may read.  <CODE>bzCompress</CODE> updates <CODE>next_in</CODE>,
<CODE>avail_in</CODE> and <CODE>total_in</CODE> to reflect the number of bytes it
has read.

</P>
<P>
Similarly, <CODE>next_out</CODE> should point to a buffer in which the
compressed data is to be placed, with <CODE>avail_out</CODE> indicating how
much output space is available.  <CODE>bzCompress</CODE> updates
<CODE>next_out</CODE>, <CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect the
number of bytes output.

</P>
<P>
You may provide and remove as little or as much data as you like on each
call of <CODE>bzCompress</CODE>.  In the limit, it is acceptable to supply and
remove data one byte at a time, although this would be terribly
inefficient.  You should always ensure that at least one byte of output
space is available at each call.

</P>
<P>
A second purpose of <CODE>bzCompress</CODE> is to request a change of mode of the
compressed stream.  

</P>
<P>
Conceptually, a compressed stream can be in one of four states: IDLE,
RUNNING, FLUSHING and FINISHING.  Before initialisation
(<CODE>bzCompressInit</CODE>) and after termination (<CODE>bzCompressEnd</CODE>), a
stream is regarded as IDLE.

</P>
<P>
Upon initialisation (<CODE>bzCompressInit</CODE>), the stream is placed in the
RUNNING state.  Subsequent calls to <CODE>bzCompress</CODE> should pass
<CODE>BZ_RUN</CODE> as the requested action; other actions are illegal and
will result in <CODE>BZ_SEQUENCE_ERROR</CODE>.

</P>
<P>
At some point, the calling program will have provided all the input data
it wants to.  It will then want to finish up -- in effect, asking the
library to process any data it might have buffered internally.  In this
state, <CODE>bzCompress</CODE> will no longer attempt to read data from
<CODE>next_in</CODE>, but it will want to write data to <CODE>next_out</CODE>.
Because the output buffer supplied by the user can be arbitrarily small,
the finishing-up operation cannot necessarily be done with a single call
of <CODE>bzCompress</CODE>.

</P>
<P>
Instead, the calling program passes <CODE>BZ_FINISH</CODE> as an action to
<CODE>bzCompress</CODE>.  This changes the stream's state to FINISHING.  Any
remaining input (ie, <CODE>next_in[0 .. avail_in-1]</CODE>) is compressed and
transferred to the output buffer.  To do this, <CODE>bzCompress</CODE> must be
called repeatedly until all the output has been consumed.  At that
point, <CODE>bzCompress</CODE> returns <CODE>BZ_STREAM_END</CODE>, and the stream's
state is set back to IDLE.  <CODE>bzCompressEnd</CODE> should then be
called.

</P>
<P>
Just to make sure the calling program does not cheat, the library makes
a note of <CODE>avail_in</CODE> at the time of the first call to
<CODE>bzCompress</CODE> which has <CODE>BZ_FINISH</CODE> as an action (ie, at the
time the program has announced its intention to not supply any more
input).  By comparing this value with that of <CODE>avail_in</CODE> over
subsequent calls to <CODE>bzCompress</CODE>, the library can detect any
attempts to slip in more data to compress.  Any calls for which this is
detected will return <CODE>BZ_SEQUENCE_ERROR</CODE>.  This indicates a
programming mistake which should be corrected.

</P>
<P>
Instead of asking to finish, the calling program may ask
<CODE>bzCompress</CODE> to take all the remaining input, compress it and
terminate the current (Burrows-Wheeler) compression block.  This could
be useful for error control purposes.  The mechanism is analogous to
that for finishing: call <CODE>bzCompress</CODE> with an action of
<CODE>BZ_FLUSH</CODE>, remove output data, and persist with the
<CODE>BZ_FLUSH</CODE> action until the value <CODE>BZ_RUN</CODE> is returned.  As
with finishing, <CODE>bzCompress</CODE> detects any attempt to provide more
input data once the flush has begun.

</P>
<P>
Once the flush is complete, the stream returns to the normal RUNNING
state.

</P>
<P>
This all sounds pretty complex, but isn't really.  Here's a table
which shows which actions are allowable in each state, what action
will be taken, what the next state is, and what the non-error return
values are.  Note that you can't explicitly ask what state the
stream is in, but nor do you need to -- it can be inferred from the
values returned by <CODE>bzCompress</CODE>.

<PRE>
IDLE/<CODE>any</CODE>           
      Illegal.  IDLE state only exists after <CODE>bzCompressEnd</CODE> or
      before <CODE>bzCompressInit</CODE>.
      Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>

RUNNING/<CODE>BZ_RUN</CODE>     
      Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible.
      Next state = RUNNING
      Return value = <CODE>BZ_RUN_OK</CODE>

RUNNING/<CODE>BZ_FLUSH</CODE>   
      Remember current value of <CODE>next_in</CODE>.  Compress from <CODE>next_in</CODE>
      to <CODE>next_out</CODE> as much as possible, but do not accept any more input.  
      Next state = FLUSHING
      Return value = <CODE>BZ_FLUSH_OK</CODE>

RUNNING/<CODE>BZ_FINISH</CODE>  
      Remember current value of <CODE>next_in</CODE>.  Compress from <CODE>next_in</CODE>
      to <CODE>next_out</CODE> as much as possible, but do not accept any more input.
      Next state = FINISHING
      Return value = <CODE>BZ_FINISH_OK</CODE>

FLUSHING/<CODE>BZ_FLUSH</CODE>  
      Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible, 
      but do not accept any more input.  
      If all the existing input has been used up and all compressed
      output has been removed
         Next state = RUNNING; Return value = <CODE>BZ_RUN_OK</CODE>
      else
         Next state = FLUSHING; Return value = <CODE>BZ_FLUSH_OK</CODE>

FLUSHING/other     
      Illegal.
      Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>

FINISHING/<CODE>BZ_FINISH</CODE>  
      Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible,
      but to not accept any more input.  
      If all the existing input has been used up and all compressed
      output has been removed
         Next state = IDLE; Return value = <CODE>BZ_STREAM_END</CODE>
      else
         Next state = FINISHING; Return value = <CODE>BZ_FINISHING</CODE>

FINISHING/other
      Illegal.
      Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
</PRE>

<P>
That still looks complicated?  Well, fair enough.  The usual sequence
of calls for compressing a load of data is:

<UL>
<LI>Get started with <CODE>bzCompressInit</CODE>.

<LI>Shovel data in and shlurp out its compressed form using zero or more

calls of <CODE>bzCompress</CODE> with action = <CODE>BZ_RUN</CODE>.
<LI>Finish up.

Repeatedly call <CODE>bzCompress</CODE> with action = <CODE>BZ_FINISH</CODE>, 
copying out the compressed output, until <CODE>BZ_STREAM_END</CODE> is returned.
<LI>Close up and go home.  Call <CODE>bzCompressEnd</CODE>.

</UL>

<P>
If the data you want to compress fits into your input buffer all
at once, you can skip the calls of <CODE>bzCompress ( ..., BZ_RUN )</CODE> and 
just do the <CODE>bzCompress ( ..., BZ_FINISH )</CODE> calls.

</P>
<P>
All required memory is allocated by <CODE>bzCompressInit</CODE>.  The
compression library can accept any data at all (obviously).  So you
shouldn't get any error return values from the <CODE>bzCompress</CODE> calls.
If you do, they will be <CODE>BZ_SEQUENCE_ERROR</CODE>, and indicate a bug in
your programming.

</P>
<P>
Trivial other possible return values:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE>   
         if <CODE>strm</CODE> is <CODE>NULL</CODE>, or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
</PRE>



<H3><A NAME="SEC12" HREF="manual_toc.html#TOC12"><CODE>bzCompressEnd</CODE></A></H3>

<PRE>
int bzCompressEnd ( bz_stream *strm );
</PRE>

<P>
Releases all memory associated with a compression stream.

</P>
<P>
Possible return values:

<PRE>
   <CODE>BZ_PARAM_ERROR</CODE>    if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
   <CODE>BZ_OK</CODE>    otherwise
</PRE>



<H3><A NAME="SEC13" HREF="manual_toc.html#TOC13"><CODE>bzDecompressInit</CODE></A></H3>

<PRE>
int bzDecompressInit ( bz_stream *strm, int verbosity, int small );
</PRE>

<P>
Prepares for decompression.  As with <CODE>bzCompressInit</CODE>, a
<CODE>bz_stream</CODE> record should be allocated and initialised before the
call.  Fields <CODE>bzalloc</CODE>, <CODE>bzfree</CODE> and <CODE>opaque</CODE> should be
set if a custom memory allocator is required, or made <CODE>NULL</CODE> for
the normal <CODE>malloc</CODE>/<CODE>free</CODE> routines.  Upon return, the internal
state will have been initialised, and <CODE>total_in</CODE> and
<CODE>total_out</CODE> will be zero.

</P>
<P>
For the meaning of parameter <CODE>verbosity</CODE>, see <CODE>bzCompressInit</CODE>.

</P>
<P>
If <CODE>small</CODE> is nonzero, the library will use an alternative
decompression algorithm which uses less memory but at the cost of
decompressing more slowly (roughly speaking, half the speed, but the
maximum memory requirement drops to around 2300k).  See Chapter 2 for
more information on memory management.

</P>
<P>
Note that the amount of memory needed to decompress
a stream cannot be determined until the stream's header has been read,
so even if <CODE>bzDecompressInit</CODE> succeeds, a subsequent
<CODE>bzDecompress</CODE> could fail with <CODE>BZ_MEM_ERROR</CODE>.

</P>
<P>
Possible return values:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>(small != 0 &#38;&#38; small != 1)</CODE>
         or <CODE>(verbosity &#60; 0 || verbosity &#62; 4)</CODE>
      <CODE>BZ_MEM_ERROR</CODE>
         if insufficient memory is available
</PRE>

<P>
Allowable next actions:

<PRE>
      <CODE>bzDecompress</CODE>
         if <CODE>BZ_OK</CODE> was returned
      no specific action required in case of error
</PRE>

<P>
 

</P>


<H3><A NAME="SEC14" HREF="manual_toc.html#TOC14"><CODE>bzDecompress</CODE></A></H3>

<PRE>
int bzDecompress ( bz_stream *strm );
</PRE>

<P>
Provides more input and/out output buffer space for the library.  The
caller maintains input and output buffers, and uses <CODE>bzDecompress</CODE>
to transfer data between them.

</P>
<P>
Before each call to <CODE>bzDecompress</CODE>, <CODE>next_in</CODE> 
should point at the compressed data,
and <CODE>avail_in</CODE> should indicate how many bytes the library
may read.  <CODE>bzDecompress</CODE> updates <CODE>next_in</CODE>, <CODE>avail_in</CODE> 
and <CODE>total_in</CODE>
to reflect the number of bytes it has read.

</P>
<P>
Similarly, <CODE>next_out</CODE> should point to a buffer in which the uncompressed
output is to be placed, with <CODE>avail_out</CODE> indicating how much output space
is available.  <CODE>bzCompress</CODE> updates <CODE>next_out</CODE>,
<CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect
the number of bytes output.

</P>
<P>
You may provide and remove as little or as much data as you like on
each call of <CODE>bzDecompress</CODE>.  
In the limit, it is acceptable to
supply and remove data one byte at a time, although this would be
terribly inefficient.  You should always ensure that at least one
byte of output space is available at each call.

</P>
<P>
Use of <CODE>bzDecompress</CODE> is simpler than <CODE>bzCompress</CODE>.

</P>
<P>
You should provide input and remove output as described above, and
repeatedly call <CODE>bzDecompress</CODE> until <CODE>BZ_STREAM_END</CODE> is
returned.  Appearance of <CODE>BZ_STREAM_END</CODE> denotes that
<CODE>bzDecompress</CODE> has detected the logical end of the compressed
stream.  <CODE>bzDecompress</CODE> will not produce <CODE>BZ_STREAM_END</CODE> until
all output data has been placed into the output buffer, so once
<CODE>BZ_STREAM_END</CODE> appears, you are guaranteed to have available all
the decompressed output, and <CODE>bzDecompressEnd</CODE> can safely be
called.

</P>
<P>
If case of an error return value, you should call <CODE>bzDecompressEnd</CODE>
to clean up and release memory.

</P>
<P>
Possible return values:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
         or <CODE>strm-&#62;avail_out &#60; 1</CODE>
      <CODE>BZ_DATA_ERROR</CODE>
         if a data integrity error is detected in the compressed stream
      <CODE>BZ_DATA_ERROR_MAGIC</CODE>
         if the compressed stream doesn't begin with the right magic bytes
      <CODE>BZ_MEM_ERROR</CODE>
         if there wasn't enough memory available
      <CODE>BZ_STREAM_END</CODE>
         if the logical end of the data stream was detected and all
         output in has been consumed, eg <CODE>s-&#62;avail_out &#62; 0</CODE>
      <CODE>BZ_OK</CODE>
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      <CODE>bzDecompress</CODE>
         if <CODE>BZ_OK</CODE> was returned
      <CODE>bzDecompressEnd</CODE>
         otherwise
</PRE>



<H3><A NAME="SEC15" HREF="manual_toc.html#TOC15"><CODE>bzDecompressEnd</CODE></A></H3>

<PRE>
int bzDecompressEnd ( bz_stream *strm );
</PRE>

<P>
Releases all memory associated with a decompression stream.

</P>
<P>
Possible return values:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
      <CODE>BZ_OK</CODE>
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      None.
</PRE>



<H2><A NAME="SEC16" HREF="manual_toc.html#TOC16">High-level interface</A></H2>