src/liblzma/api/lzma/easy.h

   1 /**
   2  * \file        lzma/easy.h
   3  * \brief       Easy to use encoder initialization
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 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  * \brief       Compression level names for lzma_easy_* functions
  26  *
  27  * At the moment, all the compression levels support LZMA_SYNC_FLUSH.
  28  * In future there may be levels that don't support LZMA_SYNC_FLUSH.
  29  * However, the LZMA_SYNC_FLUSH support won't be removed from the
  30  * existing compression levels.
  31  *
  32  * \note        If liblzma is built without encoder support, or with some
  33  *              filters disabled, some of the compression levels may be
  34  *              unsupported. In that case, the initialization functions
  35  *              will return LZMA_HEADER_ERROR.
  36  */
  37 typedef enum {
  38         LZMA_EASY_COPY,
  39                 /**<
  40                  * No compression; the data is just wrapped into .lzma
  41                  * container.
  42                  */
  43
  44         LZMA_EASY_LZMA_1,
  45                 /**<
  46                  * LZMA filter with fast compression (fast in terms of LZMA).
  47                  * If you are interested in the exact options used, see
  48                  * lzma_preset_lzma[0]. Note that the exact options may
  49                  * change between liblzma versions.
  50                  *
  51                  * At the moment, the command line tool uses these settings
  52                  * when `lzma -1' is used. In future, the command line tool
  53                  * may default to some more complex way to determine the
  54                  * settings used e.g. the type of files being compressed.
  55                  *
  56                  * LZMA_EASY_LZMA_2 is equivalent to lzma_preset_lzma[1]
  57                  * and so on.
  58                  */
  59
  60         LZMA_EASY_LZMA_2,
  61         LZMA_EASY_LZMA_3,
  62         LZMA_EASY_LZMA_4,
  63         LZMA_EASY_LZMA_5,
  64         LZMA_EASY_LZMA_6,
  65         LZMA_EASY_LZMA_7,
  66         LZMA_EASY_LZMA_8,
  67         LZMA_EASY_LZMA_9,
  68 } lzma_easy_level;
  69
  70
  71 /**
  72  * \brief       Default compression level for Data Blocks
  73  *
  74  * Data Blocks contain the actual compressed data. It's not straightforward
  75  * to recommend a default level, because in some cases keeping the resource
  76  * usage relatively low is more important that getting the maximum
  77  * compression ratio.
  78  */
  79 #define LZMA_EASY_DEFAULT LZMA_EASY_LZMA_7
  80
  81
  82 /**
  83  * \brief       Default compression level for Metadata Blocks
  84  *
  85  * Metadata Blocks are present only in Multi-Block Streams. Metadata Blocks
  86  * contain the Extra Records (if any) and some book-keeping data that is
  87  * used by decoders.
  88  */
  89 #define LZMA_EASY_METADATA_DEFAULT LZMA_EASY_LZMA_3
  90
  91
  92 /**
  93  * \brief       Calculates rough memory requirements of a compression level
  94  *
  95  * This function is a wrapper for lzma_memory_usage(), which is declared
  96  * in lzma/filter.h.
  97  *
  98  * \return      Approximate memory usage of the encoder with the given
  99  *              compression level in mebibytes (value * 1024 * 1024 bytes).
 100  *              On error (e.g. compression level is not supported),
 101  *              UINT32_MAX is returned.
 102  */
 103 extern uint32_t lzma_easy_memory_usage(lzma_easy_level level);
 104
 105
 106 /**
 107  * \brief       Initializes Single-Block .lzma Stream encoder
 108  *
 109  * This function is intended for those who just want to use the basic LZMA
 110  * features (that is, most developers out there). Lots of assumptions are
 111  * made, which are correct for most situations or at least good enough.
 112  *
 113  * \param       strm    Pointer to lzma_stream that is at least initialized
 114  *                      with LZMA_STREAM_INIT.
 115  * \param       level   Compression level to use. This selects a set of
 116  *                      compression settings from a list of compression
 117  *                      presets.
 118  *
 119  * \return      - LZMA_OK: Initialization succeeded. Use lzma_code() to
 120  *                encode your data.
 121  *              - LZMA_MEM_ERROR: Memory allocation failed. All memory
 122  *                previously allocated for *strm is now freed.
 123  *              - LZMA_HEADER_ERROR: The given compression level is not
 124  *                supported by this build of liblzma.
 125  *
 126  * If initialization succeeds, use lzma_code() to do the actual encoding.
 127  * Valid values for `action' (the second argument of lzma_code()) are
 128  * LZMA_RUN, LZMA_SYNC_FLUSH, and LZMA_FINISH. In future, there may be
 129  * compression levels that don't support LZMA_SYNC_FLUSH.
 130  */
 131 extern lzma_ret lzma_easy_encoder_single(
 132                 lzma_stream *strm, lzma_easy_level level);
 133
 134
 135 /**
 136  * \brief       Initializes Multi-Block .lzma Stream encoder
 137  *
 138  * If you want to be able to store Extra Records or want to be able to use
 139  * LZMA_FULL_FLUSH, you need to create a Multi-Block Stream.
 140  *
 141  * \param       strm    Pointer to lzma_stream that is at least initialized
 142  *                      with LZMA_STREAM_INIT.
 143  * \param       level   Compression level to use for the data being encoded.
 144  * \param       metadata_level
 145  *                      Compression level to use for Metadata Blocks.
 146  *                      Metadata Blocks contain the Extra Records (if any)
 147  *                      and some book-keeping data that is used by decoders.
 148  * \param       header  Pointer to a list of Extra Records to be stored to
 149  *                      the Header Metadata Block. Set this to NULL to omit
 150  *                      Header Metadata Block completely. The list must be
 151  *                      kept available until the encoding has finished.
 152  * \param       footer  Pointer to a list of Extra Records to be stored to
 153  *                      the Footer Metadata Block. Set this to NULL if you
 154  *                      don't want to store any Extra Records (the Footer
 155  *                      Metadata Block will still be written for other
 156  *                      reasons.) The list must be kept available until
 157  *                      the encoding has finished.
 158  *
 159  * \return      - LZMA_OK: Initialization succeeded. Use lzma_code() to
 160  *                encode your data.
 161  *              - LZMA_MEM_ERROR: Memory allocation failed. All memory
 162  *                previously allocated for *strm is now freed.
 163  *              - LZMA_HEADER_ERROR: The given compression level is not
 164  *                supported by this build of liblzma.
 165  *
 166  * If initialization succeeds, use lzma_code() to do the actual encoding.
 167  * Valid values for `action' (the second argument of lzma_code()) are
 168  * LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
 169  * there may be compression levels that don't support LZMA_SYNC_FLUSH.
 170  * LZMA_FULL_FLUSH will always work with all compression levels.
 171  */
 172 extern lzma_ret lzma_easy_encoder_multi(lzma_stream *strm,
 173                 lzma_easy_level level, lzma_easy_level metadata_level,
 174                 const lzma_extra *header, const lzma_extra *footer);