libghc-zlib-bindings-doc 0.1.1.1-3build1 / usr / share / doc / libghc-zlib-bindings-doc / html / zlib-bindings.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Low-level bindings to the zlib package.
--   
--   Provides necessary functions for producing a streaming interface. This
--   is used for example by <tt>zlib-conduit</tt> and <tt>zlib-enum</tt>.
@package zlib-bindings
@version 0.1.1.1

module Codec.Zlib.Lowlevel
data ZStreamStruct
type ZStream' = Ptr ZStreamStruct
zstreamNew :: IO ZStream'
data Strategy
StrategyDefault :: Strategy
StrategyFiltered :: Strategy
StrategyHuffman :: Strategy
StrategyRLE :: Strategy
StrategyFixed :: Strategy
deflateInit2 :: ZStream' -> Int -> WindowBits -> Int -> Strategy -> IO ()
inflateInit2 :: ZStream' -> WindowBits -> IO ()
c_free_z_stream_inflate :: FunPtr (ZStream' -> IO ())
c_free_z_stream_deflate :: FunPtr (ZStream' -> IO ())
c_set_avail_in :: ZStream' -> Ptr CChar -> CUInt -> IO ()
c_set_avail_out :: ZStream' -> Ptr CChar -> CUInt -> IO ()
c_get_avail_out :: ZStream' -> IO CUInt
c_get_avail_in :: ZStream' -> IO CUInt
c_get_next_in :: ZStream' -> IO (Ptr CChar)
c_call_inflate_noflush :: ZStream' -> IO CInt
c_call_deflate_noflush :: ZStream' -> IO CInt
c_call_deflate_finish :: ZStream' -> IO CInt
c_call_deflate_flush :: ZStream' -> IO CInt
c_call_deflate_set_dictionary :: ZStream' -> Ptr CChar -> CUInt -> IO ()
c_call_inflate_set_dictionary :: ZStream' -> Ptr CChar -> CUInt -> IO ()
instance Show Strategy
instance Eq Strategy
instance Ord Strategy
instance Enum Strategy


-- | This is a middle-level wrapper around the zlib C API. It allows you to
--   work fully with bytestrings and not touch the FFI at all, but is still
--   low-level enough to allow you to implement high-level abstractions
--   such as enumerators. Significantly, it does not use lazy IO.
--   
--   You'll probably need to reference the docs a bit to understand the
--   WindowBits parameters below, but a basic rule of thumb is 15 is for
--   zlib compression, and 31 for gzip compression.
--   
--   A simple streaming compressor in pseudo-code would look like:
--   
--   <pre>
--   def &lt;- initDeflate ...
--   popper &lt;- feedDeflate def rawContent
--   pullPopper popper
--   ...
--   finishDeflate def sendCompressedData
--   </pre>
--   
--   You can see a more complete example is available in the included
--   file-test.hs.
module Codec.Zlib

-- | The state of an inflation (eg, decompression) process. All allocated
--   memory is automatically reclaimed by the garbage collector. Also can
--   contain the inflation dictionary that is used for decompression.
data Inflate

-- | Initialize an inflation process with the given <a>WindowBits</a>. You
--   will need to call <a>feedInflate</a> to feed compressed data to this
--   and <a>finishInflate</a> to extract the final chunk of decompressed
--   data.
initInflate :: WindowBits -> IO Inflate

-- | Initialize an inflation process with the given <a>WindowBits</a>.
--   Unlike initInflate a dictionary for inflation is set which must match
--   the one set during compression.
initInflateWithDictionary :: WindowBits -> ByteString -> IO Inflate

-- | Feed the given <a>ByteString</a> to the inflater. This function takes
--   a function argument which takes a "popper". A popper is an IO action
--   that will return the next bit of inflated data, returning
--   <a>Nothing</a> when there is no more data to be popped.
--   
--   Note that this function automatically buffers the output to
--   <a>defaultChunkSize</a>, and therefore you won't get any data from the
--   popper until that much decompressed data is available. After you have
--   fed all of the compressed data to this function, you can extract your
--   final chunk of decompressed data using <a>finishInflate</a>.
feedInflate :: Inflate -> ByteString -> IO Popper

-- | As explained in <a>feedInflate</a>, inflation buffers your
--   decompressed data. After you call <a>feedInflate</a> with your last
--   chunk of compressed data, you will likely have some data still sitting
--   in the buffer. This function will return it to you.
finishInflate :: Inflate -> IO ByteString

-- | Flush the inflation buffer. Useful for interactive application.
--   
--   This is actually a synonym for <a>finishInflate</a>. It is provided
--   for its more semantic name.
--   
--   Since 0.0.3
flushInflate :: Inflate -> IO ByteString

-- | The state of a deflation (eg, compression) process. All allocated
--   memory is automatically reclaimed by the garbage collector.
data Deflate

-- | Initialize a deflation process with the given compression level and
--   <a>WindowBits</a>. You will need to call <a>feedDeflate</a> to feed
--   uncompressed data to this and <a>finishDeflate</a> to extract the
--   final chunks of compressed data.
initDeflate :: Int -> WindowBits -> IO Deflate

-- | Initialize an deflation process with the given compression level and
--   <a>WindowBits</a>. Unlike initDeflate a dictionary for deflation is
--   set.
initDeflateWithDictionary :: Int -> ByteString -> WindowBits -> IO Deflate

-- | Feed the given <a>ByteString</a> to the deflater. This function takes
--   a function argument which takes a "popper". A popper is an IO action
--   that will return the next bit of deflated data, returning
--   <a>Nothing</a> when there is no more data to be popped.
--   
--   Note that this function automatically buffers the output to
--   <a>defaultChunkSize</a>, and therefore you won't get any data from the
--   popper until that much compressed data is available. After you have
--   fed all of the decompressed data to this function, you can extract
--   your final chunks of compressed data using <a>finishDeflate</a>.
feedDeflate :: Deflate -> ByteString -> IO Popper

-- | As explained in <a>feedDeflate</a>, deflation buffers your compressed
--   data. After you call <a>feedDeflate</a> with your last chunk of
--   uncompressed data, we need to flush the rest of the data waiting to be
--   deflated. This function takes a function parameter which accepts a
--   "popper", just like <a>feedDeflate</a>.
finishDeflate :: Deflate -> Popper

-- | Flush the deflation buffer. Useful for interactive application.
--   
--   Internally this passes Z_SYNC_FLUSH to the zlib library.
--   
--   Since 0.0.3
flushDeflate :: Deflate -> Popper

-- | This specifies the size of the compression window. Larger values of
--   this parameter result in better compression at the expense of higher
--   memory usage.
--   
--   The compression window size is the value of the the window bits raised
--   to the power 2. The window bits must be in the range <tt>8..15</tt>
--   which corresponds to compression window sizes of 256b to 32Kb. The
--   default is 15 which is also the maximum size.
--   
--   The total amount of memory used depends on the window bits and the
--   <a>MemoryLevel</a>. See the <a>MemoryLevel</a> for the details.
data WindowBits :: *
WindowBits :: Int -> WindowBits

-- | The default <a>WindowBits</a> is 15 which is also the maximum size.
defaultWindowBits :: WindowBits

-- | Exception that can be thrown from the FFI code. The parameter is the
--   numerical error code from the zlib library. Quoting the zlib.h file
--   directly:
--   
--   <ul>
--   <li>#define Z_OK 0</li>
--   <li>#define Z_STREAM_END 1</li>
--   <li>#define Z_NEED_DICT 2</li>
--   <li>#define Z_ERRNO (-1)</li>
--   <li>#define Z_STREAM_ERROR (-2)</li>
--   <li>#define Z_DATA_ERROR (-3)</li>
--   <li>#define Z_MEM_ERROR (-4)</li>
--   <li>#define Z_BUF_ERROR (-5)</li>
--   <li>#define Z_VERSION_ERROR (-6)</li>
--   </ul>
data ZlibException
ZlibException :: Int -> ZlibException
type Popper = IO (Maybe ByteString)
instance Typeable ZlibException
instance Show ZlibException
instance Exception ZlibException