src/liblzma/api/lzma/extra.h

   1 /**
   2  * \file        lzma/extra.h
   3  * \brief       Handling of Extra Records in Metadata
   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  * Extra Record IDs
  26  *
  27  * See the .lzma file format specification for description what each
  28  * Extra Record type exactly means.
  29  *
  30  * If you ever need to update .lzma files with Extra Records, note that
  31  * the Record IDs are divided in two categories:
  32  *  - Safe-to-Copy Records may be preserved as is when the
  33  *    Stream is modified in ways that don't change the actual
  34  *    uncompressed data. Examples of such operatings include
  35  *    recompressing and adding, modifying, or deleting unrelated
  36  *    Extra Records.
  37  *  - Unsafe-to-Copy Records should be removed (and possibly
  38  *    recreated) when any kind of changes are made to the Stream.
  39  */
  40
  41 #define LZMA_EXTRA_PADDING      0x00
  42 #define LZMA_EXTRA_OPENPGP      0x01
  43 #define LZMA_EXTRA_FILTERS      0x02
  44 #define LZMA_EXTRA_COMMENT      0x03
  45 #define LZMA_EXTRA_CHECKS       0x04
  46 #define LZMA_EXTRA_FILENAME     0x05
  47 #define LZMA_EXTRA_MTIME        0x07
  48 #define LZMA_EXTRA_MTIME_HR     0x09
  49 #define LZMA_EXTRA_MIME_TYPE    0x0B
  50 #define LZMA_EXTRA_HOMEPAGE     0x0D
  51
  52
  53 /**
  54  * \brief       Extra Records
  55  *
  56  * The .lzma format provides a way to store custom information along
  57  * the actual compressed content. Information about these Records
  58  * are passed to and from liblzma via this linked list.
  59  */
  60 typedef struct lzma_extra_s lzma_extra;
  61 struct lzma_extra_s {
  62         /**
  63          * \brief       Pointer to the next Extra Record
  64          *
  65          * This is NULL on the last Extra Record.
  66          */
  67         lzma_extra *next;
  68
  69         /**
  70          * \brief       Record ID
  71          *
  72          * Extra Record IDs are divided in three categories:
  73          *   - Zero is a special case used for padding. It doesn't have
  74          *     Size of Data fields.
  75          *   - Odd IDs (1, 3, 5, ...) are Safe-to-Copy IDs.
  76          *     These can be preserved as is if the Stream is
  77          *     modified in a way that doesn't alter the actual
  78          *     uncompressed content.
  79          *   - Even IDs (2, 4, 6, ...) are Unsafe-to-Copy IDs.
  80          *     If the .lzma Stream is modified in any way,
  81          *     the Extra Records having a sensitive ID should
  82          *     be removed or updated accordingly.
  83          *
  84          * Refer to the .lzma file format specification for
  85          * the up to date list of Extra Record IDs.
  86          */
  87         lzma_vli id;
  88
  89         /**
  90          * \brief       Size of the Record data
  91          *
  92          * In case of strings, this should not include the
  93          * trailing '\0'.
  94          */
  95         size_t size;
  96
  97         /**
  98          * \brief       Record data
  99          *
 100          * Record data is often a string in UTF-8 encoding,
 101          * but it can be arbitrary binary data. In case of
 102          * strings, the trailing '\0' is usually not stored
 103          * in the .lzma file.
 104          *
 105          * To ease working with Extra Records containing strings,
 106          * liblzma always adds '\0' to the end of data even when
 107          * it wasn't present in the .lzma file. This '\0' is not
 108          * counted in the size of the data.
 109          */
 110         uint8_t *data;
 111 };
 112
 113
 114 extern void lzma_extra_free(lzma_extra *extra, lzma_allocator *allocator);