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