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