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

source code of include/lzma/stream_flags.h