src/liblzma/api/lzma/stream.h

   1 /**
   2  * \file        lzma/stream.h
   3  * \brief       .lzma Stream handling
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 Lasse Collin
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**
  25  * \brief       Options for .lzma Stream encoder
  26  */
  27 typedef struct {
  28         /**
  29          * \brief       Type of integrity Check
  30          *
  31          * The type of the integrity Check is stored into Stream Header
  32          * and Stream Footer. The same Check is used for all Blocks in
  33          * the Stream.
  34          */
  35         lzma_check_type check;
  36
  37         /**
  38          * \brief       Precense of CRC32 of the Block Header
  39          *
  40          * Set this to true if CRC32 of every Block Header should be
  41          * calculated and stored in the Block Header. This is recommended.
  42          *
  43          * This setting is stored into Stream Header and Stream Footer.
  44          */
  45         lzma_bool has_crc32;
  46
  47         /**
  48          * \brief       Uncompressed Size in bytes
  49          *
  50          * This is somewhat advanced feature. Most users want to set this to
  51          * LZMA_VLI_VALUE_UNKNOWN to indicate unknown Uncompressed Size.
  52          *
  53          * If the Uncompressed Size of the Stream being encoded is known,
  54          * it can be stored to the beginning of the Stream. The details
  55          * differ for Single-Block and Multi-Block Streams:
  56          *  - With Single-Block Streams, the Uncompressed Size is stored to
  57          *    the Block Header and End of Payload Marker is omitted.
  58          *  - With Multi-Block Streams, the Uncompressed Size is stored to
  59          *    the Header Metadata Block. The Uncompressed Size of the Blocks
  60          *    will be unknown, because liblzma cannot predict how the
  61          *    application is going to split the data in Blocks.
  62          */
  63         lzma_vli uncompressed_size;
  64
  65         /**
  66          * \brief       Alignment of the beginning of the Stream
  67          *
  68          * Certain filters handle data in bigger chunks than single bytes.
  69          * This affects two things:
  70          *   - Performance: aligned memory access is usually faster.
  71          *   - Further compression ratio in custom file formats: if you
  72          *     encode multiple Blocks with some non-compression filter
  73          *     such as LZMA_FILTER_POWERPC, it is a good idea to keep
  74          *     the inter-Block alignment correct to maximize compression
  75          *     ratio when all these Blocks are finally compressed as a
  76          *     single step.
  77          *
  78          * Usually the Stream is stored into its own file, thus
  79          * the alignment is usually zero.
  80          */
  81         uint32_t alignment;
  82
  83         /**
  84          * \brief       Array of filters used to encode Data Blocks
  85          *
  86          * There can be at maximum of seven filters. The end of the array is
  87          * marked with .id = LZMA_VLI_VALUE_UNKNOWN. (That's why the array
  88          * has eight members.) Minimum number of filters is zero; in that
  89          * case, an implicit Copy filter is used.
  90          */
  91         lzma_options_filter filters[8];
  92
  93         /**
  94          * \brief       Array of filters used to encode Metadata Blocks
  95          *
  96          * This is like filters[] but for Metadata Blocks. If Metadata
  97          * Blocks are compressed, they usually are compressed with
  98          * settings that require only little memory to uncompress e.g.
  99          * LZMA with 64 KiB dictionary.
 100          *
 101          * \todo        Recommend a preset.
 102          *
 103          * When liblzma sees that the Metadata Block would be very small
 104          * even in uncompressed form, it is not compressed no matter
 105          * what filter have been set here. This is to avoid possibly
 106          * increasing the size of the Metadata Block with bad compression,
 107          * and to avoid useless overhead of filters in uncompression phase.
 108          */
 109         lzma_options_filter metadata_filters[8];
 110
 111         /**
 112          * \brief       Extra information in the Header Metadata Block
 113          */
 114         lzma_extra *header;
 115
 116         /**
 117          * \brief       Extra information in the Footer Metadata Block
 118          *
 119          * It is enough to set this pointer any time before calling
 120          * lzma_code() with LZMA_FINISH as the second argument.
 121          */
 122         lzma_extra *footer;
 123
 124 } lzma_options_stream;
 125
 126
 127 /**
 128  * \brief       Initializes Single-Block .lzma Stream encoder
 129  *
 130  * This is the function that most developers are looking for. :-) It
 131  * compresses using the specified options without storing any extra
 132  * information.
 133  *
 134  * \todo        Describe that is_metadata is ignored, maybe something else.
 135  */
 136 extern lzma_ret lzma_stream_encoder_single(
 137                 lzma_stream *strm, const lzma_options_stream *options);
 138
 139
 140 /**
 141  * \brief       Initializes Multi-Block .lzma Stream encoder
 142  *
 143  */
 144 extern lzma_ret lzma_stream_encoder_multi(
 145                 lzma_stream *strm, const lzma_options_stream *options);
 146
 147
 148 /**
 149  * \brief       Initializes decoder for .lzma Stream
 150  *
 151  * \param       strm        Pointer to propertily prepared lzma_stream
 152  * \param       header      Pointer to hold a pointer to Extra Records read
 153  *                          from the Header Metadata Block. Use NULL if
 154  *                          you don't care about Extra Records.
 155  * \param       footer      Same as header, but for Footer Metadata Block.
 156  *
 157  * \return      - LZMA_OK: Initialization was successful.
 158  *              - LZMA_MEM_ERROR: Cannot allocate memory.
 159  *
 160  * If header and/or footer are not NULL, *header and/or *footer will be
 161  * initially set to NULL.
 162  *
 163  * The application can detect that Header Metadata Block has been completely
 164  * parsed when the decoder procudes some output the first time. If *header
 165  * is still NULL, there was no Extra field in the Header Metadata Block (or
 166  * the whole Header Metadata Block wasn't present at all).
 167  *
 168  * The application can detect that Footer Metadata Block has been parsed
 169  * completely when lzma_code() returns LZMA_STREAM_END. If *footer is still
 170  * NULL, there was no Extra field in the Footer Metadata Block.
 171  *
 172  * \note        If you use lzma_memory_limitter, the Extra Records will be
 173  *              allocated with it, and thus remain in the lzma_memory_limitter
 174  *              even after they get exported to the application via *header
 175  *              and *footer pointers.
 176  */
 177 extern lzma_ret lzma_stream_decoder(lzma_stream *strm,
 178                 lzma_extra **header, lzma_extra **footer);