src/liblzma/api/lzma/stream_flags.h

   1 /**
   2  * \file        lzma/stream_flags.h
   3  * \brief       .xz Stream Header and Stream Footer encoder and decoder
   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       Size of Stream Header and Stream Footer
  26  *
  27  * Stream Header and Stream Footer have the same size and they are not
  28  * going to change even if a newer version of the .xz file format is
  29  * developed in future.
  30  */
  31 #define LZMA_STREAM_HEADER_SIZE 12
  32
  33
  34 /**
  35  * Options for encoding and decoding Stream Header and Stream Footer
  36  */
  37 typedef struct {
  38         /**
  39          * \brief       Stream Flags format version
  40          *
  41          * To prevent API and ABI breakages if new features are needed in
  42          * Stream Header or Stream Footer, a version number is used to
  43          * indicate which fields in this structure are in use. For now,
  44          * version must always be zero. With non-zero version, the
  45          * lzma_stream_header_encode() and lzma_stream_footer_encode()
  46          * will return LZMA_OPTIONS_ERROR.
  47          *
  48          * lzma_stream_header_decode() and lzma_stream_footer_decode()
  49          * will always set this to the lowest value that supports all the
  50          * features indicated by the Stream Flags field. The application
  51          * must check that the version number set by the decoding functions
  52          * is supported by the application. Otherwise it is possible that
  53          * the application will decode the Stream incorrectly.
  54          */
  55         uint32_t version;
  56
  57         /**
  58          * \brief       Backward Size
  59          *
  60          * Backward Size must be a multiple of four bytes. In this Stream
  61          * format version, Backward Size is the size of the Index field.
  62          *
  63          * Backward Size isn't actually part of the Stream Flags field, but
  64          * it is convenient to include in this structure anyway. Backward
  65          * Size is present only in the Stream Footer. There is no need to
  66          * initialize backward_size when encoding Stream Header.
  67          *
  68          * lzma_stream_header_decode() always sets backward_size to
  69          * LZMA_VLI_UNKNOWN so that it is convenient to use
  70          * lzma_stream_flags_compare() when both Stream Header and Stream
  71          * Footer have been decoded.
  72          */
  73         lzma_vli backward_size;
  74 #       define LZMA_BACKWARD_SIZE_MIN 4
  75 #       define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34)
  76
  77         /**
  78          * \brief       Check ID
  79          *
  80          * This indicates the type of the integrity check calculated from
  81          * uncompressed data.
  82          */
  83         lzma_check check;
  84
  85         /*
  86          * Reserved space to allow possible future extensions without
  87          * breaking the ABI. You should not touch these, because the
  88          * names of these variables may change.
  89          *
  90          * (We will never be able to use all of these since Stream Flags
  91          * is just two bytes plus Backward Size of four bytes. But it's
  92          * nice to have the proper types when they are needed.)
  93          */
  94         lzma_reserved_enum reserved_enum1;
  95         lzma_reserved_enum reserved_enum2;
  96         lzma_reserved_enum reserved_enum3;
  97         lzma_reserved_enum reserved_enum4;
  98         lzma_reserved_enum reserved_enum5;
  99         lzma_reserved_enum reserved_enum6;
 100         lzma_bool reserved_bool1;
 101         lzma_bool reserved_bool2;
 102         lzma_bool reserved_bool3;
 103         lzma_bool reserved_bool4;
 104         lzma_bool reserved_bool5;
 105         lzma_bool reserved_bool6;
 106         lzma_bool reserved_bool7;
 107         lzma_bool reserved_bool8;
 108         uint32_t reserved_int1;
 109         uint32_t reserved_int2;
 110         uint32_t reserved_int3;
 111         uint32_t reserved_int4;
 112
 113 } lzma_stream_flags;
 114
 115
 116 /**
 117  * \brief       Encode Stream Header
 118  *
 119  * \param       options     Stream Header options to be encoded.
 120  *                          options->backward_size is ignored and doesn't
 121  *                          need to be initialized.
 122  * \param       out         Beginning of the output buffer of
 123  *                          LZMA_STREAM_HEADER_SIZE bytes.
 124  *
 125  * \return      - LZMA_OK: Encoding was successful.
 126  *              - LZMA_OPTIONS_ERROR: options->version is not supported by
 127  *                this liblzma version.
 128  *              - LZMA_PROG_ERROR: Invalid options.
 129  */
 130 extern LZMA_API(lzma_ret) lzma_stream_header_encode(
 131                 const lzma_stream_flags *options, uint8_t *out)
 132                 lzma_attr_warn_unused_result;
 133
 134
 135 /**
 136  * \brief       Encode Stream Footer
 137  *
 138  * \param       options     Stream Footer options to be encoded.
 139  * \param       out         Beginning of the output buffer of
 140  *                          LZMA_STREAM_HEADER_SIZE bytes.
 141  *
 142  * \return      - LZMA_OK: Encoding was successful.
 143  *              - LZMA_OPTIONS_ERROR: options->version is not supported by
 144  *                this liblzma version.
 145  *              - LZMA_PROG_ERROR: Invalid options.
 146  */
 147 extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
 148                 const lzma_stream_flags *options, uint8_t *out)
 149                 lzma_attr_warn_unused_result;
 150
 151
 152 /**
 153  * \brief       Decode Stream Header
 154  *
 155  * \param       options     Stream Header options to be encoded.
 156  * \param       in          Beginning of the input buffer of
 157  *                          LZMA_STREAM_HEADER_SIZE bytes.
 158  *
 159  * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to
 160  * help comparing Stream Flags from Stream Header and Stream Footer with
 161  * lzma_stream_flags_compare().
 162  *
 163  * \return      - LZMA_OK: Decoding was successful.
 164  *              - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
 165  *                buffer cannot be Stream Header.
 166  *              - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header
 167  *                is corrupt.
 168  *              - LZMA_OPTIONS_ERROR: Unsupported options are present
 169  *                in the header.
 170  *
 171  * \note        When decoding .xz files that contain multiple Streams, it may
 172  *              make sense to print "file format not recognized" only if
 173  *              decoding of the Stream Header of the _first_ Stream gives
 174  *              LZMA_FORMAT_ERROR. If non-first Stream Header gives
 175  *              LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is
 176  *              probably more appropriate.
 177  *
 178  *              For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if
 179  *              LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode()
 180  *              when decoding non-first Stream.
 181  */
 182 extern LZMA_API(lzma_ret) lzma_stream_header_decode(
 183                 lzma_stream_flags *options, const uint8_t *in)
 184                 lzma_attr_warn_unused_result;
 185
 186
 187 /**
 188  * \brief       Decode Stream Footer
 189  *
 190  * \param       options     Stream Header options to be encoded.
 191  * \param       in          Beginning of the input buffer of
 192  *                          LZMA_STREAM_HEADER_SIZE bytes.
 193  *
 194  * \return      - LZMA_OK: Decoding was successful.
 195  *              - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
 196  *                buffer cannot be Stream Footer.
 197  *              - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer
 198  *                is corrupt.
 199  *              - LZMA_OPTIONS_ERROR: Unsupported options are present
 200  *                in Stream Footer.
 201  *
 202  * \note        If Stream Header was already decoded successfully, but
 203  *              decoding Stream Footer returns LZMA_FORMAT_ERROR, the
 204  *              application should probably report some other error message
 205  *              than "file format not recognized", since the file more likely
 206  *              is corrupt (possibly truncated). Stream decoder in liblzma
 207  *              uses LZMA_DATA_ERROR in this situation.
 208  */
 209 extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
 210                 lzma_stream_flags *options, const uint8_t *in)
 211                 lzma_attr_warn_unused_result;
 212
 213
 214 /**
 215  * \brief       Compare two lzma_stream_flags structures
 216  *
 217  * backward_size values are compared only if both are not
 218  * LZMA_VLI_UNKNOWN.
 219  *
 220  * \return      - LZMA_OK: Both are equal. If either had backward_size set
 221  *                to LZMA_VLI_UNKNOWN, backward_size values were not
 222  *                compared or validated.
 223  *              - LZMA_DATA_ERROR: The structures differ.
 224  *              - LZMA_OPTIONS_ERROR: version in either structure is greater
 225  *                than the maximum supported version (currently zero).
 226  *              - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
 227  *                backward_size.
 228  */
 229 extern LZMA_API(lzma_ret) lzma_stream_flags_compare(
 230                 const lzma_stream_flags *a, const lzma_stream_flags *b)
 231                 lzma_attr_pure;