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_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_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       Test if the given Filter ID is supported for encoding
  59  *
  60  * Returns true if the give Filter ID  is supported for encoding by this
  61  * liblzma build. Otherwise false is returned.
  62  *
  63  * There is no way to list which filters are available in this particular
  64  * liblzma version and build. It would be useless, because the application
  65  * couldn't know what kind of options the filter would need.
  66  */
  67 extern lzma_bool lzma_filter_encoder_is_supported(lzma_vli id);
  68
  69
  70 /**
  71  * \brief       Test if the given Filter ID is supported for decoding
  72  *
  73  * Returns true if the give Filter ID  is supported for decoding by this
  74  * liblzma build. Otherwise false is returned.
  75  */
  76 extern lzma_bool lzma_filter_decoder_is_supported(lzma_vli id);
  77
  78
  79 /**
  80  * \brief       Calculate rough memory requirements for raw encoder
  81  *
  82  * \param       filters     Array of filters terminated with
  83  *                          .id == LZMA_VLI_UNKNOWN.
  84  *
  85  * \return      Rough number of bytes required for the given filter chain
  86  *              when encoding.
  87  */
  88 extern uint64_t lzma_memusage_encoder(const lzma_filter *filters)
  89                 lzma_attr_pure;
  90
  91
  92 /**
  93  * \brief       Calculate rough memory requirements for raw decoder
  94  *
  95  * \param       filters     Array of filters terminated with
  96  *                          .id == LZMA_VLI_UNKNOWN.
  97  *
  98  * \return      Rough number of bytes required for the given filter chain
  99  *              when decoding.
 100  */
 101 extern uint64_t lzma_memusage_decoder(const lzma_filter *filters)
 102                 lzma_attr_pure;
 103
 104
 105 /**
 106  * \brief       Initialize raw encoder
 107  *
 108  * This function may be useful when implementing custom file formats.
 109  *
 110  * \param       strm    Pointer to properly prepared lzma_stream
 111  * \param       options Array of lzma_filter structures.
 112  *                      The end of the array must be marked with
 113  *                      .id = LZMA_VLI_UNKNOWN. The minimum
 114  *                      number of filters is one and the maximum is four.
 115  *
 116  * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the
 117  * filter chain supports it), or LZMA_FINISH.
 118  *
 119  * \return      - LZMA_OK
 120  *              - LZMA_MEM_ERROR
 121  *              - LZMA_OPTIONS_ERROR
 122  *              - LZMA_PROG_ERROR
 123  */
 124 extern lzma_ret lzma_raw_encoder(
 125                 lzma_stream *strm, const lzma_filter *options)
 126                 lzma_attr_warn_unused_result;
 127
 128
 129 /**
 130  * \brief       Initialize raw decoder
 131  *
 132  * The initialization of raw decoder goes similarly to raw encoder.
 133  *
 134  * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using
 135  * LZMA_FINISH is not required, it is supported just for convenience.
 136  *
 137  * \return      - LZMA_OK
 138  *              - LZMA_MEM_ERROR
 139  *              - LZMA_OPTIONS_ERROR
 140  *              - LZMA_PROG_ERROR
 141  */
 142 extern lzma_ret lzma_raw_decoder(
 143                 lzma_stream *strm, const lzma_filter *options)
 144                 lzma_attr_warn_unused_result;
 145
 146
 147 /**
 148  * \brief       Get the size of the Filter Properties field
 149  *
 150  * This function may be useful when implementing custom file formats
 151  * using the raw encoder and decoder.
 152  *
 153  * \param       size    Pointer to uint32_t to hold the size of the properties
 154  * \param       filter  Filter ID and options (the size of the propeties may
 155  *                      vary depending on the options)
 156  *
 157  * \return      - LZMA_OK
 158  *              - LZMA_OPTIONS_ERROR
 159  *              - LZMA_PROG_ERROR
 160  *
 161  * \note        This function validates the Filter ID, but does not
 162  *              necessarily validate the options. Thus, it is possible
 163  *              that this returns LZMA_OK while the following call to
 164  *              lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
 165  */
 166 extern lzma_ret lzma_properties_size(
 167                 uint32_t *size, const lzma_filter *filter);
 168
 169
 170 /**
 171  * \brief       Encode the Filter Properties field
 172  *
 173  * \param       filter  Filter ID and options
 174  * \param       props   Buffer to hold the encoded options. The size of
 175  *                      buffer must have been already determined with
 176  *                      lzma_properties_size().
 177  *
 178  * \return      - LZMA_OK
 179  *              - LZMA_OPTIONS_ERROR
 180  *              - LZMA_PROG_ERROR
 181  *
 182  * \note        Even this function won't validate more options than actually
 183  *              necessary. Thus, it is possible that encoding the properties
 184  *              succeeds but using the same options to initialize the encoder
 185  *              will fail.
 186  *
 187  * \note        It is OK to skip calling this function if
 188  *              lzma_properties_size() indicated that the size
 189  *              of the Filter Properties field is zero.
 190  */
 191 extern lzma_ret lzma_properties_encode(
 192                 const lzma_filter *filter, uint8_t *props);
 193
 194
 195 /**
 196  * \brief       Decode the Filter Properties field
 197  *
 198  * \param       filter      filter->id must have been set to the correct
 199  *                          Filter ID. filter->options doesn't need to be
 200  *                          initialized (it's not freed by this function). The
 201  *                          decoded options will be stored to filter->options.
 202  *                          filter->options is set to NULL if there are no
 203  *                          properties or if an error occurs.
 204  * \param       allocator   Custom memory allocator used to allocate the
 205  *                          options. Set to NULL to use the default malloc(),
 206  *                          and in case of an error, also free().
 207  * \param       props       Input buffer containing the properties.
 208  * \param       props_size  Size of the properties. This must be the exact
 209  *                          size; giving too much or too little input will
 210  *                          return LZMA_OPTIONS_ERROR.
 211  *
 212  * \return      - LZMA_OK
 213  *              - LZMA_OPTIONS_ERROR
 214  *              - LZMA_MEM_ERROR
 215  */
 216 extern lzma_ret lzma_properties_decode(
 217                 lzma_filter *filter, lzma_allocator *allocator,
 218                 const uint8_t *props, size_t props_size);
 219
 220
 221 /**
 222  * \brief       Calculates encoded size of a Filter Flags field
 223  *
 224  * Knowing the size of Filter Flags is useful to know when allocating
 225  * memory to hold the encoded Filter Flags.
 226  *
 227  * \param       size    Pointer to integer to hold the calculated size
 228  * \param       options Filter ID and associated options whose encoded
 229  *                      size is to be calculted
 230  *
 231  * \return      - LZMA_OK: *size set successfully. Note that this doesn't
 232  *                guarantee that options->options is valid, thus
 233  *                lzma_filter_flags_encode() may still fail.
 234  *              - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
 235  *              - LZMA_PROG_ERROR: Invalid options
 236  *
 237  * \note        If you need to calculate size of List of Filter Flags,
 238  *              you need to loop over every lzma_filter entry.
 239  */
 240 extern lzma_ret lzma_filter_flags_size(
 241                 uint32_t *size, const lzma_filter *options)
 242                 lzma_attr_warn_unused_result;
 243
 244
 245 /**
 246  * \brief       Encodes Filter Flags into given buffer
 247  *
 248  * In contrast to some functions, this doesn't allocate the needed buffer.
 249  * This is due to how this function is used internally by liblzma.
 250  *
 251  * \param       out         Beginning of the output buffer
 252  * \param       out_pos     out[*out_pos] is the next write position. This
 253  *                          is updated by the encoder.
 254  * \param       out_size    out[out_size] is the first byte to not write.
 255  * \param       options     Filter options to be encoded
 256  *
 257  * \return      - LZMA_OK: Encoding was successful.
 258  *              - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
 259  *              - LZMA_PROG_ERROR: Invalid options or not enough output
 260  *                buffer space (you should have checked it with
 261  *                lzma_filter_flags_size()).
 262  */
 263 extern lzma_ret lzma_filter_flags_encode(const lzma_filter *options,
 264                 uint8_t *out, size_t *out_pos, size_t out_size)
 265                 lzma_attr_warn_unused_result;
 266
 267
 268 /**
 269  * \brief       Initializes Filter Flags decoder
 270  *
 271  * The decoded result is stored into *options. options->options is
 272  * initialized but the old value is NOT free()d.
 273  *
 274  * Because the results of this decoder are placed into *options,
 275  * strm->next_in, strm->avail_in, and strm->total_in are not used
 276  * when calling lzma_code(). The only valid action for lzma_code()
 277  * is LZMA_RUN
 278  *
 279  * \return      - LZMA_OK
 280  *              - LZMA_MEM_ERROR
 281  *              - LZMA_PROG_ERROR
 282  */
 283 extern lzma_ret lzma_filter_flags_decode(
 284                 lzma_filter *options, lzma_allocator *allocator,
 285                 const uint8_t *in, size_t *in_pos, size_t in_size)
 286                 lzma_attr_warn_unused_result;