src/liblzma/api/lzma/filter.h

   1 /**
   2  * \file        lzma/filter.h
   3  * \brief       Common filter related types
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 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       Filter options
  26  *
  27  * This structure is used to pass Filter ID and a pointer filter's options
  28  * to liblzma.
  29  */
  30 typedef struct {
  31         /**
  32          * \brief       Filter ID
  33          *
  34          * Use constants whose name begin with `LZMA_FILTER_' to specify
  35          * different filters. In an array of lzma_option_filter structures,
  36          * use LZMA_VLI_VALUE_UNKNOWN to indicate end of filters.
  37          */
  38         lzma_vli id;
  39
  40         /**
  41          * \brief       Pointer to filter-specific options structure
  42          *
  43          * If the filter doesn't need options, set this to NULL. If id is
  44          * set to LZMA_VLI_VALUE_UNKNOWN, options is ignored, and thus
  45          * doesn't need be initialized.
  46          *
  47          * Some filters support changing the options in the middle of
  48          * the encoding process. These filters store the pointer of the
  49          * options structure and communicate with the application via
  50          * modifications of the options structure.
  51          */
  52         void *options;
  53
  54 } lzma_filter;
  55
  56
  57 /**
  58  * \brief       Filters available for encoding
  59  *
  60  * Pointer to an array containing the list of available Filter IDs that
  61  * can be used for encoding. The last element is LZMA_VLI_VALUE_UNKNOWN.
  62  *
  63  * If lzma_available_filter_encoders[0] == LZMA_VLI_VALUE_UNKNOWN, the
  64  * encoder components haven't been built at all. This means that the
  65  * encoding-specific functions are probably missing from the library
  66  * API/ABI completely.
  67  */
  68 extern const lzma_vli *const lzma_filter_encoders;
  69
  70
  71 /**
  72  * \brief       Filters available for decoding
  73  *
  74  * Pointer to an array containing the list of available Filter IDs that
  75  * can be used for decoding. The last element is LZMA_VLI_VALUE_UNKNOWN.
  76  *
  77  * If lzma_available_filter_decoders[0] == LZMA_VLI_VALUE_UNKNOWN, the
  78  * decoder components haven't been built at all. This means that the
  79  * decoding-specific functions are probably missing from the library
  80  * API/ABI completely.
  81  */
  82 extern const lzma_vli *const lzma_filter_decoders;
  83
  84
  85 /**
  86  * \brief       Calculate rough memory requirements for given filter chain
  87  *
  88  * \param       filters     Array of filters terminated with
  89  *                          .id == LZMA_VLI_VALUE_UNKNOWN.
  90  *
  91  * \return      Number of mebibytes (MiB i.e. 2^20) required for the given
  92  *              encoder or decoder filter chain.
  93  *
  94  * \note        If calculating memory requirements of encoder, lzma_init() or
  95  *              lzma_init_encoder() must have been called earlier. Similarly,
  96  *              if calculating memory requirements of decoder, lzma_init() or
  97  *              lzma_init_decoder() must have been called earlier.
  98  */
  99 // extern uint32_t lzma_memory_usage(
 100 //              const lzma_filter *filters, lzma_bool is_encoder);
 101
 102 extern uint64_t lzma_memusage_encoder(const lzma_filter *filters)
 103                 lzma_attr_pure;
 104
 105 extern uint64_t lzma_memusage_decoder(const lzma_filter *filters)
 106                 lzma_attr_pure;
 107
 108
 109 /**
 110  * \brief       Initializes raw encoder
 111  *
 112  * This function may be useful when implementing custom file formats.
 113  *
 114  * \param       strm    Pointer to properly prepared lzma_stream
 115  * \param       options Array of lzma_filter structures.
 116  *                      The end of the array must be marked with
 117  *                      .id = LZMA_VLI_VALUE_UNKNOWN. The minimum
 118  *                      number of filters is one and the maximum is four.
 119  *
 120  * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
 121  * filter chain supports it), or LZMA_FINISH.
 122  *
 123  * \return      - LZMA_OK
 124  *              - LZMA_MEM_ERROR
 125  *              - LZMA_HEADER_ERROR
 126  *              - LZMA_PROG_ERROR
 127  */
 128 extern lzma_ret lzma_raw_encoder(
 129                 lzma_stream *strm, const lzma_filter *options)
 130                 lzma_attr_warn_unused_result;
 131
 132
 133 /**
 134  * \brief       Initializes raw decoder
 135  *
 136  * The initialization of raw decoder goes similarly to raw encoder.
 137  *
 138  * The `action' with lzma_code() can be LZMA_RUN or LZMA_SYNC_FLUSH.
 139  *
 140  * \return      - LZMA_OK
 141  *              - LZMA_MEM_ERROR
 142  *              - LZMA_HEADER_ERROR
 143  *              - LZMA_PROG_ERROR
 144  */
 145 extern lzma_ret lzma_raw_decoder(
 146                 lzma_stream *strm, const lzma_filter *options)
 147                 lzma_attr_warn_unused_result;
 148
 149
 150 /**
 151  * \brief       Calculates encoded size of a Filter Flags field
 152  *
 153  * Knowing the size of Filter Flags is useful to know when allocating
 154  * memory to hold the encoded Filter Flags.
 155  *
 156  * \param       size    Pointer to integer to hold the calculated size
 157  * \param       options Filter ID and associated options whose encoded
 158  *                      size is to be calculted
 159  *
 160  * \return      - LZMA_OK: *size set successfully. Note that this doesn't
 161  *                guarantee that options->options is valid, thus
 162  *                lzma_filter_flags_encode() may still fail.
 163  *              - LZMA_HEADER_ERROR: Unknown Filter ID or unsupported options.
 164  *              - LZMA_PROG_ERROR: Invalid options
 165  *
 166  * \note        If you need to calculate size of List of Filter Flags,
 167  *              you need to loop over every lzma_filter entry.
 168  */
 169 extern lzma_ret lzma_filter_flags_size(
 170                 uint32_t *size, const lzma_filter *options)
 171                 lzma_attr_warn_unused_result;
 172
 173
 174 /**
 175  * \brief       Encodes Filter Flags into given buffer
 176  *
 177  * In contrast to some functions, this doesn't allocate the needed buffer.
 178  * This is due to how this function is used internally by liblzma.
 179  *
 180  * \param       out         Beginning of the output buffer
 181  * \param       out_pos     out[*out_pos] is the next write position. This
 182  *                          is updated by the encoder.
 183  * \param       out_size    out[out_size] is the first byte to not write.
 184  * \param       options     Filter options to be encoded
 185  *
 186  * \return      - LZMA_OK: Encoding was successful.
 187  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 188  *              - LZMA_PROG_ERROR: Invalid options or not enough output
 189  *                buffer space (you should have checked it with
 190  *                lzma_filter_flags_size()).
 191  */
 192 extern lzma_ret lzma_filter_flags_encode(const lzma_filter *options,
 193                 uint8_t *out, size_t *out_pos, size_t out_size)
 194                 lzma_attr_warn_unused_result;
 195
 196
 197 /**
 198  * \brief       Initializes Filter Flags decoder
 199  *
 200  * The decoded result is stored into *options. options->options is
 201  * initialized but the old value is NOT free()d.
 202  *
 203  * Because the results of this decoder are placed into *options,
 204  * strm->next_in, strm->avail_in, and strm->total_in are not used
 205  * when calling lzma_code(). The only valid action for lzma_code()
 206  * is LZMA_RUN
 207  *
 208  * \return      - LZMA_OK
 209  *              - LZMA_MEM_ERROR
 210  *              - LZMA_PROG_ERROR
 211  */
 212 extern lzma_ret lzma_filter_flags_decode(
 213                 lzma_filter *options, lzma_allocator *allocator,
 214                 const uint8_t *in, size_t *in_pos, size_t in_size)
 215                 lzma_attr_warn_unused_result;