1 /* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 // vim: expandtab:ts=8:sw=4:softtabstop=4: 3 /** 4 * \file lzma/stream_flags.h 5 * \brief .xz Stream Header and Stream Footer encoder and decoder 6 */ 7 8 /* 9 * Author: Lasse Collin 10 * 11 * This file has been put into the public domain. 12 * You can do whatever you want with this file. 13 * 14 * See ../lzma.h for information about liblzma as a whole. 15 */ 16 17 #ifndef LZMA_H_INTERNAL 18 # error Never include this file directly. Use <lzma.h> instead. 19 #endif 20 21 22 /** 23 * \brief Size of Stream Header and Stream Footer 24 * 25 * Stream Header and Stream Footer have the same size and they are not 26 * going to change even if a newer version of the .xz file format is 27 * developed in future. 28 */ 29 #define LZMA_STREAM_HEADER_SIZE 12 30 31 32 /** 33 * \brief Options for encoding/decoding Stream Header and Stream Footer 34 */ 35 typedef struct { 36 /** 37 * \brief Stream Flags format version 38 * 39 * To prevent API and ABI breakages if new features are needed in 40 * Stream Header or Stream Footer, a version number is used to 41 * indicate which fields in this structure are in use. For now, 42 * version must always be zero. With non-zero version, the 43 * lzma_stream_header_encode() and lzma_stream_footer_encode() 44 * will return LZMA_OPTIONS_ERROR. 45 * 46 * lzma_stream_header_decode() and lzma_stream_footer_decode() 47 * will always set this to the lowest value that supports all the 48 * features indicated by the Stream Flags field. The application 49 * must check that the version number set by the decoding functions 50 * is supported by the application. Otherwise it is possible that 51 * the application will decode the Stream incorrectly. 52 */ 53 uint32_t version; 54 55 /** 56 * \brief Backward Size 57 * 58 * Backward Size must be a multiple of four bytes. In this Stream 59 * format version, Backward Size is the size of the Index field. 60 * 61 * Backward Size isn't actually part of the Stream Flags field, but 62 * it is convenient to include in this structure anyway. Backward 63 * Size is present only in the Stream Footer. There is no need to 64 * initialize backward_size when encoding Stream Header. 65 * 66 * lzma_stream_header_decode() always sets backward_size to 67 * LZMA_VLI_UNKNOWN so that it is convenient to use 68 * lzma_stream_flags_compare() when both Stream Header and Stream 69 * Footer have been decoded. 70 */ 71 lzma_vli backward_size; 72 # define LZMA_BACKWARD_SIZE_MIN 4 73 # define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34) 74 75 /** 76 * \brief Check ID 77 * 78 * This indicates the type of the integrity check calculated from 79 * uncompressed data. 80 */ 81 lzma_check check; 82 83 /* 84 * Reserved space to allow possible future extensions without 85 * breaking the ABI. You should not touch these, because the 86 * names of these variables may change. 87 * 88 * (We will never be able to use all of these since Stream Flags 89 * is just two bytes plus Backward Size of four bytes. But it's 90 * nice to have the proper types when they are needed.) 91 */ 92 lzma_reserved_enum reserved_enum1; 93 lzma_reserved_enum reserved_enum2; 94 lzma_reserved_enum reserved_enum3; 95 lzma_reserved_enum reserved_enum4; 96 lzma_reserved_enum reserved_enum5; 97 lzma_reserved_enum reserved_enum6; 98 lzma_bool reserved_bool1; 99 lzma_bool reserved_bool2; 100 lzma_bool reserved_bool3; 101 lzma_bool reserved_bool4; 102 lzma_bool reserved_bool5; 103 lzma_bool reserved_bool6; 104 lzma_bool reserved_bool7; 105 lzma_bool reserved_bool8; 106 uint32_t reserved_int1; 107 uint32_t reserved_int2; 108 uint32_t reserved_int3; 109 uint32_t reserved_int4; 110 111 } lzma_stream_flags; 112 113 114 /** 115 * \brief Encode Stream Header 116 * 117 * \param options Stream Header options to be encoded. 118 * options->backward_size is ignored and doesn't 119 * need to be initialized. 120 * \param out Beginning of the output buffer of 121 * LZMA_STREAM_HEADER_SIZE bytes. 122 * 123 * \return - LZMA_OK: Encoding was successful. 124 * - LZMA_OPTIONS_ERROR: options->version is not supported by 125 * this liblzma version. 126 * - LZMA_PROG_ERROR: Invalid options. 127 */ 128 extern LZMA_API(lzma_ret) lzma_stream_header_encode( 129 const lzma_stream_flags *options, uint8_t *out) 130 lzma_nothrow lzma_attr_warn_unused_result; 131 132 133 /** 134 * \brief Encode Stream Footer 135 * 136 * \param options Stream Footer options to be encoded. 137 * \param out Beginning of the output buffer of 138 * LZMA_STREAM_HEADER_SIZE bytes. 139 * 140 * \return - LZMA_OK: Encoding was successful. 141 * - LZMA_OPTIONS_ERROR: options->version is not supported by 142 * this liblzma version. 143 * - LZMA_PROG_ERROR: Invalid options. 144 */ 145 extern LZMA_API(lzma_ret) lzma_stream_footer_encode( 146 const lzma_stream_flags *options, uint8_t *out) 147 lzma_nothrow lzma_attr_warn_unused_result; 148 149 150 /** 151 * \brief Decode Stream Header 152 * 153 * \param options Stream Header options to be encoded. 154 * \param in Beginning of the input buffer of 155 * LZMA_STREAM_HEADER_SIZE bytes. 156 * 157 * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to 158 * help comparing Stream Flags from Stream Header and Stream Footer with 159 * lzma_stream_flags_compare(). 160 * 161 * \return - LZMA_OK: Decoding was successful. 162 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 163 * buffer cannot be Stream Header. 164 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header 165 * is corrupt. 166 * - LZMA_OPTIONS_ERROR: Unsupported options are present 167 * in the header. 168 * 169 * \note When decoding .xz files that contain multiple Streams, it may 170 * make sense to print "file format not recognized" only if 171 * decoding of the Stream Header of the _first_ Stream gives 172 * LZMA_FORMAT_ERROR. If non-first Stream Header gives 173 * LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is 174 * probably more appropriate. 175 * 176 * For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if 177 * LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() 178 * when decoding non-first Stream. 179 */ 180 extern LZMA_API(lzma_ret) lzma_stream_header_decode( 181 lzma_stream_flags *options, const uint8_t *in) 182 lzma_nothrow lzma_attr_warn_unused_result; 183 184 185 /** 186 * \brief Decode Stream Footer 187 * 188 * \param options Stream Header options to be encoded. 189 * \param in Beginning of the input buffer of 190 * LZMA_STREAM_HEADER_SIZE bytes. 191 * 192 * \return - LZMA_OK: Decoding was successful. 193 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 194 * buffer cannot be Stream Footer. 195 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer 196 * is corrupt. 197 * - LZMA_OPTIONS_ERROR: Unsupported options are present 198 * in Stream Footer. 199 * 200 * \note If Stream Header was already decoded successfully, but 201 * decoding Stream Footer returns LZMA_FORMAT_ERROR, the 202 * application should probably report some other error message 203 * than "file format not recognized", since the file more likely 204 * is corrupt (possibly truncated). Stream decoder in liblzma 205 * uses LZMA_DATA_ERROR in this situation. 206 */ 207 extern LZMA_API(lzma_ret) lzma_stream_footer_decode( 208 lzma_stream_flags *options, const uint8_t *in) 209 lzma_nothrow lzma_attr_warn_unused_result; 210 211 212 /** 213 * \brief Compare two lzma_stream_flags structures 214 * 215 * backward_size values are compared only if both are not 216 * LZMA_VLI_UNKNOWN. 217 * 218 * \return - LZMA_OK: Both are equal. If either had backward_size set 219 * to LZMA_VLI_UNKNOWN, backward_size values were not 220 * compared or validated. 221 * - LZMA_DATA_ERROR: The structures differ. 222 * - LZMA_OPTIONS_ERROR: version in either structure is greater 223 * than the maximum supported version (currently zero). 224 * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or 225 * backward_size. 226 */ 227 extern LZMA_API(lzma_ret) lzma_stream_flags_compare( 228 const lzma_stream_flags *a, const lzma_stream_flags *b) 229 lzma_nothrow lzma_attr_pure; 230