5 * \author Copyright (C) 1999-2008 Igor Pavlov
6 * \author Copyright (C) 2007-2008 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.
29 * \brief Compression level names for lzma_easy_* functions
31 * At the moment, all the compression levels support LZMA_SYNC_FLUSH.
32 * In future there may be levels that don't support LZMA_SYNC_FLUSH.
33 * However, the LZMA_SYNC_FLUSH support won't be removed from the
34 * existing compression levels.
36 * \note If liblzma is built without encoder support, or with some
37 * filters disabled, some of the compression levels may be
38 * unsupported. In that case, the initialization functions
39 * will return LZMA_HEADER_ERROR.
44 * No compression; the data is just wrapped into .lzma
48 LZMA_EASY_LZMA2_1 = 1,
50 * LZMA2 filter with fast compression (fast in terms of LZMA2).
51 * If you are interested in the exact options used, see
52 * lzma_preset_lzma[0]. Note that the exact options may
53 * change between liblzma versions.
55 * At the moment, the command line tool uses these settings
56 * when `lzma -1' is used. In future, the command line tool
57 * may default to some more complex way to determine the
58 * settings used e.g. the type of files being compressed.
60 * LZMA_EASY_LZMA_2 is equivalent to lzma_preset_lzma[1]
76 * \brief Default compression level
78 * Data Blocks contain the actual compressed data. It's not straightforward
79 * to recommend a default level, because in some cases keeping the resource
80 * usage relatively low is more important that getting the maximum
83 #define LZMA_EASY_DEFAULT LZMA_EASY_LZMA2_7
87 * \brief Calculates rough memory requirements of a compression level
89 * This function is a wrapper for lzma_memory_usage(), which is declared
92 * \return Approximate memory usage of the encoder with the given
93 * compression level in mebibytes (value * 1024 * 1024 bytes).
94 * On error (e.g. compression level is not supported),
95 * UINT32_MAX is returned.
97 extern uint64_t lzma_easy_memory_usage(lzma_easy_level level)
102 * \brief Initializes .lzma Stream encoder
104 * This function is intended for those who just want to use the basic features
105 * if liblzma (that is, most developers out there). Lots of assumptions are
106 * made, which are correct or at least good enough for most situations.
108 * \param strm Pointer to lzma_stream that is at least initialized
109 * with LZMA_STREAM_INIT.
110 * \param level Compression level to use. This selects a set of
111 * compression settings from a list of compression
114 * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to
116 * - LZMA_MEM_ERROR: Memory allocation failed. All memory
117 * previously allocated for *strm is now freed.
118 * - LZMA_HEADER_ERROR: The given compression level is not
119 * supported by this build of liblzma.
121 * If initialization succeeds, use lzma_code() to do the actual encoding.
122 * Valid values for `action' (the second argument of lzma_code()) are
123 * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
124 * there may be compression levels that don't support LZMA_SYNC_FLUSH.
126 extern lzma_ret lzma_easy_encoder(lzma_stream *strm, lzma_easy_level level)
127 lzma_attr_warn_unused_result;
131 * \brief Initializes .lzma Stream encoder
133 * \param strm Pointer to properly prepared lzma_stream
134 * \param filters Array of filters. This must be terminated with
135 * filters[n].id = LZMA_VLI_VALUE_UNKNOWN. There must
136 * be 1-4 filters, but there are restrictions on how
137 * multiple filters can be combined. FIXME Tell where
138 * to find more information.
139 * \param check Type of the integrity check to calculate from
142 * \return - LZMA_OK: Initialization was successful.
144 * - LZMA_HEADER_ERROR
147 extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
148 const lzma_filter *filters, lzma_check check)
149 lzma_attr_warn_unused_result;
153 * \brief Initializes LZMA_Alone (deprecated file format) encoder
155 * LZMA_Alone files have the suffix .lzma like the .lzma Stream files.
156 * LZMA_Alone format supports only one filter, the LZMA filter. There is
157 * no support for integrity checks like CRC32.
159 * Use this format if and only if you need to create files readable by
160 * legacy LZMA tools such as LZMA Utils 4.32.x.
162 * LZMA_Alone encoder doesn't support LZMA_SYNC_FLUSH or LZMA_FULL_FLUSH.
168 extern lzma_ret lzma_alone_encoder(
169 lzma_stream *strm, const lzma_options_lzma *options)
170 lzma_attr_warn_unused_result;
178 * This flag makes lzma_code() return LZMA_NO_CHECK if the input stream
179 * being decoded has no integrity check. Note that when used with
180 * lzma_auto_decoder(), all LZMA_Alone files will trigger LZMA_NO_CHECK
181 * if LZMA_TELL_NO_CHECK is used.
183 #define LZMA_TELL_NO_CHECK UINT32_C(0x01)
187 * This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input
188 * stream has an integrity check, but the type of the integrity check is not
189 * supported by this liblzma version or build. Such files can still be
190 * decoded, but the integrity check cannot be verified.
192 #define LZMA_TELL_UNSUPPORTED_CHECK UINT32_C(0x02)
196 * This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type
197 * of the integrity check is known. The type can then be got with
200 #define LZMA_TELL_ANY_CHECK UINT32_C(0x04)
204 * This flag enables decoding of concatenated files with file formats that
205 * allow concatenating compressed files as is. From the formats currently
206 * supported by liblzma, only the new .lzma format allows concatenated files.
207 * Concatenated files are not allowed with the LZMA_Alone format.
209 * This flag also affects the usage of the `action' argument for lzma_code().
210 * When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END
211 * unless LZMA_FINISH is used as `action'. Thus, the application has to set
212 * LZMA_FINISH in the same way as it does when encoding.
214 * If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH
215 * as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required.
217 #define LZMA_CONCATENATED UINT32_C(0x08)
221 * \brief Initializes decoder for .lzma Stream
223 * \param strm Pointer to properly prepared lzma_stream
224 * \param memlimit Rough memory usage limit as bytes
226 * \return - LZMA_OK: Initialization was successful.
227 * - LZMA_MEM_ERROR: Cannot allocate memory.
228 * - LZMA_HEADER_ERROR: Unsupported flags
230 extern lzma_ret lzma_stream_decoder(
231 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
232 lzma_attr_warn_unused_result;
236 * \brief Decode .lzma Streams and LZMA_Alone files with autodetection
238 * Autodetects between the .lzma Stream and LZMA_Alone formats, and
239 * calls lzma_stream_decoder() or lzma_alone_decoder() once the type
240 * of the file has been detected.
242 * \param strm Pointer to propertily prepared lzma_stream
243 * \param memlimit Rough memory usage limit as bytes
244 * \param flags Bitwise-or of flags, or zero for no flags.
246 * \return - LZMA_OK: Initialization was successful.
247 * - LZMA_MEM_ERROR: Cannot allocate memory.
248 * - LZMA_HEADER_ERROR: Unsupported flags
250 extern lzma_ret lzma_auto_decoder(
251 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
252 lzma_attr_warn_unused_result;
256 * \brief Initializes decoder for LZMA_Alone file
258 * The LZMA_Alone decoder supports LZMA_SYNC_FLUSH. FIXME
263 extern lzma_ret lzma_alone_decoder(lzma_stream *strm, uint64_t memlimit)
264 lzma_attr_warn_unused_result;