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_options_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_available_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_available_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  * \param       is_encoder  Set to true when calculating memory requirements
  91  *                          of an encoder; false for decoder.
  92  *
  93  * \return      Number of mebibytes (MiB i.e. 2^20) required for the given
  94  *              encoder or decoder filter chain.
  95  *
  96  * \note        If calculating memory requirements of encoder, lzma_init() or
  97  *              lzma_init_encoder() must have been called earlier. Similarly,
  98  *              if calculating memory requirements of decoder, lzma_init() or
  99  *              lzma_init_decoder() must have been called earlier.
 100  */
 101 extern uint32_t lzma_memory_usage(
 102                 const lzma_options_filter *filters, lzma_bool is_encoder);
 103
 104
 105 /**
 106  * \brief       Calculates encoded size of a Filter Flags field
 107  *
 108  * Knowing the size of Filter Flags is useful to know when allocating
 109  * memory to hold the encoded Filter Flags.
 110  *
 111  * \param       size    Pointer to integer to hold the calculated size
 112  * \param       options Filter ID and associated options whose encoded
 113  *                      size is to be calculted
 114  *
 115  * \return      - LZMA_OK: *size set successfully. Note that this doesn't
 116  *                guarantee that options->options is valid, thus
 117  *                lzma_filter_flags_encode() may still fail.
 118  *              - LZMA_HEADER_ERROR: Unknown Filter ID or unsupported options.
 119  *              - LZMA_PROG_ERROR: Invalid options
 120  *
 121  * \note        If you need to calculate size of List of Filter Flags,
 122  *              you need to loop over every lzma_options_filter entry.
 123  */
 124 extern lzma_ret lzma_filter_flags_size(
 125                 uint32_t *size, const lzma_options_filter *options);
 126
 127
 128 /**
 129  * \brief       Encodes Filter Flags into given buffer
 130  *
 131  * In contrast to some functions, this doesn't allocate the needed buffer.
 132  * This is due to how this function is used internally by liblzma.
 133  *
 134  * \param       out         Beginning of the output buffer
 135  * \param       out_pos     out[*out_pos] is the next write position. This
 136  *                          is updated by the encoder.
 137  * \param       out_size    out[out_size] is the first byte to not write.
 138  * \param       options     Filter options to be encoded
 139  *
 140  * \return      - LZMA_OK: Encoding was successful.
 141  *              - LZMA_HEADER_ERROR: Invalid or unsupported options.
 142  *              - LZMA_PROG_ERROR: Invalid options or not enough output
 143  *                buffer space (you should have checked it with
 144  *                lzma_filter_flags_size()).
 145  */
 146 extern lzma_ret lzma_filter_flags_encode(uint8_t *out, size_t *out_pos,
 147                 size_t out_size, const lzma_options_filter *options);
 148
 149
 150 /**
 151  * \brief       Initializes Filter Flags decoder
 152  *
 153  * The decoded result is stored into *options. options->options is
 154  * initialized but the old value is NOT free()d.
 155  *
 156  * Because the results of this decoder are placed into *options,
 157  * strm->next_in, strm->avail_in, and strm->total_in are not used
 158  * when calling lzma_code(). The only valid action for lzma_code()
 159  * is LZMA_RUN
 160  *
 161  * \return      - LZMA_OK
 162  *              - LZMA_MEM_ERROR
 163  *              - LZMA_PROG_ERROR
 164  */
 165 extern lzma_ret lzma_filter_flags_decoder(
 166                 lzma_stream *strm, lzma_options_filter *options);