2 * \file lzma/stream_flags.h
3 * \brief .lzma 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 .lzma 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 * Backward Size must be a multiple of four bytes. In this Stream
59 * format version Backward Size is the size of the Index field.
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.
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.
71 lzma_vli backward_size;
72 # define LZMA_BACKWARD_SIZE_MIN 4
73 # define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34)
76 * Type of the Check calculated from uncompressed data
81 * Reserved space to allow possible future extensions without
82 * breaking the ABI. You should not touch these, because the
83 * names of these variables may change.
85 * (We will never be able to use all of these since Stream Flags
86 * is just two bytes plus Backward Size of four bytes. But it's
87 * nice to have the proper types when they are needed.)
89 lzma_reserved_enum reserved_enum1;
90 lzma_reserved_enum reserved_enum2;
91 lzma_reserved_enum reserved_enum3;
92 lzma_reserved_enum reserved_enum4;
93 lzma_reserved_enum reserved_enum5;
94 lzma_reserved_enum reserved_enum6;
95 lzma_bool reserved_bool1;
96 lzma_bool reserved_bool2;
97 lzma_bool reserved_bool3;
98 lzma_bool reserved_bool4;
99 lzma_bool reserved_bool5;
100 lzma_bool reserved_bool6;
101 lzma_bool reserved_bool7;
102 lzma_bool reserved_bool8;
103 uint32_t reserved_int1;
104 uint32_t reserved_int2;
105 uint32_t reserved_int3;
106 uint32_t reserved_int4;
112 * \brief Encode Stream Header
114 * \param out Beginning of the output buffer of
115 * LZMA_STREAM_HEADER_SIZE bytes.
116 * \param options Stream Header options to be encoded.
117 * options->index_size is ignored and doesn't
118 * need to be initialized.
120 * \return - LZMA_OK: Encoding was successful.
121 * - LZMA_OPTIONS_ERROR: options->version is not supported by
122 * this liblzma version.
123 * - LZMA_PROG_ERROR: Invalid options.
125 extern lzma_ret lzma_stream_header_encode(
126 const lzma_stream_flags *options, uint8_t *out)
127 lzma_attr_warn_unused_result;
131 * \brief Encode Stream Footer
133 * \param out Beginning of the output buffer of
134 * LZMA_STREAM_HEADER_SIZE bytes.
135 * \param options Stream Footer options to be encoded.
137 * \return - LZMA_OK: Encoding was successful.
138 * - LZMA_OPTIONS_ERROR: options->version is not supported by
139 * this liblzma version.
140 * - LZMA_PROG_ERROR: Invalid options.
142 extern lzma_ret lzma_stream_footer_encode(
143 const lzma_stream_flags *options, uint8_t *out)
144 lzma_attr_warn_unused_result;
148 * \brief Decode Stream Header
150 * \param options Stream Header options to be encoded.
151 * \param in Beginning of the input buffer of
152 * LZMA_STREAM_HEADER_SIZE bytes.
154 * options->index_size is always set to LZMA_VLI_UNKNOWN. This is to
155 * help comparing Stream Flags from Stream Header and Stream Footer with
156 * lzma_stream_flags_compare().
158 * \return - LZMA_OK: Decoding was successful.
159 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
160 * buffer cannot be Stream Header.
161 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header
163 * - LZMA_OPTIONS_ERROR: Unsupported options are present
166 extern lzma_ret lzma_stream_header_decode(
167 lzma_stream_flags *options, const uint8_t *in)
168 lzma_attr_warn_unused_result;
172 * \brief Decode Stream Footer
174 * \param options Stream Header options to be encoded.
175 * \param in Beginning of the input buffer of
176 * LZMA_STREAM_HEADER_SIZE bytes.
178 * \return - LZMA_OK: Decoding was successful.
179 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given
180 * buffer cannot be Stream Footer.
181 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the footer
183 * - LZMA_OPTIONS_ERROR: Unsupported options are present
186 * \note If Stream Header was already decoded successfully, but
187 * decoding Stream Footer returns LZMA_FORMAT_ERROR, the
188 * application should probably report some other error message
189 * than "unsupported file format", since the file more likely is
190 * corrupt (possibly truncated). Stream decoder in liblzma uses
191 * LZMA_DATA_ERROR in this situation.
193 extern lzma_ret lzma_stream_footer_decode(
194 lzma_stream_flags *options, const uint8_t *in)
195 lzma_attr_warn_unused_result;
199 * \brief Compare two lzma_stream_flags structures
201 * backward_size values are compared only if both are not
204 * \return - LZMA_OK: Both are equal. If either had backward_size set
205 * to LZMA_VLI_UNKNOWN, backward_size values were not
206 * compared or validated.
207 * - LZMA_DATA_ERROR: The structures differ.
208 * - LZMA_OPTIONS_ERROR: version in either structure is greater
209 * than the maximum supported version (currently zero).
210 * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or
213 extern lzma_ret lzma_stream_flags_compare(
214 const lzma_stream_flags *a, const lzma_stream_flags *b)