2 * \file lzma/stream_flags.h
3 * \brief .xz Stream Header and Stream Footer encoder and decoder
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
25 * \brief Size of Stream Header and Stream Footer
27 * Stream Header and Stream Footer have the same size and they are not
28 * going to change even if a newer version of the .xz file format is
29 * developed in future.
31 #define LZMA_STREAM_HEADER_SIZE 12
35 * Options for encoding and decoding Stream Header and Stream Footer
39 * \brief Stream Flags format version
41 * To prevent API and ABI breakages if new features are needed in
42 * Stream Header or Stream Footer, a version number is used to
43 * indicate which fields in this structure are in use. For now,
44 * version must always be zero. With non-zero version, the
45 * lzma_stream_header_encode() and lzma_stream_footer_encode()
46 * will return LZMA_OPTIONS_ERROR.
48 * lzma_stream_header_decode() and lzma_stream_footer_decode()
49 * will always set this to the lowest value that supports all the
50 * features indicated by the Stream Flags field. The application
51 * must check that the version number set by the decoding functions
52 * is supported by the application. Otherwise it is possible that
53 * the application will decode the Stream incorrectly.
58 * \brief Backward Size
60 * Backward Size must be a multiple of four bytes. In this Stream
61 * format version, Backward Size is the size of the Index field.
63 * Backward Size isn't actually part of the Stream Flags field, but
64 * it is convenient to include in this structure anyway. Backward
65 * Size is present only in the Stream Footer. There is no need to
66 * initialize backward_size when encoding Stream Header.
68 * lzma_stream_header_decode() always sets backward_size to
69 * LZMA_VLI_UNKNOWN so that it is convenient to use
70 * lzma_stream_flags_compare() when both Stream Header and Stream
71 * Footer have been decoded.
73 lzma_vli backward_size;
74 # define LZMA_BACKWARD_SIZE_MIN 4
75 # define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34)
80 * This indicates the type of the integrity check calculated from
86 * Reserved space to allow possible future extensions without
87 * breaking the ABI. You should not touch these, because the
88 * names of these variables may change.
90 * (We will never be able to use all of these since Stream Flags
91 * is just two bytes plus Backward Size of four bytes. But it's
92 * nice to have the proper types when they are needed.)
94 lzma_reserved_enum reserved_enum1;
95 lzma_reserved_enum reserved_enum2;
96 lzma_reserved_enum reserved_enum3;
97 lzma_reserved_enum reserved_enum4;
98 lzma_reserved_enum reserved_enum5;
99 lzma_reserved_enum reserved_enum6;
100 lzma_bool reserved_bool1;
101 lzma_bool reserved_bool2;
102 lzma_bool reserved_bool3;
103 lzma_bool reserved_bool4;
104 lzma_bool reserved_bool5;
105 lzma_bool reserved_bool6;
106 lzma_bool reserved_bool7;
107 lzma_bool reserved_bool8;
108 uint32_t reserved_int1;
109 uint32_t reserved_int2;
110 uint32_t reserved_int3;
111 uint32_t reserved_int4;
117 * \brief Encode Stream Header
119 * \param options Stream Header options to be encoded.
120 * options->backward_size is ignored and doesn't
121 * need to be initialized.
122 * \param out Beginning of the output buffer of
123 * LZMA_STREAM_HEADER_SIZE bytes.
125 * \return - LZMA_OK: Encoding was successful.
126 * - LZMA_OPTIONS_ERROR: options->version is not supported by
127 * this liblzma version.
128 * - LZMA_PROG_ERROR: Invalid options.
130 extern LZMA_API(lzma_ret) lzma_stream_header_encode(
131 const lzma_stream_flags *options, uint8_t *out)
132 lzma_attr_warn_unused_result;
136 * \brief Encode Stream Footer
138 * \param options Stream Footer options to be encoded.
139 * \param out Beginning of the output buffer of
140 * LZMA_STREAM_HEADER_SIZE bytes.
142 * \return - LZMA_OK: Encoding was successful.
143 * - LZMA_OPTIONS_ERROR: options->version is not supported by
144 * this liblzma version.
145 * - LZMA_PROG_ERROR: Invalid options.
147 extern LZMA_API(lzma_ret) lzma_stream_footer_encode(
148 const lzma_stream_flags *options, uint8_t *out)
149 lzma_attr_warn_unused_result;
153 * \brief Decode Stream Header
155 * \param options Stream Header options to be encoded.
156 * \param in Beginning of the input buffer of
157 * LZMA_STREAM_HEADER_SIZE bytes.
159 * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to
160 * help comparing Stream Flags from Stream Header and Stream Footer with
161 * lzma_stream_flags_compare().
163 * \return - LZMA_OK: Decoding was successful.
164 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
165 * buffer cannot be Stream Header.
166 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header
168 * - LZMA_OPTIONS_ERROR: Unsupported options are present
171 * \note When decoding .xz files that contain multiple Streams, it may
172 * make sense to print "file format not recognized" only if
173 * decoding of the Stream Header of the _first_ Stream gives
174 * LZMA_FORMAT_ERROR. If non-first Stream Header gives
175 * LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is
176 * probably more appropriate.
178 * For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if
179 * LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode()
180 * when decoding non-first Stream.
182 extern LZMA_API(lzma_ret) lzma_stream_header_decode(
183 lzma_stream_flags *options, const uint8_t *in)
184 lzma_attr_warn_unused_result;
188 * \brief Decode Stream Footer
190 * \param options Stream Header options to be encoded.
191 * \param in Beginning of the input buffer of
192 * LZMA_STREAM_HEADER_SIZE bytes.
194 * \return - LZMA_OK: Decoding was successful.
195 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
196 * buffer cannot be Stream Footer.
197 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer
199 * - LZMA_OPTIONS_ERROR: Unsupported options are present
202 * \note If Stream Header was already decoded successfully, but
203 * decoding Stream Footer returns LZMA_FORMAT_ERROR, the
204 * application should probably report some other error message
205 * than "file format not recognized", since the file more likely
206 * is corrupt (possibly truncated). Stream decoder in liblzma
207 * uses LZMA_DATA_ERROR in this situation.
209 extern LZMA_API(lzma_ret) lzma_stream_footer_decode(
210 lzma_stream_flags *options, const uint8_t *in)
211 lzma_attr_warn_unused_result;
215 * \brief Compare two lzma_stream_flags structures
217 * backward_size values are compared only if both are not
220 * \return - LZMA_OK: Both are equal. If either had backward_size set
221 * to LZMA_VLI_UNKNOWN, backward_size values were not
222 * compared or validated.
223 * - LZMA_DATA_ERROR: The structures differ.
224 * - LZMA_OPTIONS_ERROR: version in either structure is greater
225 * than the maximum supported version (currently zero).
226 * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
229 extern LZMA_API(lzma_ret) lzma_stream_flags_compare(
230 const lzma_stream_flags *a, const lzma_stream_flags *b)