manual.xml.svn-base

絲路server源碼 Silk Road server source

  Return value = BZ_FINISH_OK

FLUSHING/BZ_FLUSH
  Compress from next_in to next_out 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 = BZ_RUN_OK
  else
    Next state = FLUSHING; Return value = BZ_FLUSH_OK

FLUSHING/other     
  Illegal.
  Return value = BZ_SEQUENCE_ERROR

FINISHING/BZ_FINISH
  Compress from next_in to next_out 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 = BZ_STREAM_END
  else
    Next state = FINISHING; Return value = BZ_FINISHING

FINISHING/other
  Illegal.
  Return value = BZ_SEQUENCE_ERROR
</programlisting>


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

<orderedlist>

 <listitem><para>Get started with
  <computeroutput>BZ2_bzCompressInit</computeroutput>.</para></listitem>

 <listitem><para>Shovel data in and shlurp out its compressed form
  using zero or more calls of
  <computeroutput>BZ2_bzCompress</computeroutput> with action =
  <computeroutput>BZ_RUN</computeroutput>.</para></listitem>

 <listitem><para>Finish up. Repeatedly call
  <computeroutput>BZ2_bzCompress</computeroutput> with action =
  <computeroutput>BZ_FINISH</computeroutput>, copying out the
  compressed output, until
  <computeroutput>BZ_STREAM_END</computeroutput> is
  returned.</para></listitem> <listitem><para>Close up and go home.  Call
  <computeroutput>BZ2_bzCompressEnd</computeroutput>.</para></listitem>

</orderedlist>

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

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

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

<programlisting>
BZ_PARAM_ERROR
  if strm is NULL, or strm->s is NULL
</programlisting>

</sect2>


<sect2 id="bzCompress-end" xreflabel="BZ2_bzCompressEnd">
<title><computeroutput>BZ2_bzCompressEnd</computeroutput></title>

<programlisting>
int BZ2_bzCompressEnd ( bz_stream *strm );
</programlisting>

<para>Releases all memory associated with a compression
stream.</para>

<para>Possible return values:</para>

<programlisting>
BZ_PARAM_ERROR  if strm is NULL or strm->s is NULL
BZ_OK           otherwise
</programlisting>

</sect2>


<sect2 id="bzDecompress-init" xreflabel="BZ2_bzDecompressInit">
<title><computeroutput>BZ2_bzDecompressInit</computeroutput></title>

<programlisting>
int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small );
</programlisting>

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

<para>For the meaning of parameter
<computeroutput>verbosity</computeroutput>, see
<computeroutput>BZ2_bzCompressInit</computeroutput>.</para>

<para>If <computeroutput>small</computeroutput> 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 <xref linkend="using"/>
for more information on memory management.</para>

<para>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
<computeroutput>BZ2_bzDecompressInit</computeroutput> succeeds, a
subsequent <computeroutput>BZ2_bzDecompress</computeroutput>
could fail with
<computeroutput>BZ_MEM_ERROR</computeroutput>.</para>

<para>Possible return values:</para>

<programlisting>
BZ_CONFIG_ERROR
  if the library has been mis-compiled
BZ_PARAM_ERROR
  if ( small != 0 && small != 1 )
  or (verbosity <; 0 || verbosity > 4)
BZ_MEM_ERROR
  if insufficient memory is available
</programlisting>

<para>Allowable next actions:</para>

<programlisting>
BZ2_bzDecompress
  if BZ_OK was returned
  no specific action required in case of error
</programlisting>

</sect2>


<sect2 id="bzDecompress" xreflabel="BZ2_bzDecompress">
<title><computeroutput>BZ2_bzDecompress</computeroutput></title>

<programlisting>
int BZ2_bzDecompress ( bz_stream *strm );
</programlisting>

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

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

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

<para>You may provide and remove as little or as much data as you
like on each call of
<computeroutput>BZ2_bzDecompress</computeroutput>.  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.</para>

<para>Use of <computeroutput>BZ2_bzDecompress</computeroutput> is
simpler than
<computeroutput>BZ2_bzCompress</computeroutput>.</para>

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

<para>If case of an error return value, you should call
<computeroutput>BZ2_bzDecompressEnd</computeroutput> to clean up
and release memory.</para>

<para>Possible return values:</para>

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

<para>Allowable next actions:</para>

<programlisting>
BZ2_bzDecompress
  if BZ_OK was returned
BZ2_bzDecompressEnd
  otherwise
</programlisting>

</sect2>


<sect2 id="bzDecompress-end" xreflabel="BZ2_bzDecompressEnd">
<title><computeroutput>BZ2_bzDecompressEnd</computeroutput></title>

<programlisting>
int BZ2_bzDecompressEnd ( bz_stream *strm );
</programlisting>

<para>Releases all memory associated with a decompression
stream.</para>

<para>Possible return values:</para>

<programlisting>
BZ_PARAM_ERROR
  if strm is NULL or strm->s is NULL
BZ_OK
  otherwise
</programlisting>

<para>Allowable next actions:</para>

<programlisting>
  None.
</programlisting>

</sect2>

</sect1>


<sect1 id="hl-interface" xreflabel="High-level interface">
<title>High-level interface</title>

<para>This interface provides functions for reading and writing
<computeroutput>bzip2</computeroutput> format files.  First, some
general points.</para>

<itemizedlist mark='bullet'>

 <listitem><para>All of the functions take an
  <computeroutput>int*</computeroutput> first argument,
  <computeroutput>bzerror</computeroutput>.  After each call,
  <computeroutput>bzerror</computeroutput> should be consulted
  first to determine the outcome of the call.  If
  <computeroutput>bzerror</computeroutput> is
  <computeroutput>BZ_OK</computeroutput>, the call completed
  successfully, and only then should the return value of the
  function (if any) be consulted.  If
  <computeroutput>bzerror</computeroutput> is
  <computeroutput>BZ_IO_ERROR</computeroutput>, there was an
  error reading/writing the underlying compressed file, and you
  should then consult <computeroutput>errno</computeroutput> /
  <computeroutput>perror</computeroutput> to determine the cause
  of the difficulty.  <computeroutput>bzerror</computeroutput>
  may also be set to various other values; precise details are
  given on a per-function basis below.</para></listitem>

 <listitem><para>If <computeroutput>bzerror</computeroutput> indicates
  an error (ie, anything except
  <computeroutput>BZ_OK</computeroutput> and
  <computeroutput>BZ_STREAM_END</computeroutput>), you should
  immediately call
  <computeroutput>BZ2_bzReadClose</computeroutput> (or
  <computeroutput>BZ2_bzWriteClose</computeroutput>, depending on
  whether you are attempting to read or to write) to free up all
  resources associated with the stream.  Once an error has been
  indicated, behaviour of all calls except
  <computeroutput>BZ2_bzReadClose</computeroutput>
  (<computeroutput>BZ2_bzWriteClose</computeroutput>) is
  undefined.  The implication is that (1)
  <computeroutput>bzerror</computeroutput> should be checked
  after each call, and (2) if
  <computeroutput>bzerror</computeroutput> in