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