include/lzma/stream_flags.h

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