include/lzma/stream_flags.h

0001 /**
0002  * \file        lzma/stream_flags.h
0003  * \brief       .xz Stream Header and Stream Footer encoder and decoder
0004  * \note        Never include this file directly. Use <lzma.h> instead.
0005  */
0006
0007 /*
0008  * Author: Lasse Collin
0009  *
0010  * This file has been put into the public domain.
0011  * You can do whatever you want with this file.
0012  */
0013
0014 #ifndef LZMA_H_INTERNAL
0015 #   error Never include this file directly. Use <lzma.h> instead.
0016 #endif
0017
0018
0019 /**
0020  * \brief       Size of Stream Header and Stream Footer
0021  *
0022  * Stream Header and Stream Footer have the same size and they are not
0023  * going to change even if a newer version of the .xz file format is
0024  * developed in future.
0025  */
0026 #define LZMA_STREAM_HEADER_SIZE 12
0027
0028
0029 /**
0030  * \brief       Options for encoding/decoding Stream Header and Stream Footer
0031  */
0032 typedef struct {
0033     /**
0034      * \brief       Stream Flags format version
0035      *
0036      * To prevent API and ABI breakages if new features are needed in
0037      * Stream Header or Stream Footer, a version number is used to
0038      * indicate which members in this structure are in use. For now,
0039      * version must always be zero. With non-zero version, the
0040      * lzma_stream_header_encode() and lzma_stream_footer_encode()
0041      * will return LZMA_OPTIONS_ERROR.
0042      *
0043      * lzma_stream_header_decode() and lzma_stream_footer_decode()
0044      * will always set this to the lowest value that supports all the
0045      * features indicated by the Stream Flags field. The application
0046      * must check that the version number set by the decoding functions
0047      * is supported by the application. Otherwise it is possible that
0048      * the application will decode the Stream incorrectly.
0049      */
0050     uint32_t version;
0051
0052     /**
0053      * \brief       Backward Size
0054      *
0055      * Backward Size must be a multiple of four bytes. In this Stream
0056      * format version, Backward Size is the size of the Index field.
0057      *
0058      * Backward Size isn't actually part of the Stream Flags field, but
0059      * it is convenient to include in this structure anyway. Backward
0060      * Size is present only in the Stream Footer. There is no need to
0061      * initialize backward_size when encoding Stream Header.
0062      *
0063      * lzma_stream_header_decode() always sets backward_size to
0064      * LZMA_VLI_UNKNOWN so that it is convenient to use
0065      * lzma_stream_flags_compare() when both Stream Header and Stream
0066      * Footer have been decoded.
0067      */
0068     lzma_vli backward_size;
0069
0070     /**
0071      * \brief       Minimum value for lzma_stream_flags.backward_size
0072      */
0073 #   define LZMA_BACKWARD_SIZE_MIN 4
0074
0075     /**
0076      * \brief       Maximum value for lzma_stream_flags.backward_size
0077      */
0078 #   define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34)
0079
0080     /**
0081      * \brief       Check ID
0082      *
0083      * This indicates the type of the integrity check calculated from
0084      * uncompressed data.
0085      */
0086     lzma_check check;
0087
0088     /*
0089      * Reserved space to allow possible future extensions without
0090      * breaking the ABI. You should not touch these, because the
0091      * names of these variables may change.
0092      *
0093      * (We will never be able to use all of these since Stream Flags
0094      * is just two bytes plus Backward Size of four bytes. But it's
0095      * nice to have the proper types when they are needed.)
0096      */
0097
0098     /** \private     Reserved member. */
0099     lzma_reserved_enum reserved_enum1;
0100
0101     /** \private     Reserved member. */
0102     lzma_reserved_enum reserved_enum2;
0103
0104     /** \private     Reserved member. */
0105     lzma_reserved_enum reserved_enum3;
0106
0107     /** \private     Reserved member. */
0108     lzma_reserved_enum reserved_enum4;
0109
0110     /** \private     Reserved member. */
0111     lzma_bool reserved_bool1;
0112
0113     /** \private     Reserved member. */
0114     lzma_bool reserved_bool2;
0115
0116     /** \private     Reserved member. */
0117     lzma_bool reserved_bool3;
0118
0119     /** \private     Reserved member. */
0120     lzma_bool reserved_bool4;
0121
0122     /** \private     Reserved member. */
0123     lzma_bool reserved_bool5;
0124
0125     /** \private     Reserved member. */
0126     lzma_bool reserved_bool6;
0127
0128     /** \private     Reserved member. */
0129     lzma_bool reserved_bool7;
0130
0131     /** \private     Reserved member. */
0132     lzma_bool reserved_bool8;
0133
0134     /** \private     Reserved member. */
0135     uint32_t reserved_int1;
0136
0137     /** \private     Reserved member. */
0138     uint32_t reserved_int2;
0139
0140 } lzma_stream_flags;
0141
0142
0143 /**
0144  * \brief       Encode Stream Header
0145  *
0146  * \param       options     Stream Header options to be encoded.
0147  *                          options->backward_size is ignored and doesn't
0148  *                          need to be initialized.
0149  * \param[out]  out         Beginning of the output buffer of
0150  *                          LZMA_STREAM_HEADER_SIZE bytes.
0151  *
0152  * \return      Possible lzma_ret values:
0153  *              - LZMA_OK: Encoding was successful.
0154  *              - LZMA_OPTIONS_ERROR: options->version is not supported by
0155  *                this liblzma version.
0156  *              - LZMA_PROG_ERROR: Invalid options.
0157  */
0158 extern LZMA_API(lzma_ret) lzma_stream_header_encode(
0159         const lzma_stream_flags *options, uint8_t *out)
0160         lzma_nothrow lzma_attr_warn_unused_result;
0161
0162
0163 /**
0164  * \brief       Encode Stream Footer
0165  *
0166  * \param       options     Stream Footer options to be encoded.
0167  * \param[out]  out         Beginning of the output buffer of
0168  *                          LZMA_STREAM_HEADER_SIZE bytes.
0169  *
0170  * \return      Possible lzma_ret values:
0171  *              - LZMA_OK: Encoding was successful.
0172  *              - LZMA_OPTIONS_ERROR: options->version is not supported by
0173  *                this liblzma version.
0174  *              - LZMA_PROG_ERROR: Invalid options.
0175  */
0176 extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
0177         const lzma_stream_flags *options, uint8_t *out)
0178         lzma_nothrow lzma_attr_warn_unused_result;
0179
0180
0181 /**
0182  * \brief       Decode Stream Header
0183  *
0184  * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to
0185  * help comparing Stream Flags from Stream Header and Stream Footer with
0186  * lzma_stream_flags_compare().
0187  *
0188  * \note        When decoding .xz files that contain multiple Streams, it may
0189  *              make sense to print "file format not recognized" only if
0190  *              decoding of the Stream Header of the \a first Stream gives
0191  *              LZMA_FORMAT_ERROR. If non-first Stream Header gives
0192  *              LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is
0193  *              probably more appropriate.
0194  *              For example, the Stream decoder in liblzma uses
0195  *              LZMA_DATA_ERROR if LZMA_FORMAT_ERROR is returned by
0196  *              lzma_stream_header_decode() when decoding non-first Stream.
0197  *
0198  * \param[out]  options     Target for the decoded Stream Header options.
0199  * \param       in          Beginning of the input buffer of
0200  *                          LZMA_STREAM_HEADER_SIZE bytes.
0201  *
0202  *
0203  * \return      Possible lzma_ret values:
0204  *              - LZMA_OK: Decoding was successful.
0205  *              - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
0206  *                buffer cannot be Stream Header.
0207  *              - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header
0208  *                is corrupt.
0209  *              - LZMA_OPTIONS_ERROR: Unsupported options are present
0210  *                in the header.
0211  */
0212 extern LZMA_API(lzma_ret) lzma_stream_header_decode(
0213         lzma_stream_flags *options, const uint8_t *in)
0214         lzma_nothrow lzma_attr_warn_unused_result;
0215
0216
0217 /**
0218  * \brief       Decode Stream Footer
0219  *
0220  * \note        If Stream Header was already decoded successfully, but
0221  *              decoding Stream Footer returns LZMA_FORMAT_ERROR, the
0222  *              application should probably report some other error message
0223  *              than "file format not recognized". The file likely
0224  *              is corrupt (possibly truncated). The Stream decoder in liblzma
0225  *              uses LZMA_DATA_ERROR in this situation.
0226  *
0227  * \param[out]  options     Target for the decoded Stream Footer options.
0228  * \param       in          Beginning of the input buffer of
0229  *                          LZMA_STREAM_HEADER_SIZE bytes.
0230  *
0231  * \return      Possible lzma_ret values:
0232  *              - LZMA_OK: Decoding was successful.
0233  *              - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
0234  *                buffer cannot be Stream Footer.
0235  *              - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer
0236  *                is corrupt.
0237  *              - LZMA_OPTIONS_ERROR: Unsupported options are present
0238  *                in Stream Footer.
0239  */
0240 extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
0241         lzma_stream_flags *options, const uint8_t *in)
0242         lzma_nothrow lzma_attr_warn_unused_result;
0243
0244
0245 /**
0246  * \brief       Compare two lzma_stream_flags structures
0247  *
0248  * backward_size values are compared only if both are not
0249  * LZMA_VLI_UNKNOWN.
0250  *
0251  * \param       a       Pointer to lzma_stream_flags structure
0252  * \param       b       Pointer to lzma_stream_flags structure
0253  *
0254  * \return      Possible lzma_ret values:
0255  *              - LZMA_OK: Both are equal. If either had backward_size set
0256  *                to LZMA_VLI_UNKNOWN, backward_size values were not
0257  *                compared or validated.
0258  *              - LZMA_DATA_ERROR: The structures differ.
0259  *              - LZMA_OPTIONS_ERROR: version in either structure is greater
0260  *                than the maximum supported version (currently zero).
0261  *              - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
0262  *                backward_size.
0263  */
0264 extern LZMA_API(lzma_ret) lzma_stream_flags_compare(
0265         const lzma_stream_flags *a, const lzma_stream_flags *b)
0266         lzma_nothrow lzma_attr_pure;