src/liblzma/api/lzma/container.h

   1 /**
   2  * \file        lzma/container.h
   3  * \brief       File formats
   4  *
   5  * \author      Copyright (C) 1999-2008 Igor Pavlov
   6  * \author      Copyright (C) 2007-2008 Lasse Collin
   7  *
   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.
  12  *
  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.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /************
  25  * Encoding *
  26  ************/
  27
  28 /**
  29  * \brief       Compression level names for lzma_easy_* functions
  30  *
  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.
  35  *
  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_OPTIONS_ERROR.
  40  */
  41 typedef enum {
  42         LZMA_EASY_COPY      = 0,
  43                 /**<
  44                  * No compression; the data is just wrapped into .lzma
  45                  * container.
  46                  */
  47
  48         LZMA_EASY_LZMA2_1   = 1,
  49                 /**<
  50                  * LZMA2 filter with fast compression (fast in terms of LZMA2).
  51                  * If you are interested in the exact options used, see
  52                  * lzma_lzma_preset(1). Note that the exact options may
  53                  * change between liblzma versions.
  54                  *
  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.
  59                  *
  60                  * LZMA_EASY_LZMA2_2 is equivalent to lzma_lzma_preset(2)
  61                  * and so on.
  62                  */
  63
  64         LZMA_EASY_LZMA2_2    = 2,
  65         LZMA_EASY_LZMA2_3    = 3,
  66         LZMA_EASY_LZMA2_4    = 4,
  67         LZMA_EASY_LZMA2_5    = 5,
  68         LZMA_EASY_LZMA2_6    = 6,
  69         LZMA_EASY_LZMA2_7    = 7,
  70         LZMA_EASY_LZMA2_8    = 8,
  71         LZMA_EASY_LZMA2_9    = 9,
  72 } lzma_easy_level;
  73
  74
  75 /**
  76  * \brief       Default compression level
  77  *
  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
  81  * compression ratio.
  82  */
  83 #define LZMA_EASY_DEFAULT LZMA_EASY_LZMA2_7
  84
  85
  86 /**
  87  * \brief       Calculates rough memory requirements of a compression level
  88  *
  89  * This function is a wrapper for lzma_memory_usage(), which is declared
  90  * in filter.h.
  91  *
  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.
  96  */
  97 extern uint64_t lzma_easy_memory_usage(lzma_easy_level level)
  98                 lzma_attr_pure;
  99
 100
 101 /**
 102  * \brief       Initializes .lzma Stream encoder
 103  *
 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.
 107  *
 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
 112  *                      presets.
 113  *
 114  * \return      - LZMA_OK: Initialization succeeded. Use lzma_code() to
 115  *                encode your data.
 116  *              - LZMA_MEM_ERROR: Memory allocation failed. All memory
 117  *                previously allocated for *strm is now freed.
 118  *              - LZMA_OPTIONS_ERROR: The given compression level is not
 119  *                supported by this build of liblzma.
 120  *
 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.
 125  */
 126 extern lzma_ret lzma_easy_encoder(lzma_stream *strm, lzma_easy_level level)
 127                 lzma_attr_warn_unused_result;
 128
 129
 130 /**
 131  * \brief       Initializes .lzma Stream encoder
 132  *
 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_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
 140  *                      uncompressed data.
 141  *
 142  * \return      - LZMA_OK: Initialization was successful.
 143  *              - LZMA_MEM_ERROR
 144  *              - LZMA_OPTIONS_ERROR
 145  *              - LZMA_PROG_ERROR
 146  */
 147 extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
 148                 const lzma_filter *filters, lzma_check check)
 149                 lzma_attr_warn_unused_result;
 150
 151
 152 /**
 153  * \brief       Initializes LZMA_Alone (deprecated file format) encoder
 154  *
 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.
 158  *
 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.
 161  *
 162  * LZMA_Alone encoder doesn't support LZMA_SYNC_FLUSH or LZMA_FULL_FLUSH.
 163  *
 164  * \return      - LZMA_OK
 165  *              - LZMA_MEM_ERROR
 166  *              - LZMA_PROG_ERROR
 167  */
 168 extern lzma_ret lzma_alone_encoder(
 169                 lzma_stream *strm, const lzma_options_lzma *options)
 170                 lzma_attr_warn_unused_result;
 171
 172
 173 /************
 174  * Decoding *
 175  ************/
 176
 177 /**
 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.
 182  */
 183 #define LZMA_TELL_NO_CHECK              UINT32_C(0x01)
 184
 185
 186 /**
 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.
 191  */
 192 #define LZMA_TELL_UNSUPPORTED_CHECK     UINT32_C(0x02)
 193
 194
 195 /**
 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
 198  * lzma_get_check().
 199  */
 200 #define LZMA_TELL_ANY_CHECK             UINT32_C(0x04)
 201
 202
 203 /**
 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.
 208  *
 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.
 213  *
 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.
 216  */
 217 #define LZMA_CONCATENATED               UINT32_C(0x08)
 218
 219
 220 /**
 221  * \brief       Initializes decoder for .lzma Stream
 222  *
 223  * \param       strm        Pointer to properly prepared lzma_stream
 224  * \param       memlimit    Rough memory usage limit as bytes
 225  *
 226  * \return      - LZMA_OK: Initialization was successful.
 227  *              - LZMA_MEM_ERROR: Cannot allocate memory.
 228  *              - LZMA_OPTIONS_ERROR: Unsupported flags
 229  */
 230 extern lzma_ret lzma_stream_decoder(
 231                 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
 232                 lzma_attr_warn_unused_result;
 233
 234
 235 /**
 236  * \brief       Decode .lzma Streams and LZMA_Alone files with autodetection
 237  *
 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.
 241  *
 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.
 245  *
 246  * \return      - LZMA_OK: Initialization was successful.
 247  *              - LZMA_MEM_ERROR: Cannot allocate memory.
 248  *              - LZMA_OPTIONS_ERROR: Unsupported flags
 249  */
 250 extern lzma_ret lzma_auto_decoder(
 251                 lzma_stream *strm, uint64_t memlimit, uint32_t flags)
 252                 lzma_attr_warn_unused_result;
 253
 254
 255 /**
 256  * \brief       Initializes decoder for LZMA_Alone file
 257  *
 258  * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
 259  * There is no need to use LZMA_FINISH, but allowing it may simplify
 260  * certain types of applications.
 261  *
 262  * \return      - LZMA_OK
 263  *              - LZMA_MEM_ERROR
 264  */
 265 extern lzma_ret lzma_alone_decoder(lzma_stream *strm, uint64_t memlimit)
 266                 lzma_attr_warn_unused_result;