src/liblzma/api/lzma/block.h

   1 /**
   2  * \file        lzma/block.h
   3  * \brief       .lzma Block 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 the Block Header encoder and decoder
  26  *
  27  * Different things use different parts of this structure. Some read
  28  * some members, other functions write, and some do both. Only the
  29  * members listed for reading need to be initialized when the specified
  30  * functions are called. The members marked for writing will be assigned
  31  * new values at some point either by calling the given function or by
  32  * later calls to lzma_code().
  33  */
  34 typedef struct {
  35         /**
  36          * \brief       Size of the Block Header
  37          *
  38          * Read by:
  39          *  - lzma_block_encoder()
  40          *  - lzma_block_decoder()
  41          *
  42          * Written by:
  43          *  - lzma_block_header_size()
  44          *  - lzma_block_header_decode()
  45          */
  46         uint32_t header_size;
  47 #       define LZMA_BLOCK_HEADER_SIZE_MIN 8
  48 #       define LZMA_BLOCK_HEADER_SIZE_MAX 1024
  49
  50         /**
  51          * \brief       Type of integrity Check
  52          *
  53          * The type of the integrity Check is not stored into the Block
  54          * Header, thus its value must be provided also when decoding.
  55          *
  56          * Read by:
  57          *  - lzma_block_encoder()
  58          *  - lzma_block_decoder()
  59          */
  60         lzma_check_type check;
  61
  62         /**
  63          * \brief       Size of the Compressed Data in bytes
  64          *
  65          * Usually you don't know this value when encoding in streamed mode.
  66          * In non-streamed mode you can reserve space for this field when
  67          * encoding the Block Header the first time, and then re-encode the
  68          * Block Header and copy it over the original one after the encoding
  69          * of the Block has been finished.
  70          *
  71          * Read by:
  72          *  - lzma_block_header_size()
  73          *  - lzma_block_header_encode()
  74          *  - lzma_block_encoder()
  75          *  - lzma_block_decoder()
  76          *
  77          * Written by:
  78          *  - lzma_block_header_decode()
  79          *  - lzma_block_encoder()
  80          *  - lzma_block_decoder()
  81          */
  82         lzma_vli compressed_size;
  83
  84         /**
  85          * \brief       Uncompressed Size in bytes
  86          *
  87          * Encoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is stored
  88          * to the Uncompressed Size field in the Block Header. The real
  89          * uncompressed size of the data being compressed must match
  90          * the Uncompressed Size or LZMA_HEADER_ERROR is returned.
  91          *
  92          * If Uncompressed Size is unknown, End of Payload Marker must
  93          * be used. If uncompressed_size == LZMA_VLI_VALUE_UNKNOWN and
  94          * has_eopm == 0, LZMA_HEADER_ERROR will be returned.
  95          *
  96          * Decoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is
  97          * compared to the real Uncompressed Size. If they do not match,
  98          * LZMA_HEADER_ERROR is returned.
  99          *
 100          * Read by:
 101          *  - lzma_block_header_size()
 102          *  - lzma_block_header_encode()
 103          *  - lzma_block_encoder()
 104          *  - lzma_block_decoder()
 105          *
 106          * Written by:
 107          *  - lzma_block_header_decode()
 108          *  - lzma_block_encoder()
 109          *  - lzma_block_decoder()
 110          */
 111         lzma_vli uncompressed_size;
 112
 113         /**
 114          * \brief       Array of filters
 115          *
 116          * There can be 1-4 filters. The end of the array is marked with
 117          * .id = LZMA_VLI_VALUE_UNKNOWN.
 118          *
 119          * Read by:
 120          *  - lzma_block_header_size()
 121          *  - lzma_block_header_encode()
 122          *  - lzma_block_encoder()
 123          *  - lzma_block_decoder()
 124          *
 125          * Written by:
 126          *  - lzma_block_header_decode(): Note that this does NOT free()
 127          *    the old filter options structures. All unused filters[] will
 128          *    have .id == LZMA_VLI_VALUE_UNKNOWN and .options == NULL. If
 129          *    decoding fails, all filters[] are guaranteed to be
 130          *    LZMA_VLI_VALUE_UNKNOWN and NULL.
 131          *
 132          * \note        Because of the array is terminated with
 133          *              .id = LZMA_VLI_VALUE_UNKNOWN, the actual array must
 134          *              have LZMA_BLOCK_FILTERS_MAX + 1 members or the Block
 135          *              Header decoder will overflow the buffer.
 136          */
 137         lzma_options_filter *filters;
 138 #       define LZMA_BLOCK_FILTERS_MAX 4
 139
 140 } lzma_options_block;
 141
 142
 143 /**
 144  * \brief       Decodes the Block Header Size field
 145  *
 146  * To decode Block Header using lzma_block_header_decode(), the size of the
 147  * Block Header has to be known and stored into lzma_options_block.header_size.
 148  * The size can be calculated from the first byte of a Block using this macro.
 149  * Note that if the first byte is 0x00, it indicates beginning of Index; use
 150  * this macro only when the byte is not 0x00.
 151  */
 152 #define lzma_block_header_size_decode(b) (((uint32_t)(b) + 1) * 4)
 153
 154
 155 /**
 156  * \brief       Calculates the size of Block Header
 157  *
 158  * \return      - LZMA_OK: Size calculated successfully and stored to
 159  *                options->header_size.
 160  *              - LZMA_HEADER_ERROR: Unsupported filters or filter options.
 161  *              - LZMA_PROG_ERROR: Invalid options
 162  *
 163  * \note        This doesn't check that all the options are valid i.e. this
 164  *              may return LZMA_OK even if lzma_block_header_encode() or
 165  *              lzma_block_encoder() would fail.
 166  */
 167 extern lzma_ret lzma_block_header_size(lzma_options_block *options);
 168
 169
 170 /**
 171  * \brief       Encodes Block Header
 172  *
 173  * Encoding of the Block options is done with a single call instead of
 174  * first initializing and then doing the actual work with lzma_code().
 175  *
 176  * \param       out         Beginning of the output buffer. This must be
 177  *                          at least options->header_size bytes.
 178  * \param       options     Block options to be encoded.
 179  *
 180  * \return      - LZMA_OK: Encoding was successful. options->header_size
 181  *                bytes were written to output buffer.
 182  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 183  *              - LZMA_PROG_ERROR
 184  */
 185 extern lzma_ret lzma_block_header_encode(
 186                 const lzma_options_block *options, uint8_t *out);
 187
 188
 189 /**
 190  * \brief       Decodes Block Header
 191  *
 192  * Decoding of the Block options is done with a single call instead of
 193  * first initializing and then doing the actual work with lzma_code().
 194  *
 195  * \param       options     Destination for block options
 196  * \param       allocator   lzma_allocator for custom allocator functions.
 197  *                          Set to NULL to use malloc().
 198  * \param       in          Beginning of the input buffer. This must be
 199  *                          at least options->header_size bytes.
 200  *
 201  * \return      - LZMA_OK: Decoding was successful. options->header_size
 202  *                bytes were written to output buffer.
 203  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 204  *              - LZMA_PROG_ERROR
 205  */
 206 extern lzma_ret lzma_block_header_decode(lzma_options_block *options,
 207                 lzma_allocator *allocator, const uint8_t *in);
 208
 209
 210 /**
 211  * \brief       Sets Compressed Size according to Total Size
 212  *
 213  * Block Header stores Compressed Size, but Index has Total Size. If the
 214  * application has already parsed the Index and is now decoding Blocks,
 215  * it can calculate Compressed Size from Total Size. This function does
 216  * exactly that with error checking, so application doesn't need to check,
 217  * for example, if the value in Index is too small to contain even the
 218  * Block Header. Note that you need to call this function after decoding
 219  * the Block Header field.
 220  *
 221  * \return      - LZMA_OK: options->compressed_size was set successfully.
 222  *              - LZMA_DATA_ERROR: total_size is too small compared to
 223  *                options->header_size and lzma_check_sizes[options->check].
 224  *              - LZMA_PROG_ERROR: Some values are invalid. For example,
 225  *                total_size and options->header_size must be multiples
 226  *                of four, total_size must be at least 12, and
 227  *                options->header_size between 8 and 1024 inclusive.
 228  */
 229 extern lzma_ret lzma_block_total_size_set(
 230                 lzma_options_block *options, lzma_vli total_size);
 231
 232
 233 /**
 234  * \brief       Calculates Total Size
 235  *
 236  * This function can be useful after decoding a Block to get Total Size
 237  * that is stored in Index.
 238  *
 239  * \return      Total Size on success, or zero on error.
 240  */
 241 extern lzma_vli lzma_block_total_size_get(const lzma_options_block *options);
 242
 243
 244 /**
 245  * \brief       Initializes .lzma Block encoder
 246  *
 247  * This function is required for multi-thread encoding. It may also be
 248  * useful when implementing custom file formats.
 249  *
 250  * \return      - LZMA_OK: All good, continue with lzma_code().
 251  *              - LZMA_MEM_ERROR
 252  *              - LZMA_HEADER_ERROR
 253  *              - LZMA_DATA_ERROR: Limits (total_limit and uncompressed_limit)
 254  *                have been reached already.
 255  *              - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
 256  *                that is not supported by this buid of liblzma. Initializing
 257  *                the encoder failed.
 258  *              - LZMA_PROG_ERROR
 259  *
 260  * lzma_code() can return FIXME
 261  */
 262 extern lzma_ret lzma_block_encoder(
 263                 lzma_stream *strm, lzma_options_block *options);
 264
 265
 266 /**
 267  * \brief       Initializes decoder for .lzma Block
 268  *
 269  * \return      - LZMA_OK: All good, continue with lzma_code().
 270  *              - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
 271  *                the given Check type is not supported, thus Check will be
 272  *                ignored.
 273  *              - LZMA_PROG_ERROR
 274  *              - LZMA_MEM_ERROR
 275  */
 276 extern lzma_ret lzma_block_decoder(
 277                 lzma_stream *strm, lzma_options_block *options);