* Options for encoding and decoding Stream Header and Stream Footer
*/
typedef struct {
+ /**
+ * \brief Stream Flags format version
+ *
+ * To prevent API and ABI breakages if new features are needed in
+ * Stream Header or Stream Footer, a version number is used to
+ * indicate which fields in this structure are in use. For now,
+ * version must always be zero. With non-zero version, the
+ * lzma_stream_header_encode() and lzma_stream_footer_encode()
+ * will return LZMA_HEADER_ERROR.
+ *
+ * lzma_stream_header_decode() and lzma_stream_footer_decode()
+ * will always set this to the lowest value that supports all the
+ * features indicated by the Stream Flags field. The application
+ * must check that the version number set by the decoding functions
+ * is supported by the application. Otherwise it is possible that
+ * the application will decode the Stream incorrectly.
+ */
+ uint32_t version;
+
/**
* Backward Size must be a multiple of four bytes. In this Stream
* format version Backward Size is the size of the Index field.
+ *
+ * Backward Size isn't actually part of the Stream Flags field, but
+ * it is convenient to include in this structure anyway. Backward
+ * Size is present only in the Stream Footer. There is no need to
+ * initialize backward_size when encoding Stream Header.
+ *
+ * lzma_stream_header_decode() always sets backward_size to
+ * LZMA_VLI_VALUE_UNKNOWN so that it is convenient to use
+ * lzma_stream_flags_compare() when both Stream Header and Stream
+ * Footer have been decoded.
*/
lzma_vli backward_size;
# define LZMA_BACKWARD_SIZE_MIN 4
*/
lzma_check check;
+ /**
+ * Reserved space to allow possible future extensions without
+ * breaking the ABI. You should not touch these, because the
+ * names of these variables may change.
+ *
+ * (We will never be able to use all of these since Stream Flags
+ * is just two bytes plus Backward Size of four bytes. But it's
+ * nice to have the proper types when they are needed.)
+ */
+ lzma_reserved_enum reserved_enum1;
+ lzma_reserved_enum reserved_enum2;
+ lzma_reserved_enum reserved_enum3;
+ lzma_reserved_enum reserved_enum4;
+ lzma_reserved_enum reserved_enum5;
+ lzma_reserved_enum reserved_enum6;
+ lzma_bool reserved_bool1;
+ lzma_bool reserved_bool2;
+ lzma_bool reserved_bool3;
+ lzma_bool reserved_bool4;
+ lzma_bool reserved_bool5;
+ lzma_bool reserved_bool6;
+ lzma_bool reserved_bool7;
+ lzma_bool reserved_bool8;
+ uint32_t reserved_int1;
+ uint32_t reserved_int2;
+ uint32_t reserved_int3;
+ uint32_t reserved_int4;
+
} lzma_stream_flags;
* need to be initialized.
*
* \return - LZMA_OK: Encoding was successful.
+ * - LZMA_HEADER_ERROR: options->version is not supported by
+ * this liblzma version.
* - LZMA_PROG_ERROR: Invalid options.
*/
extern lzma_ret lzma_stream_header_encode(
* \param options Stream Footer options to be encoded.
*
* \return - LZMA_OK: Encoding was successful.
+ * - LZMA_HEADER_ERROR: options->version is not supported by
+ * this liblzma version.
* - LZMA_PROG_ERROR: Invalid options.
*/
extern lzma_ret lzma_stream_footer_encode(
*
* options->index_size is always set to LZMA_VLI_VALUE_UNKNOWN. This is to
* help comparing Stream Flags from Stream Header and Stream Footer with
- * lzma_stream_flags_equal().
+ * lzma_stream_flags_compare().
*
* \return - LZMA_OK: Decoding was successful.
* - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
* is corrupt.
* - LZMA_HEADER_ERROR: Unsupported options are present
* in the footer.
+ *
+ * \note If Stream Header was already decoded successfully, but
+ * decoding Stream Footer returns LZMA_FORMAT_ERROR, the
+ * application should probably report some other error message
+ * than "unsupported file format", since the file more likely is
+ * corrupt (possibly truncated). Stream decoder in liblzma uses
+ * LZMA_DATA_ERROR in this situation.
*/
extern lzma_ret lzma_stream_footer_decode(
lzma_stream_flags *options, const uint8_t *in)
/**
* \brief Compare two lzma_stream_flags structures
*
- * index_size values are compared only if both are not LZMA_VLI_VALUE_UNKNOWN.
+ * backward_size values are compared only if both are not
+ * LZMA_VLI_VALUE_UNKNOWN.
*
- * \return true if both structures are considered equal; false otherwise.
+ * \return - LZMA_OK: Both are equal. If either had backward_size set
+ * to LZMA_VLI_VALUE_UNKNOWN, backward_size values were not
+ * compared or validated.
+ * - LZMA_DATA_ERROR: The structures differ.
+ * - LZMA_HEADER_ERROR: version in either structure is greater
+ * than the maximum supported version (currently zero).
+ * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
+ * backward_size.
*/
-extern lzma_bool lzma_stream_flags_equal(
+extern lzma_ret lzma_stream_flags_compare(
const lzma_stream_flags *a, const lzma_stream_flags *b)
lzma_attr_pure;
const uint8_t lzma_footer_magic[2] = { 0x59, 0x5A };
-extern LZMA_API lzma_bool
-lzma_stream_flags_equal(const lzma_stream_flags *a, const lzma_stream_flags *b)
+extern LZMA_API lzma_ret
+lzma_stream_flags_compare(
+ const lzma_stream_flags *a, const lzma_stream_flags *b)
{
+ // We can compare only version 0 structures.
+ if (a->version != 0 || b->version != 0)
+ return LZMA_HEADER_ERROR;
+
+ // Check type
+ if ((unsigned int)(a->check) > LZMA_CHECK_ID_MAX
+ || (unsigned int)(b->check) > LZMA_CHECK_ID_MAX)
+ return LZMA_PROG_ERROR;
+
if (a->check != b->check)
- return false;
+ return LZMA_DATA_ERROR;
// Backward Sizes are compared only if they are known in both.
if (a->backward_size != LZMA_VLI_VALUE_UNKNOWN
- && b->backward_size != LZMA_VLI_VALUE_UNKNOWN
- && a->backward_size != b->backward_size)
- return false;
+ && b->backward_size != LZMA_VLI_VALUE_UNKNOWN) {
+ if (!is_backward_size_valid(a) || !is_backward_size_valid(b))
+ return LZMA_PROG_ERROR;
+
+ if (a->backward_size != b->backward_size)
+ return LZMA_DATA_ERROR;
+ }
- return true;
+ return LZMA_OK;
}
projects / xz / commitdiff