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