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