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