src/liblzma/api/lzma/metadata.h

   1 /**
   2  * \file        lzma/metadata.h
   3  * \brief       Metadata handling
   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       Information stored into a Metadata Block
  26  *
  27  * This structure holds all the information that can be stored to
  28  * a Metadata Block.
  29  */
  30 typedef struct {
  31         /**
  32          * \brief       Size of Header Metadata Block
  33          */
  34         lzma_vli header_metadata_size;
  35
  36         /**
  37          * \brief       Total Size of the Stream
  38          */
  39         lzma_vli total_size;
  40
  41         /**
  42          * \brief       Uncompressed Size of the Stream
  43          */
  44         lzma_vli uncompressed_size;
  45
  46         /**
  47          * \brief       Index of the Blocks stored in the Stream
  48          */
  49         lzma_index *index;
  50
  51         /**
  52          * \brief       Extra information
  53          */
  54         lzma_extra *extra;
  55
  56 } lzma_metadata;
  57
  58
  59 /**
  60  * \brief       Calculate the encoded size of Metadata
  61  *
  62  * \return      Uncompressed size of the Metadata in encoded form. This value
  63  *              may be passed to Block encoder as Uncompressed Size when using
  64  *              Metadata filter. On error, zero is returned.
  65  */
  66 extern lzma_vli lzma_metadata_size(const lzma_metadata *metadata);
  67
  68
  69 /**
  70  * \brief       Initializes Metadata encoder
  71  *
  72  * \param       coder       Pointer to a pointer to hold Metadata encoder's
  73  *                          internal state. Original value is ignored, thus
  74  *                          you don't need to initialize the pointer.
  75  * \param       allocator   Custom memory allocator; usually NULL.
  76  * \param       metadata    Pointer to Metadata to encoded
  77  *
  78  * \return      - LZMA_OK: Initialization succeeded.
  79  *              - LZMA_MEM_ERROR: Cannot allocate memory for *coder.
  80  *
  81  * The initialization function makes internal copy of the *metadata structure.
  82  * However, the linked lists metadata->index and metadata->extra are NOT
  83  * copied. Thus, the application may destroy *metadata after initialization
  84  * if it likes, but not Index or Extra.
  85  */
  86 extern lzma_ret lzma_metadata_encoder(lzma_stream *strm,
  87                 lzma_options_block *options, const lzma_metadata *metadata);
  88
  89
  90 /**
  91  * \brief       Initializes Metadata decoder
  92  *
  93  * \param       want_extra    If this is true, Extra Records will be stored
  94  *                            to metadata->extra. If this is false, Extra
  95  *                            Records will be parsed but not stored anywhere,
  96  *                            metadata->extra will be set to NULL.
  97  */
  98 extern lzma_ret lzma_metadata_decoder(
  99                 lzma_stream *strm, lzma_options_block *options,
 100                 lzma_metadata *metadata, lzma_bool want_extra);