manual.texi

ReactOS是一些高手根据Windows XP的内核编写出的类XP。内核实现机理和API函数调用几乎相同。甚至可以兼容XP的程序。喜欢研究系统内核的人可以看一看。

         Next state = FINISHING; Return value = @code{BZ_FINISHING}

FINISHING/other
      Illegal.
      Return value = @code{BZ_SEQUENCE_ERROR}
@end display

That still looks complicated?  Well, fair enough.  The usual sequence
of calls for compressing a load of data is:
@itemize @bullet
@item Get started with @code{BZ2_bzCompressInit}.
@item Shovel data in and shlurp out its compressed form using zero or more
calls of @code{BZ2_bzCompress} with action = @code{BZ_RUN}.
@item Finish up.  
Repeatedly call @code{BZ2_bzCompress} with action = @code{BZ_FINISH}, 
copying out the compressed output, until @code{BZ_STREAM_END} is returned.
@item Close up and go home.  Call @code{BZ2_bzCompressEnd}.
@end itemize
If the data you want to compress fits into your input buffer all
at once, you can skip the calls of @code{BZ2_bzCompress ( ..., BZ_RUN )} and 
just do the @code{BZ2_bzCompress ( ..., BZ_FINISH )} calls.

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

Trivial other possible return values:
@display
      @code{BZ_PARAM_ERROR}   
         if @code{strm} is @code{NULL}, or @code{strm->s} is @code{NULL}
@end display

@subsection @code{BZ2_bzCompressEnd}
@example
int BZ2_bzCompressEnd ( bz_stream *strm );
@end example
Releases all memory associated with a compression stream.

Possible return values:
@display
   @code{BZ_PARAM_ERROR}    if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
   @code{BZ_OK}    otherwise
@end display


@subsection @code{BZ2_bzDecompressInit}
@example
int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small );
@end example
Prepares for decompression.  As with @code{BZ2_bzCompressInit}, a
@code{bz_stream} record should be allocated and initialised before the
call.  Fields @code{bzalloc}, @code{bzfree} and @code{opaque} should be
set if a custom memory allocator is required, or made @code{NULL} for
the normal @code{malloc}/@code{free} routines.  Upon return, the internal
state will have been initialised, and @code{total_in} and
@code{total_out} will be zero.

For the meaning of parameter @code{verbosity}, see @code{BZ2_bzCompressInit}.

If @code{small} 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.

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{BZ2_bzDecompressInit} succeeds, a subsequent
@code{BZ2_bzDecompress} could fail with @code{BZ_MEM_ERROR}.

Possible return values:
@display
      @code{BZ_CONFIG_ERROR}
         if the library has been mis-compiled
      @code{BZ_PARAM_ERROR}
         if @code{(small != 0 && small != 1)}
         or @code{(verbosity < 0 || verbosity > 4)}
      @code{BZ_MEM_ERROR}
         if insufficient memory is available
@end display

Allowable next actions:
@display
      @code{BZ2_bzDecompress}
         if @code{BZ_OK} was returned
      no specific action required in case of error
@end display

 

@subsection @code{BZ2_bzDecompress}
@example
int BZ2_bzDecompress ( bz_stream *strm );
@end example
Provides more input and/out output buffer space for the library.  The
caller maintains input and output buffers, and uses @code{BZ2_bzDecompress}
to transfer data between them.

Before each call to @code{BZ2_bzDecompress}, @code{next_in} 
should point at the compressed data,
and @code{avail_in} should indicate how many bytes the library
may read.  @code{BZ2_bzDecompress} updates @code{next_in}, @code{avail_in} 
and @code{total_in}
to reflect the number of bytes it has read.

Similarly, @code{next_out} should point to a buffer in which the uncompressed
output is to be placed, with @code{avail_out} indicating how much output space
is available.  @code{BZ2_bzCompress} updates @code{next_out},
@code{avail_out} and @code{total_out} to reflect
the number of bytes output.

You may provide and remove as little or as much data as you like on
each call of @code{BZ2_bzDecompress}.  
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.

Use of @code{BZ2_bzDecompress} is simpler than @code{BZ2_bzCompress}.

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

If case of an error return value, you should call @code{BZ2_bzDecompressEnd}
to clean up and release memory.

Possible return values:
@display
      @code{BZ_PARAM_ERROR}
         if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
         or @code{strm->avail_out < 1}
      @code{BZ_DATA_ERROR}
         if a data integrity error is detected in the compressed stream
      @code{BZ_DATA_ERROR_MAGIC}
         if the compressed stream doesn't begin with the right magic bytes
      @code{BZ_MEM_ERROR}
         if there wasn't enough memory available
      @code{BZ_STREAM_END}
         if the logical end of the data stream was detected and all
         output in has been consumed, eg @code{s->avail_out > 0}
      @code{BZ_OK}
         otherwise
@end display
Allowable next actions:
@display
      @code{BZ2_bzDecompress}
         if @code{BZ_OK} was returned
      @code{BZ2_bzDecompressEnd}
         otherwise
@end display


