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       Type of integrity Check
  37          *
  38          * The type of the integrity Check is not stored into the Block
  39          * Header, thus its value must be provided also when decoding.
  40          *
  41          * Read by:
  42          *  - lzma_block_encoder()
  43          *  - lzma_block_decoder()
  44          */
  45         lzma_check_type check;
  46
  47         /**
  48          * \brief       Precense of CRC32 of the Block Header
  49          *
  50          * Set this to true if CRC32 of the Block Header should be
  51          * calculated and stored in the Block Header.
  52          *
  53          * There is no way to autodetect if CRC32 is present in the Block
  54          * Header, thus this information must be provided also when decoding.
  55          *
  56          * Read by:
  57          *  - lzma_block_header_size()
  58          *  - lzma_block_header_encoder()
  59          *  - lzma_block_header_decoder()
  60          */
  61         lzma_bool has_crc32;
  62
  63         /**
  64          * \brief       Usage of End of Payload Marker
  65          *
  66          * If this is true, End of Payload Marker is used even if
  67          * Uncompressed Size is known.
  68          *
  69          * Read by:
  70          *  - lzma_block_header_encoder()
  71          *  - lzma_block_encoder()
  72          *  - lzma_block_decoder()
  73          *
  74          * Written by:
  75          *  - lzma_block_header_decoder()
  76          */
  77         lzma_bool has_eopm;
  78
  79         /**
  80          * \brief       True if the Block is a Metadata Block
  81          *
  82          * If this is true, the Metadata bit will be set in the Block Header.
  83          * It is up to the application to store correctly formatted data
  84          * into Metadata Block.
  85          *
  86          * Read by:
  87          *  - lzma_block_header_encoder()
  88          *
  89          * Written by:
  90          *  - lzma_block_header_decoder()
  91          */
  92         lzma_bool is_metadata;
  93
  94         /**
  95          * \brief       True if Uncompressed Size is in Block Footer
  96          *
  97          * Read by:
  98          *  - lzma_block_encoder()
  99          *  - lzma_block_decoder()
 100          */
 101         lzma_bool has_uncompressed_size_in_footer;
 102
 103         /**
 104          * \brief       True if Backward Size is in Block Footer
 105          *
 106          * Read by:
 107          *  - lzma_block_encoder()
 108          *  - lzma_block_decoder()
 109          */
 110         lzma_bool has_backward_size;
 111
 112         /**
 113          * \brief       True if Block coder should take care of Padding
 114          *
 115          * In liblzma, Stream decoder sets this to true when decoding
 116          * Header Metadata Block or Data Blocks from Multi-Block Stream,
 117          * and to false when decoding Single-Block Stream or Footer
 118          * Metadata Block from a Multi-Block Stream.
 119          *
 120          * Read by:
 121          *  - lzma_block_encoder()
 122          *  - lzma_block_decoder()
 123          */
 124         lzma_bool handle_padding;
 125
 126         /**
 127          * \brief       Size of the Compressed Data in bytes
 128          *
 129          * Usually you don't know this value when encoding in streamed mode.
 130          * In non-streamed mode you can reserve space for this field when
 131          * encoding the Block Header the first time, and then re-encode the
 132          * Block Header and copy it over the original one after the encoding
 133          * of the Block has been finished.
 134          *
 135          * Read by:
 136          *  - lzma_block_header_size()
 137          *  - lzma_block_header_encoder()
 138          *  - lzma_block_encoder()
 139          *  - lzma_block_decoder()
 140          *
 141          * Written by:
 142          *  - lzma_block_header_decoder()
 143          *  - lzma_block_encoder()
 144          *  - lzma_block_decoder()
 145          */
 146         lzma_vli compressed_size;
 147
 148         /**
 149          * \brief       Uncompressed Size in bytes
 150          *
 151          * Encoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is stored
 152          * to the Uncompressed Size field in the Block Header. The real
 153          * uncompressed size of the data being compressed must match
 154          * the Uncompressed Size or LZMA_HEADER_ERROR is returned.
 155          *
 156          * If Uncompressed Size is unknown, End of Payload Marker must
 157          * be used. If uncompressed_size == LZMA_VLI_VALUE_UNKNOWN and
 158          * has_eopm == 0, LZMA_HEADER_ERROR will be returned.
 159          *
 160          * Decoder: If this value is not LZMA_VLI_VALUE_UNKNOWN, it is
 161          * compared to the real Uncompressed Size. If they do not match,
 162          * LZMA_HEADER_ERROR is returned.
 163          *
 164          * Read by:
 165          *  - lzma_block_header_size()
 166          *  - lzma_block_header_encoder()
 167          *  - lzma_block_encoder()
 168          *  - lzma_block_decoder()
 169          *
 170          * Written by:
 171          *  - lzma_block_header_decoder()
 172          *  - lzma_block_encoder()
 173          *  - lzma_block_decoder()
 174          */
 175         lzma_vli uncompressed_size;
 176
 177         /**
 178          * \brief       Number of bytes to reserve for Compressed Size
 179          *
 180          * This is useful if you want to be able to store the Compressed Size
 181          * to the Block Header, but you don't know it when starting to encode.
 182          * Setting this to non-zero value at maximum of LZMA_VLI_BYTES_MAX,
 183          * the Block Header encoder will force the Compressed Size field to
 184          * occupy specified number of bytes. You can later rewrite the Block
 185          * Header to contain correct information by using otherwise identical
 186          * lzma_options_block structure except the correct compressed_size.
 187          *
 188          * Read by:
 189          *  - lzma_block_header_size()
 190          *  - lzma_block_header_encoder()
 191          *
 192          * Written by:
 193          *  - lzma_block_header_decoder()
 194          */
 195         uint32_t compressed_reserve;
 196
 197         /**
 198          * \brief       Number of bytes to reserve for Uncompressed Size
 199          *
 200          * See the description of compressed_size above.
 201          *
 202          * Read by:
 203          *  - lzma_block_header_size()
 204          *  - lzma_block_header_encoder()
 205          *
 206          * Written by:
 207          *  - lzma_block_header_decoder()
 208          */
 209         uint32_t uncompressed_reserve;
 210
 211         /**
 212          * \brief       Total Size of the Block in bytes
 213          *
 214          * This is useful in the decoder, which can verify the Total Size
 215          * if it is known from Index.
 216          *
 217          * Read by:
 218          *  - lzma_block_encoder()
 219          *  - lzma_block_decoder()
 220          *
 221          * Written by:
 222          *  - lzma_block_encoder()
 223          *  - lzma_block_decoder()
 224          */
 225         lzma_vli total_size;
 226
 227         /**
 228          * \brief       Upper limit of Total Size
 229          *
 230          * Read by:
 231          *  - lzma_block_encoder()
 232          *  - lzma_block_decoder()
 233          */
 234         lzma_vli total_limit;
 235
 236         /**
 237          * \brief       Upper limit of Uncompressed Size
 238          *
 239          * Read by:
 240          *  - lzma_block_encoder()
 241          *  - lzma_block_decoder()
 242          */
 243         lzma_vli uncompressed_limit;
 244
 245         /**
 246          * \brief       Array of filters
 247          *
 248          * There can be at maximum of seven filters. The end of the array
 249          * is marked with .id = LZMA_VLI_VALUE_UNKNOWN. Minimum number of
 250          * filters is zero; in that case, an implicit Copy filter is used.
 251          *
 252          * Read by:
 253          *  - lzma_block_header_size()
 254          *  - lzma_block_header_encoder()
 255          *  - lzma_block_encoder()
 256          *  - lzma_block_decoder()
 257          *
 258          * Written by:
 259          *  - lzma_block_header_decoder(): Note that this does NOT free()
 260          *    the old filter options structures. If decoding fails, the
 261          *    caller must take care of freeing the options structures
 262          *    that may have been allocated and decoded before the error
 263          *    occurred.
 264          */
 265         lzma_options_filter filters[8];
 266
 267         /**
 268          * \brief       Size of the Padding field
 269          *
 270          * The Padding field exist to allow aligning the Compressed Data field
 271          * optimally in the Block. See lzma_options_stream.alignment in
 272          * stream.h for more information.
 273          *
 274          * If you want the Block Header encoder to automatically calculate
 275          * optimal size for the Padding field by looking at the information
 276          * in filters[], set this to LZMA_BLOCK_HEADER_PADDING_AUTO. In that
 277          * case, you must also set the aligmnet variable to tell the the
 278          * encoder the aligmnet of the beginning of the Block Header.
 279          *
 280          * The decoder never sets this to LZMA_BLOCK_HEADER_PADDING_AUTO.
 281          *
 282          * Read by:
 283          *  - lzma_block_header_size()
 284          *  - lzma_block_header_encoder(): Note that this doesn't
 285          *    accept LZMA_BLOCK_HEADER_PADDING_AUTO.
 286          *
 287          * Written by (these never set padding to
 288          * LZMA_BLOCK_HEADER_PADDING_AUTO):
 289          *  - lzma_block_header_size()
 290          *  - lzma_block_header_decoder()
 291          */
 292         int32_t padding;
 293 #       define LZMA_BLOCK_HEADER_PADDING_AUTO (-1)
 294 #       define LZMA_BLOCK_HEADER_PADDING_MIN 0
 295 #       define LZMA_BLOCK_HEADER_PADDING_MAX 31
 296
 297         /**
 298          * \brief       Alignment of the beginning of the Block Header
 299          *
 300          * This variable is read only if padding has been set to
 301          * LZMA_BLOCK_HEADER_PADDING_AUTO.
 302          *
 303          * Read by:
 304          *  - lzma_block_header_size()
 305          *  - lzma_block_header_encoder()
 306          */
 307         uint32_t alignment;
 308
 309         /**
 310          * \brief       Size of the Block Header
 311          *
 312          * Read by:
 313          *  - lzma_block_encoder()
 314          *  - lzma_block_decoder()
 315          *
 316          * Written by:
 317          *  - lzma_block_header_size()
 318          *  - lzma_block_header_decoder()
 319          */
 320         uint32_t header_size;
 321
 322 } lzma_options_block;
 323
 324
 325 /**
 326  * \brief       Calculates the size of Header Padding and Block Header
 327  *
 328  * \return      - LZMA_OK: Size calculated successfully and stored to
 329  *                options->header_size.
 330  *              - LZMA_HEADER_ERROR: Unsupported filters or filter options.
 331  *              - LZMA_PROG_ERROR: Invalid options
 332  *
 333  * \note        This doesn't check that all the options are valid i.e. this
 334  *              may return LZMA_OK even if lzma_block_header_encode() or
 335  *              lzma_block_encoder() would fail.
 336  */
 337 extern lzma_ret lzma_block_header_size(lzma_options_block *options);
 338
 339
 340 /**
 341  * \brief       Encodes Block Header
 342  *
 343  * Encoding of the Block options is done with a single call instead of
 344  * first initializing and then doing the actual work with lzma_code().
 345  *
 346  * \param       out         Beginning of the output buffer. This must be
 347  *                          at least options->header_size bytes.
 348  * \param       options     Block options to be encoded.
 349  *
 350  * \return      - LZMA_OK: Encoding was successful. options->header_size
 351  *                bytes were written to output buffer.
 352  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 353  *              - LZMA_PROG_ERROR
 354  */
 355 extern lzma_ret lzma_block_header_encode(
 356                 uint8_t *out, const lzma_options_block *options);
 357
 358
 359 /**
 360  * \brief       Initializes Block Header decoder
 361  *
 362  * Because the results of this decoder are placed into *options,
 363  * strm->next_in, strm->avail_in, and strm->total_in are not used.
 364  *
 365  * The only valid `action' with lzma_code() is LZMA_RUN.
 366  *
 367  * \return      - LZMA_OK: Encoding was successful. options->header_size
 368  *                bytes were written to output buffer.
 369  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 370  *              - LZMA_PROG_ERROR
 371  */
 372 extern lzma_ret lzma_block_header_decoder(
 373                 lzma_stream *strm, lzma_options_block *options);
 374
 375
 376 /**
 377  * \brief       Initializes .lzma Block encoder
 378  *
 379  * This function is required for multi-thread encoding. It may also be
 380  * useful when implementing custom file formats.
 381  *
 382  * \return      - LZMA_OK: All good, continue with lzma_code().
 383  *              - LZMA_MEM_ERROR
 384  *              - LZMA_HEADER_ERROR
 385  *              - LZMA_DATA_ERROR: Limits (total_limit and uncompressed_limit)
 386  *                have been reached already.
 387  *              - LZMA_UNSUPPORTED_CHECK: options->check specfies a Check
 388  *                that is not supported by this buid of liblzma. Initializing
 389  *                the encoder failed.
 390  *              - LZMA_PROG_ERROR
 391  *
 392  * lzma_code() can return FIXME
 393  */
 394 extern lzma_ret lzma_block_encoder(
 395                 lzma_stream *strm, lzma_options_block *options);
 396
 397
 398 /**
 399  * \brief       Initializes decoder for .lzma Block
 400  *
 401  * \return      - LZMA_OK: All good, continue with lzma_code().
 402  *              - LZMA_UNSUPPORTED_CHECK: Initialization was successful, but
 403  *                the given Check type is not supported, thus Check will be
 404  *                ignored.
 405  *              - LZMA_PROG_ERROR
 406  *              - LZMA_MEM_ERROR
 407  */
 408 extern lzma_ret lzma_block_decoder(
 409                 lzma_stream *strm, lzma_options_block *options);