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