manual.texi

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

Possible assignments to @code{bzerror}:
@display
      @code{BZ_SEQUENCE_ERROR} 
         if @code{b} was opened with @code{bzOpenWrite} 
      @code{BZ_OK} 
         otherwise
@end display

Allowable next actions:
@display
      none
@end display



@subsection @code{bzWriteOpen}
@example
   BZFILE *bzWriteOpen ( int *bzerror, FILE *f, 
                         int blockSize100k, int verbosity,
                         int workFactor );
@end example
Prepare to write compressed data to file handle @code{f}.  
@code{f} should refer to
a file which has been opened for writing, and for which the error
indicator (@code{ferror(f)})is not set.  

For the meaning of parameters @code{blockSize100k},
@code{verbosity} and @code{workFactor}, see
@* @code{bzCompressInit}.

All required memory is allocated at this stage, so if the call
completes successfully, @code{BZ_MEM_ERROR} cannot be signalled by a
subsequent call to @code{bzWrite}.

Possible assignments to @code{bzerror}:
@display 
      @code{BZ_PARAM_ERROR} 
         if @code{f} is @code{NULL} 
         or @code{blockSize100k < 1} or @code{blockSize100k > 9}
      @code{BZ_IO_ERROR} 
         if @code{ferror(f)} is nonzero
      @code{BZ_MEM_ERROR} 
         if insufficient memory is available
      @code{BZ_OK} 
         otherwise
@end display

Possible return values:
@display
      Pointer to an abstract @code{BZFILE}  
         if @code{bzerror} is @code{BZ_OK}   
      @code{NULL} 
         otherwise
@end display

Allowable next actions:
@display
      @code{bzWrite} 
         if @code{bzerror} is @code{BZ_OK} 
         (you could go directly to @code{bzWriteClose}, but this would be pretty pointless)
      @code{bzWriteClose} 
         otherwise
@end display



@subsection @code{bzWrite}
@example
   void bzWrite ( int *bzerror, BZFILE *b, void *buf, int len );
@end example
Absorbs @code{len} bytes from the buffer @code{buf}, eventually to be
compressed and written to the file.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{b} is @code{NULL} or @code{buf} is @code{NULL} or @code{len < 0}
      @code{BZ_SEQUENCE_ERROR} 
         if b was opened with @code{bzReadOpen}
      @code{BZ_IO_ERROR} 
         if there is an error writing the compressed file.
      @code{BZ_OK} 
         otherwise
@end display




@subsection @code{bzWriteClose}
@example
   int bzWriteClose ( int *bzerror, BZFILE* f,
                      int abandon,
                      unsigned int* nbytes_in,
                      unsigned int* nbytes_out );
@end example

Compresses and flushes to the compressed file all data so far supplied
by @code{bzWrite}.  The logical end-of-stream markers are also written, so
subsequent calls to @code{bzWrite} are illegal.  All memory associated 
with the compressed file @code{b} is released.  
@code{fflush} is called on the
compressed file, but it is not @code{fclose}'d.

If @code{bzWriteClose} is called to clean up after an error, the only
action is to release the memory.  The library records the error codes
issued by previous calls, so this situation will be detected
automatically.  There is no attempt to complete the compression
operation, nor to @code{fflush} the compressed file.  You can force this
behaviour to happen even in the case of no error, by passing a nonzero
value to @code{abandon}.

If @code{nbytes_in} is non-null, @code{*nbytes_in} will be set to be the
total volume of uncompressed data handled.  Similarly, @code{nbytes_out}
will be set to the total volume of compressed data written.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_SEQUENCE_ERROR} 
         if @code{b} was opened with @code{bzReadOpen}
      @code{BZ_IO_ERROR} 
         if there is an error writing the compressed file
      @code{BZ_OK} 
         otherwise
@end display

@subsection Handling embedded compressed data streams

The high-level library facilitates use of
@code{bzip2} data streams which form some part of a surrounding, larger
data stream.
@itemize @bullet
@item For writing, the library takes an open file handle, writes
compressed data to it, @code{fflush}es it but does not @code{fclose} it.
The calling application can write its own data before and after the
compressed data stream, using that same file handle.
@item Reading is more complex, and the facilities are not as general
as they could be since generality is hard to reconcile with efficiency.
@code{bzRead} reads from the compressed file in blocks of size
@code{BZ_MAX_UNUSED} bytes, and in doing so probably will overshoot
the logical end of compressed stream.
To recover this data once decompression has
ended, call @code{bzReadGetUnused} after the last call of @code{bzRead}
(the one returning @code{BZ_STREAM_END}) but before calling
@code{bzReadClose}.
@end itemize

This mechanism makes it easy to decompress multiple @code{bzip2}
streams placed end-to-end.  As the end of one stream, when @code{bzRead}
returns @code{BZ_STREAM_END}, call @code{bzReadGetUnused} to collect the
unused data (copy it into your own buffer somewhere).  
That data forms the start of the next compressed stream.
To start uncompressing that next stream, call @code{bzReadOpen} again,
feeding in the unused data via the @code{unused}/@code{nUnused}
parameters.
Keep doing this until @code{BZ_STREAM_END} return coincides with the
physical end of file (@code{feof(f)}).  In this situation
@code{bzReadGetUnused}
will of course return no data.

