source/include/lzmadec.h

0001 /******************************************************************************
0002
0003     LZMA decoder library with a zlib like API
0004
0005         * WARNING WARNING WARNING WARNING WARNING WARNING *
0006         *                                                 *
0007         * This library hasn't been maintained since 2005. *
0008         * This will be replaced by liblzma once it is     *
0009         * finished. liblzma will provide all the features *
0010         * of liblzmadec and a lot more.                   *
0011         *                                                 *
0012         * WARNING WARNING WARNING WARNING WARNING WARNING *
0013
0014     Copyright (C) 1999-2005 Igor Pavlov (http://7-zip.org/)
0015     Copyright (C) 2005 Lasse Collin <lasse.collin@tukaani.org>
0016     Based on zlib.h and bzlib.h.
0017
0018     This library is free software; you can redistribute it and/or
0019     modify it under the terms of the GNU Lesser General Public
0020     License as published by the Free Software Foundation; either
0021     version 2.1 of the License, or (at your option) any later version.
0022
0023     This library is distributed in the hope that it will be useful,
0024     but WITHOUT ANY WARRANTY; without even the implied warranty of
0025     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0026     Lesser General Public License for more details.
0027
0028 ******************************************************************************/
0029
0030
0031 /*************************
0032   WARNING WARNING WARNING
0033   Comments about return
0034   codes etc. are not up
0035   to date.
0036  *************************/
0037
0038
0039 #ifndef LZMADEC_H
0040 #define LZMADEC_H
0041
0042 #ifdef __cplusplus
0043 extern "C" {
0044 #endif
0045
0046 /**********
0047   Includes
0048  **********/
0049
0050 #include <sys/types.h>
0051 #include <inttypes.h>
0052
0053 /* Define LZMADEC_NO_STDIO to not include stdio.h and lzmadec_FILE functions. */
0054 #ifndef LZMADEC_NO_STDIO
0055 #include <stdio.h>
0056 #endif
0057
0058
0059 /*******************
0060   Defines/Constants
0061  *******************/
0062
0063 /* Size in bytes of the smallest possible LZMA encoded file */
0064 #define LZMADEC_MINIMUM_SIZE 18
0065
0066 /* Return values */
0067 #define LZMADEC_OK                0
0068 #define LZMADEC_STREAM_END        1
0069 #define LZMADEC_HEADER_ERROR    (-2)
0070 #define LZMADEC_DATA_ERROR      (-3)
0071 #define LZMADEC_MEM_ERROR       (-4)
0072 #define LZMADEC_BUF_ERROR       (-5)
0073 #define LZMADEC_SEQUENCE_ERROR  (-6)
0074 /*
0075    LZMADEC_OK
0076    Operation succeeded or some progress has been made.
0077
0078    LZMADEC_STREAM_END
0079    The end of the encoded data has been reached. Note that this is
0080    a possible return value even when finish_decoding == LZMADEC_RUN.
0081
0082    LZMADEC_DATA_ERROR
0083    Something wrong with the input data.
0084
0085    LZMADEC_MEM_ERROR
0086    The memory allocation function returned a NULL pointer. The same
0087    function can be called again with the same arguments to try again.
0088
0089    LZMADEC_BUF_ERROR
0090    You should provide more input in next_in and set avail_in accordingly.
0091    The first call to lzmadec_decode() must provide at least 18 bytes of
0092    input data. Subsequent calls can any amount of data (or no data at all).
0093    Note that LZMADEC_BUF_ERROR is not fatal and decoding can continue by
0094    supplying more input data.
0095 */
0096
0097
0098 /**********
0099   typedefs
0100  **********/
0101
0102 typedef struct {
0103     uint8_t *next_in;
0104     size_t avail_in;
0105     uint_fast64_t total_in;
0106
0107     uint8_t *next_out;
0108     size_t avail_out;
0109     uint_fast64_t total_out;
0110
0111     void *state; /* Internal state, not visible outside the library */
0112
0113     void *(*lzma_alloc)(void *, size_t, size_t);
0114     void (*lzma_free)(void *, void *);
0115     void *opaque;
0116 } lzmadec_stream;
0117
0118 typedef struct {
0119     uint_fast64_t uncompressed_size;
0120     uint_fast32_t dictionary_size;
0121     uint_fast32_t internal_data_size;
0122     uint_fast8_t is_streamed;
0123     uint_fast8_t pb;
0124     uint_fast8_t lp;
0125     uint_fast8_t lc;
0126 } lzmadec_info;
0127
0128 #ifndef LZMADEC_NO_STDIO
0129 typedef void lzmadec_FILE;
0130 #endif
0131
0132
0133 /*********************
0134   Single call decoding
0135  *********************/
0136
0137 extern int_fast8_t lzmadec_buffer (
0138     uint8_t *dest, size_t *dest_len,
0139     uint8_t *source, const size_t source_len);
0140 /*
0141     Decode the data from source buffer to destination buffer with
0142     a single pass.
0143
0144     Return values:
0145         LZMADEC_OK              Decoding successful
0146         LZMADEC_HEADER_ERROR    Invalid header
0147         LZMADEC_MEM_ERROR       Not enough memory
0148         LZMADEC_DATA_ERROR      Corrupted source data
0149         LZMADEC_BUF_ERROR       Destination buffer too small
0150
0151     Equivalent in zlib: uncompress()
0152 */
0153
0154
0155 /*********************
0156   Multi call decoding
0157  *********************/
0158
0159 extern int_fast8_t lzmadec_init (lzmadec_stream *strm);
0160 /*
0161     Initialize the decoder.
0162
0163     Return values:
0164         LZMADEC_OK
0165         LZMADEC_HEADER_ERROR
0166         LZMADEC_MEM_ERROR
0167
0168     Equivalent in zlib: inflateInit()
0169 */
0170
0171 extern int_fast8_t
0172 lzmadec_decode (lzmadec_stream *strm, const int_fast8_t finish_decoding);
0173 /*
0174     The finish_decoding flag
0175
0176     In contrast to zlib and bzlib, liblzmadec can detect the end of the
0177     compressed stream only with streamed LZMA data. Non-streamed data
0178     does not contain any end of stream marker and thus needs the
0179     finish_decoding flag to be set to decode the last bytes of the data.
0180
0181     When the finish_decoding is zero,
0182     This is a sign to the decoder that even if avail_in == 0 happened to
0183     be true, there can still be more input data not passed to the library
0184     yet. It is safe to call lzmadec_decode with LZMADEC_RUN even if all
0185     the data has been passed to the library already; in that case there
0186     there will usually be bytes left in the internal output buffer.
0187
0188     Set the finish_decoding to non-zero to sign the decoder that all
0189     the input has been given to it via next_in buffer. Once called with
0190     non-zero finish_decoding flag, it should not be unset or an error
0191     will be returned.
0192
0193     If you can assure that (avail_in > 0) on every lzmadec_decode() call
0194     before all the data has been passed to the decoder library, the
0195     simplest way is to use (strm.avail_in == 0) as the finish_decoding
0196     value.
0197
0198     Return values:
0199         LZMADEC_OK
0200         LZMADEC_STREAM_END
0201         LZMADEC_DATA_ERROR
0202         LZMADEC_HEADER_ERROR (only right after initialization)
0203         LZMADEC_MEM_ERROR (only right after initialization)
0204
0205     Equivalent in zlib: inflate()
0206 */
0207
0208 int_fast8_t lzmadec_end (lzmadec_stream *strm);
0209 /*
0210     Return values:
0211         LZMADEC_OK
0212         LZMADEC_STREAM_ERROR FIXME
0213
0214     Equivalent in zlib: inflateEnd()
0215 */
0216
0217
0218 /*************
0219   Information
0220  *************/
0221
0222 extern int_fast8_t lzmadec_buffer_info (
0223         lzmadec_info *info, const uint8_t *buffer, const size_t len);
0224 /*
0225     Parse the header of a LZMA stream. The header size is
0226     13 bytes; make sure there is at least 13 bytes available
0227     in the buffer. Information about parsed header will be stored
0228     to *info.
0229
0230     Most common uses for this function are checking
0231       - the uncompressed size of the file (if availabe)
0232       - how much RAM is needed to decompress the data.
0233
0234         uncompressed_size   Uncompressed size of the data as bytes
0235
0236         dictionary_size     Dictionary size as bytes; depends only on
0237                             settings used when compressing the data.
0238
0239         internal_data_size  The amount of memory needed by liblzmadec
0240                             to decode the data excluding the dictionary
0241                             size. Note that this value depends not only
0242                             about the used compression settings but
0243                             also the implementation and/or compile time
0244                             settings; specifically sizeof(uint_fast16_t).
0245
0246         is_streamed         Zero if the data is non-streamed LZMA, and
0247                             non-zero for streamed. This flag is set
0248                             simply by checking the size field.
0249
0250         pb                  Number of pos bits; can be from 0 to 4.
0251
0252         lp                  Number of literal pos bits; from 0 to 4.
0253
0254         lc                  Number of literal context bits; from 0 to 8.
0255
0256     To know how much memory is needed to compress a specific stream,
0257     add up dictionary_size and internal_data_size. Note that if the
0258     dictionary is extremely huge, the result might not fit in
0259     uint_fast32_t. ;-)
0260
0261     WARNING: LZMA streams have no magic first bytes. All data
0262     that has 0x00 - 0xE1 as the first byte in the buffer will
0263     return LZMADEC_OK.
0264
0265     Return values:
0266         LZMADEC_OK              All OK, the information was stored to *info.
0267         LZMADEC_BUF_ERROR       len is too small.
0268         LZMADEC_HEADER_ERROR    Invalid header data.
0269 */
0270
0271 extern const uint8_t *lzmadec_version (void);
0272 /*
0273     Return a pointer to a statically allocated string containing the version
0274     number of the liblzmadec. The version number format is x.yy.z where
0275     x.yy is the version of LZMA SDK from http://7-zip.org/sdk.html, and x
0276     is
0277
0278     Equivalent in zlib: zlibVersion()
0279 */
0280
0281
0282 /**********
0283   File I/O
0284  **********/
0285 #ifndef LZMADEC_NO_STDIO
0286
0287 extern lzmadec_FILE *lzmadec_open (const char *path);
0288 extern lzmadec_FILE *lzmadec_dopen (int fd);
0289 extern ssize_t lzmadec_read (lzmadec_FILE *file, uint8_t *buf, size_t len);
0290 extern uint8_t *lzmadec_gets (lzmadec_FILE *file, uint8_t *buf, size_t len);
0291 extern int lzmadec_getc (lzmadec_FILE *file);
0292 extern int_fast8_t lzmadec_seek (lzmadec_FILE *file, off_t offset, int whence);
0293 extern off_t lzmadec_tell (lzmadec_FILE *file);
0294 extern int_fast8_t lzmadec_rewind (lzmadec_FILE *file);
0295 extern int_fast8_t lzmadec_eof (lzmadec_FILE *file);
0296 extern int_fast8_t lzmadec_close (lzmadec_FILE *file);
0297 /* extern const char *lzmadec_error (lzmadec_FILE *file, int *errnum) */
0298
0299 #endif /* ifndef LZMADEC_NO_STDIO */
0300
0301 #ifdef __cplusplus
0302 }
0303 #endif
0304
0305 #endif /* ifndef LZMADEC_H */