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 */ 33 typedef 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_bool reserved_bool1; 95 lzma_bool reserved_bool2; 96 lzma_bool reserved_bool3; 97 lzma_bool reserved_bool4; 98 lzma_bool reserved_bool5; 99 lzma_bool reserved_bool6; 100 lzma_bool reserved_bool7; 101 lzma_bool reserved_bool8; 102 uint32_t reserved_int1; 103 uint32_t reserved_int2; 104 105 } lzma_stream_flags; 106 107 108 /** 109 * \brief Encode Stream Header 110 * 111 * \param options Stream Header options to be encoded. 112 * options->backward_size is ignored and doesn't 113 * need to be initialized. 114 * \param out Beginning of the output buffer of 115 * LZMA_STREAM_HEADER_SIZE bytes. 116 * 117 * \return - LZMA_OK: Encoding was successful. 118 * - LZMA_OPTIONS_ERROR: options->version is not supported by 119 * this liblzma version. 120 * - LZMA_PROG_ERROR: Invalid options. 121 */ 122 extern LZMA_API(lzma_ret) lzma_stream_header_encode( 123 const lzma_stream_flags *options, uint8_t *out) 124 lzma_nothrow lzma_attr_warn_unused_result; 125 126 127 /** 128 * \brief Encode Stream Footer 129 * 130 * \param options Stream Footer options to be encoded. 131 * \param out Beginning of the output buffer of 132 * LZMA_STREAM_HEADER_SIZE bytes. 133 * 134 * \return - LZMA_OK: Encoding was successful. 135 * - LZMA_OPTIONS_ERROR: options->version is not supported by 136 * this liblzma version. 137 * - LZMA_PROG_ERROR: Invalid options. 138 */ 139 extern LZMA_API(lzma_ret) lzma_stream_footer_encode( 140 const lzma_stream_flags *options, uint8_t *out) 141 lzma_nothrow lzma_attr_warn_unused_result; 142 143 144 /** 145 * \brief Decode Stream Header 146 * 147 * \param options Target for the decoded Stream Header options. 148 * \param in Beginning of the input buffer of 149 * LZMA_STREAM_HEADER_SIZE bytes. 150 * 151 * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to 152 * help comparing Stream Flags from Stream Header and Stream Footer with 153 * lzma_stream_flags_compare(). 154 * 155 * \return - LZMA_OK: Decoding was successful. 156 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 157 * buffer cannot be Stream Header. 158 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header 159 * is corrupt. 160 * - LZMA_OPTIONS_ERROR: Unsupported options are present 161 * in the header. 162 * 163 * \note When decoding .xz files that contain multiple Streams, it may 164 * make sense to print "file format not recognized" only if 165 * decoding of the Stream Header of the _first_ Stream gives 166 * LZMA_FORMAT_ERROR. If non-first Stream Header gives 167 * LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is 168 * probably more appropriate. 169 * 170 * For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if 171 * LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() 172 * when decoding non-first Stream. 173 */ 174 extern LZMA_API(lzma_ret) lzma_stream_header_decode( 175 lzma_stream_flags *options, const uint8_t *in) 176 lzma_nothrow lzma_attr_warn_unused_result; 177 178 179 /** 180 * \brief Decode Stream Footer 181 * 182 * \param options Target for the decoded Stream Header options. 183 * \param in Beginning of the input buffer of 184 * LZMA_STREAM_HEADER_SIZE bytes. 185 * 186 * \return - LZMA_OK: Decoding was successful. 187 * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 188 * buffer cannot be Stream Footer. 189 * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer 190 * is corrupt. 191 * - LZMA_OPTIONS_ERROR: Unsupported options are present 192 * in Stream Footer. 193 * 194 * \note If Stream Header was already decoded successfully, but 195 * decoding Stream Footer returns LZMA_FORMAT_ERROR, the 196 * application should probably report some other error message 197 * than "file format not recognized", since the file more likely 198 * is corrupt (possibly truncated). Stream decoder in liblzma 199 * uses LZMA_DATA_ERROR in this situation. 200 */ 201 extern LZMA_API(lzma_ret) lzma_stream_footer_decode( 202 lzma_stream_flags *options, const uint8_t *in) 203 lzma_nothrow lzma_attr_warn_unused_result; 204 205 206 /** 207 * \brief Compare two lzma_stream_flags structures 208 * 209 * backward_size values are compared only if both are not 210 * LZMA_VLI_UNKNOWN. 211 * 212 * \return - LZMA_OK: Both are equal. If either had backward_size set 213 * to LZMA_VLI_UNKNOWN, backward_size values were not 214 * compared or validated. 215 * - LZMA_DATA_ERROR: The structures differ. 216 * - LZMA_OPTIONS_ERROR: version in either structure is greater 217 * than the maximum supported version (currently zero). 218 * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or 219 * backward_size. 220 */ 221 extern LZMA_API(lzma_ret) lzma_stream_flags_compare( 222 const lzma_stream_flags *a, const lzma_stream_flags *b) 223 lzma_nothrow lzma_attr_pure; 224