This should give some feel for how the high-level interface can be used.
If you require extra flexibility, you'll have to bite the bullet and get
to grips with the low-level interface.

@subsection Standard file-reading/writing code
Here's how you'd write data to a compressed file:
@example @code
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "w" );
if (!f) @{
   /* handle error */
@}
b = bzWriteOpen ( &bzerror, f, 9 );
if (bzerror != BZ_OK) @{
   bzWriteClose ( b );
   /* handle error */
@}

while ( /* condition */ ) @{
   /* get data to write into buf, and set nBuf appropriately */
   nWritten = bzWrite ( &bzerror, b, buf, nBuf );
   if (bzerror == BZ_IO_ERROR) @{ 
      bzWriteClose ( &bzerror, b );
      /* handle error */
   @}
@}

bzWriteClose ( &bzerror, b );
if (bzerror == BZ_IO_ERROR) @{
   /* handle error */
@}
@end example
And to read from a compressed file:
@example
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "r" );
if (!f) @{
   /* handle error */
@}
b = bzReadOpen ( &bzerror, f, 0, NULL, 0 );
if (bzerror != BZ_OK) @{
   bzReadClose ( &bzerror, b );
   /* handle error */
@}

bzerror = BZ_OK;
while (bzerror == BZ_OK && /* arbitrary other conditions */) @{
   nBuf = bzRead ( &bzerror, b, buf, /* size of buf */ );
   if (bzerror == BZ_OK) @{
      /* do something with buf[0 .. nBuf-1] */
   @}
@}
if (bzerror != BZ_STREAM_END) @{
   bzReadClose ( &bzerror, b );
   /* handle error */
@} else @{
   bzReadClose ( &bzerror );
@}
@end example



@section Utility functions
@subsection @code{bzBuffToBuffCompress}
@example
   int bzBuffToBuffCompress( char*         dest,
                             unsigned int* destLen,
                             char*         source,
                             unsigned int  sourceLen,
                             int           blockSize100k,
                             int           verbosity,
                             int           workFactor );
@end example
Attempts to compress the data in @code{source[0 .. sourceLen-1]}
into the destination buffer, @code{dest[0 .. *destLen-1]}.
If the destination buffer is big enough, @code{*destLen} is
set to the size of the compressed data, and @code{BZ_OK} is
returned.  If the compressed data won't fit, @code{*destLen}
is unchanged, and @code{BZ_OUTBUFF_FULL} is returned.

Compression in this manner is a one-shot event, done with a single call
to this function.  The resulting compressed data is a complete
@code{bzip2} format data stream.  There is no mechanism for making
additional calls to provide extra input data.  If you want that kind of
mechanism, use the low-level interface.

For the meaning of parameters @code{blockSize100k}, @code{verbosity}
and @code{workFactor}, @* see @code{bzCompressInit}.

To guarantee that the compressed data will fit in its buffer, allocate
an output buffer of size 1% larger than the uncompressed data, plus
six hundred extra bytes.

@code{bzBuffToBuffDecompress} will not write data at or
beyond @code{dest[*destLen]}, even in case of buffer overflow.

Possible return values:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{dest} is @code{NULL} or @code{destLen} is @code{NULL}
         or @code{blockSize100k < 1} or @code{blockSize100k > 9}
         or @code{verbosity < 0} or @code{verbosity > 4} 
         or @code{workFactor < 0} or @code{workFactor > 250}
      @code{BZ_MEM_ERROR}
         if insufficient memory is available 
      @code{BZ_OUTBUFF_FULL}
         if the size of the compressed data exceeds @code{*destLen}
      @code{BZ_OK} 
         otherwise
@end display



@subsection @code{bzBuffToBuffDecompress}
@example
   int bzBuffToBuffDecompress ( char*         dest,
                                unsigned int* destLen,
                                char*         source,
                                unsigned int  sourceLen,
                                int           small,
                                int           verbosity );
@end example
Attempts to decompress the data in @code{source[0 .. sourceLen-1]}
into the destination buffer, @code{dest[0 .. *destLen-1]}.
If the destination buffer is big enough, @code{*destLen} is
set to the size of the uncompressed data, and @code{BZ_OK} is
returned.  If the compressed data won't fit, @code{*destLen}
is unchanged, and @code{BZ_OUTBUFF_FULL} is returned.

@code{source} is assumed to hold a complete @code{bzip2} format
data stream.  @code{bzBuffToBuffDecompress} tries to decompress
the entirety of the stream into the output buffer.

For the meaning of parameters @code{small} and @code{verbosity},
see @code{bzDecompressInit}.

Because the compression ratio of the compressed data cannot be known in
advance, there is no easy way to guarantee that the output buffer will
be big enough.  You may of course make arrangements in your code to
record the size of the uncompressed data, but such a mechanism is beyond
the scope of this library.

@code{bzBuffToBuffDecompress} will not write data at or
beyond @code{dest[*destLen]}, even in case of buffer overflow.

Possible return values:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{dest} is @code{NULL} or @code{destLen} is @code{NULL}
         or @code{small != 0 && small != 1}
         or @code{verbosity < 0} or @code{verbosity > 4} 
      @code{BZ_MEM_ERROR}
         if insufficient memory is available 
      @code{BZ_OUTBUFF_FULL}
         if the size of the compressed data exceeds @code{