src/liblzma/api/lzma/block.h

   1 /**
   2  * \file        lzma/block.h
   3  * \brief       .xz 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_header_encode()
  40          *  - lzma_block_header_decode()
  41          *  - lzma_block_decoder()
  42          *
  43          * Written by:
  44          *  - lzma_block_header_size()
  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_header_encode()
  58          *  - lzma_block_header_decode()
  59          *  - lzma_block_encoder()
  60          *  - lzma_block_decoder()
  61          */
  62         lzma_check check;
  63
  64         /**
  65          * \brief       Size of the Compressed Data in bytes
  66          *
  67          * Usually you don't know this value when encoding in streamed mode.
  68          * In non-streamed mode you can reserve space for this field when
  69          * encoding the Block Header the first time, and then re-encode the
  70          * Block Header and copy it over the original one after the encoding
  71          * of the Block has been finished.
  72          *
  73          * Read by:
  74          *  - lzma_block_header_size()
  75          *  - lzma_block_header_encode()
  76          *  - lzma_block_decoder()
  77          *
  78          * Written by:
  79          *  - lzma_block_header_decode()
  80          *  - lzma_block_encoder()
  81          *  - lzma_block_decoder()
  82          */
  83         lzma_vli compressed_size;
  84
  85         /**
  86          * \brief       Uncompressed Size in bytes
  87          *
  88          * Encoder: If this value is not LZMA_VLI_UNKNOWN, it is stored
  89          * to the Uncompressed Size field in the Block Header. The real
  90          * uncompressed size of the data being compressed must match
  91          * the Uncompressed Size or LZMA_OPTIONS_ERROR is returned.
  92          *
  93          * If Uncompressed Size is unknown, End of Payload Marker must
  94          * be used. If uncompressed_size == LZMA_VLI_UNKNOWN and
  95          * has_eopm == 0, LZMA_OPTIONS_ERROR will be returned.
  96          *
  97          * Decoder: If this value is not LZMA_VLI_UNKNOWN, it is
  98          * compared to the real Uncompressed Size. If they do not match,
  99          * LZMA_OPTIONS_ERROR is returned.
 100          *
 101          * Read by:
 102          *  - lzma_block_header_size()
 103          *  - lzma_block_header_encode()
 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_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_UNKNOWN and .options == NULL. If
 129          *    decoding fails, all filters[] are guaranteed to be
 130          *    LZMA_VLI_UNKNOWN and NULL.
 131          *
 132          * \note        Because of the array is terminated with
 133          *              .id = LZMA_VLI_UNKNOWN, the actual array must
 134          *              have LZMA_FILTERS_MAX + 1 members or the Block
 135          *              Header decoder will overflow the buffer.
 136          */
 137         lzma_filter *filters;
 138
 139 } lzma_block;
 140
 141
 142 /**
 143  * \brief       Decodes the Block Header Size field
 144  *
 145  * To decode Block Header using lzma_block_header_decode(), the size of the
 146  * Block Header has to be known and stored into lzma_block.header_size.
 147  * The size can be calculated from the first byte of a Block using this macro.
 148  * Note that if the first byte is 0x00, it indicates beginning of Index; use
 149  * this macro only when the byte is not 0x00.
 150  *
 151  * There is no encoding macro, because Block Header encoder is enough for that.
 152  */
 153 #define lzma_block_header_size_decode(b) (((uint32_t)(b) + 1) * 4)
 154
 155
 156 /**
 157  * \brief       Calculates the size of Block Header
 158  *
 159  * \return      - LZMA_OK: Size calculated successfully and stored to
 160  *                options->header_size.
 161  *              - LZMA_OPTIONS_ERROR: Unsupported filters or filter options.
 162  *              - LZMA_PROG_ERROR: Invalid options
 163  *
 164  * \note        This doesn't check that all the options are valid i.e. this
 165  *              may return LZMA_OK even if lzma_block_header_encode() or
 166  *              lzma_block_encoder() would fail.
 167  */
 168 extern lzma_ret lzma_block_header_size(lzma_block *options)
 169                 lzma_attr_warn_unused_result;
 170
 171
 172 /**
 173  * \brief       Encodes Block Header
 174  *
 175  * Encoding of the Block options is done with a single call instead of
 176  * first initializing and then doing the actual work with lzma_code().
 177  *
 178  * \param       out         Beginning of the output buffer. This must be
 179  *                          at least options->header_size bytes.
 180  * \param       options     Block options to be encoded.
 181  *
 182  * \return      - LZMA_OK: Encoding was successful. options->header_size
 183  *                bytes were written to output buffer.
 184  *              - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
 185  *              - LZMA_PROG_ERROR
 186  */
 187 extern lzma_ret lzma_block_header_encode(
 188                 const lzma_block *options, uint8_t *out)
 189                 lzma_attr_warn_unused_result;
 190
 191
 192 /**
 193  * \brief       Decodes Block Header
 194  *
 195  * Decoding of the Block options is done with a single call instead of
 196  * first initializing and then doing the actual work with lzma_code().
 197  *
 198  * \param       options     Destination for block options
 199  * \param       allocator   lzma_allocator for custom allocator functions.
 200  *                          Set to NULL to use malloc().
 201  * \param       in          Beginning of the input buffer. This must be
 202  *                          at least options->header_size bytes.
 203  *
 204  * \return      - LZMA_OK: Decoding was successful. options->header_size
 205  *                bytes were written to output buffer.
 206  *              - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
 207  *              - LZMA_PROG_ERROR
 208  */
 209 extern lzma_ret lzma_block_header_decode(lzma_block *options,
 210                 lzma_allocator *allocator, const uint8_t *in)
 211                 lzma_attr_warn_unused_result;
 212
 213
 214 /**
 215  * \brief       Sets Compressed Size according to Unpadded Size
 216  *
 217  * Block Header stores Compressed Size, but Index has Unpadded Size. If the
 218  * application has already parsed the Index and is now decoding Blocks,
 219  * it can calculate Compressed Size from Unpadded Size. This function does
 220  * exactly that with error checking, so application doesn't need to check,
 221  * for example, if the value in Index is too small to contain even the
 222  * Block Header. Note that you need to call this function _after_ decoding
 223  * the Block Header field.
 224  *
 225  * \return      - LZMA_OK: options->compressed_size was set successfully.
 226  *              - LZMA_DATA_ERROR: unpadded_size is too small compared to
 227  *                options->header_size and lzma_check_sizes[options->check].
 228  *              - LZMA_PROG_ERROR: Some values are invalid. For example,
 229  *                options->header_size must be a multiple of four, and
 230  *                options->header_size between 8 and 1024 inclusive.
 231  */
 232 extern lzma_ret lzma_block_compressed_size(
 233                 lzma_block *options, lzma_vli unpadded_size)
 234                 lzma_attr_warn_unused_result;
 235
 236
 237 /**
 238  * \brief       Calculates Unpadded Size
 239  *
 240  * This function can be useful after decoding a Block to get Unpadded Size
 241  * that is stored in Index.
 242  *
 243  * \return      Unpadded Size on success, or zero on error.
 244  */
 245 extern lzma_vli lzma_block_unpadded_size(const lzma_block *options)
 246                 lzma_attr_pure;
 247
 248
 249 /**
 250  * \brief       Calculates the total encoded size of a Block
 251  *
 252  * This is equivalent to lzma_block_unpadded_size() except that the returned
 253  * value includes the size of the Block Padding field.
 254  *
 255  * \return      On success, total encoded size of the Block. On error,
 256  *              zero is returned.
 257  */
 258 extern lzma_vli lzma_block_total_size(const lzma_block *options)
 259                 lzma_attr_pure;
 260
 261
 262 /**
 263  * \brief       Initializes .lzma Block encoder
 264  *
 265  * This function is required for multi-thread encoding. It may also be
 266  * useful when implementing custom file formats.
 267  *
 268  * \return      - LZMA_OK: All good, continue with lzma_code().
 269  *              - LZMA_MEM_ERROR
 270  *              - LZMA_OPTIONS_ERROR
 271  *              - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
 272  *                that is not supported by this buid of liblzma. Initializing
 273  *                the encoder failed.
 274  *              - LZMA_PROG_ERROR
 275  *
 276  * lzma_code() can return FIXME
 277  */
 278 extern lzma_ret lzma_block_encoder(lzma_stream *strm, lzma_block *options)
 279                 lzma_attr_warn_unused_result;
 280
 281
 282 /**
 283  * \brief       Initializes decoder for .lzma Block
 284  *
 285  * \return      - LZMA_OK: All good, continue with lzma_code().
 286  *              - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
 287  *                the given Check type is not supported, thus Check will be
 288  *                ignored.
 289  *              - LZMA_PROG_ERROR
 290  *              - LZMA_MEM_ERROR
 291  */
 292 extern lzma_ret lzma_block_decoder(lzma_stream *strm, lzma_block *options)
 293                 lzma_attr_warn_unused_result;