@subsection @code{BZ2_bzDecompressEnd}
@example
int BZ2_bzDecompressEnd ( bz_stream *strm );
@end example
Releases all memory associated with a decompression stream.

Possible return values:
@display
      @code{BZ_PARAM_ERROR}
         if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
      @code{BZ_OK}
         otherwise
@end display

Allowable next actions:
@display
      None.
@end display


@section High-level interface

This interface provides functions for reading and writing 
@code{bzip2} format files.  First, some general points.

@itemize @bullet
@item All of the functions take an @code{int*} first argument,
  @code{bzerror}.
  After each call, @code{bzerror} should be consulted first to determine
  the outcome of the call.  If @code{bzerror} is @code{BZ_OK}, 
  the call completed
  successfully, and only then should the return value of the function
  (if any) be consulted.  If @code{bzerror} is @code{BZ_IO_ERROR}, 
  there was an error
  reading/writing the underlying compressed file, and you should
  then consult @code{errno}/@code{perror} to determine the 
  cause of the difficulty.
  @code{bzerror} may also be set to various other values; precise details are
  given on a per-function basis below.
@item If @code{bzerror} indicates an error 
  (ie, anything except @code{BZ_OK} and @code{BZ_STREAM_END}),
  you should immediately call @code{BZ2_bzReadClose} (or @code{BZ2_bzWriteClose},
  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 @code{BZ2_bzReadClose} (@code{BZ2_bzWriteClose}) is undefined.  
  The implication is that (1) @code{bzerror} should
  be checked after each call, and (2) if @code{bzerror} indicates an error, 
  @code{BZ2_bzReadClose} (@code{BZ2_bzWriteClose}) should then be called to clean up.
@item The @code{FILE*} arguments passed to
   @code{BZ2_bzReadOpen}/@code{BZ2_bzWriteOpen}  
  should be set to binary mode.
  Most Unix systems will do this by default, but other platforms,
  including Windows and Mac, will not.  If you omit this, you may
  encounter problems when moving code to new platforms.
@item Memory allocation requests are handled by
  @code{malloc}/@code{free}.  
  At present
  there is no facility for user-defined memory allocators in the file I/O
  functions (could easily be added, though).
@end itemize



@subsection @code{BZ2_bzReadOpen}
@example
   typedef void BZFILE;

   BZFILE *BZ2_bzReadOpen ( int *bzerror, FILE *f, 
                            int small, int verbosity,
                            void *unused, int nUnused );
@end example
Prepare to read compressed data from file handle @code{f}.  @code{f}
should refer to a file which has been opened for reading, and for which
the error indicator (@code{ferror(f)})is not set.  If @code{small} is 1,
the library will try to decompress using less memory, at the expense of
speed.

For reasons explained below, @code{BZ2_bzRead} will decompress the
@code{nUnused} bytes starting at @code{unused}, before starting to read
from the file @code{f}.  At most @code{BZ_MAX_UNUSED} bytes may be
supplied like this.  If this facility is not required, you should pass
@code{NULL} and @code{0} for @code{unused} and n@code{Unused}
respectively.

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

The amount of memory needed to decompress a file cannot be determined
until the file's header has been read.  So it is possible that
@code{BZ2_bzReadOpen} returns @code{BZ_OK} but a subsequent call of
@code{BZ2_bzRead} will return @code{BZ_MEM_ERROR}.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_CONFIG_ERROR}
         if the library has been mis-compiled
      @code{BZ_PARAM_ERROR}
         if @code{f} is @code{NULL} 
         or @code{small} is neither @code{0} nor @code{1}                 
         or @code{(unused == NULL && nUnused != 0)}
         or @code{(unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED))}
      @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{BZ2_bzRead}
         if @code{bzerror} is @code{BZ_OK}   
      @code{BZ2_bzClose} 
         otherwise
@end display


@subsection @code{BZ2_bzRead}
@example
   int BZ2_bzRead ( int *bzerror, BZFILE *b, void *buf, int len );
@end example
Reads up to @code{len} (uncompressed) bytes from the compressed file 
@code{b} into
the buffer @code{buf}.  If the read was successful, 
@code{bzerror} is set to @code{BZ_OK}
and the number of bytes read is returned.  If the logical end-of-stream
was detected, @code{bzerror} will be set to @code{BZ_STREAM_END}, 
and the number
of bytes read is returned.  All other @code{bzerror} values denote an error.

@code{BZ2_bzRead} will supply @code{len} bytes,
unless the logical stream end is detected
or an error occurs.  Because of this, it is possible to detect the 
stream end by observing when the number of bytes returned is 
less than the number
requested.  Nevertheless, this is regarded as inadvisable; you should
instead check @code{bzerror} after every call and watch out for
@code{BZ_STREAM_END}.

Internally, @code{BZ2_bzRead} copies data from the compressed file in chunks
of size @code{BZ_MAX_UNUSED} bytes
before decompressing it.  If the file contains more bytes than strictly
needed to reach the logical end-of-stream, @code{BZ2_bzRead} will almost certainly
read some of the trailing data before signalling @code{BZ_SEQUENCE_END}.