1207753Smm/** 2207753Smm * \file lzma/stream_flags.h 3207753Smm * \brief .xz Stream Header and Stream Footer encoder and decoder 4207753Smm */ 5207753Smm 6207753Smm/* 7207753Smm * Author: Lasse Collin 8207753Smm * 9207753Smm * This file has been put into the public domain. 10207753Smm * You can do whatever you want with this file. 11207753Smm * 12207753Smm * See ../lzma.h for information about liblzma as a whole. 13207753Smm */ 14207753Smm 15207753Smm#ifndef LZMA_H_INTERNAL 16207753Smm# error Never include this file directly. Use <lzma.h> instead. 17207753Smm#endif 18207753Smm 19207753Smm 20207753Smm/** 21207753Smm * \brief Size of Stream Header and Stream Footer 22207753Smm * 23207753Smm * Stream Header and Stream Footer have the same size and they are not 24207753Smm * going to change even if a newer version of the .xz file format is 25207753Smm * developed in future. 26207753Smm */ 27207753Smm#define LZMA_STREAM_HEADER_SIZE 12 28207753Smm 29207753Smm 30207753Smm/** 31207753Smm * \brief Options for encoding/decoding Stream Header and Stream Footer 32207753Smm */ 33207753Smmtypedef struct { 34207753Smm /** 35207753Smm * \brief Stream Flags format version 36207753Smm * 37207753Smm * To prevent API and ABI breakages if new features are needed in 38207753Smm * Stream Header or Stream Footer, a version number is used to 39207753Smm * indicate which fields in this structure are in use. For now, 40207753Smm * version must always be zero. With non-zero version, the 41207753Smm * lzma_stream_header_encode() and lzma_stream_footer_encode() 42207753Smm * will return LZMA_OPTIONS_ERROR. 43207753Smm * 44207753Smm * lzma_stream_header_decode() and lzma_stream_footer_decode() 45207753Smm * will always set this to the lowest value that supports all the 46207753Smm * features indicated by the Stream Flags field. The application 47207753Smm * must check that the version number set by the decoding functions 48207753Smm * is supported by the application. Otherwise it is possible that 49207753Smm * the application will decode the Stream incorrectly. 50207753Smm */ 51207753Smm uint32_t version; 52207753Smm 53207753Smm /** 54207753Smm * \brief Backward Size 55207753Smm * 56207753Smm * Backward Size must be a multiple of four bytes. In this Stream 57207753Smm * format version, Backward Size is the size of the Index field. 58207753Smm * 59207753Smm * Backward Size isn't actually part of the Stream Flags field, but 60207753Smm * it is convenient to include in this structure anyway. Backward 61207753Smm * Size is present only in the Stream Footer. There is no need to 62207753Smm * initialize backward_size when encoding Stream Header. 63207753Smm * 64207753Smm * lzma_stream_header_decode() always sets backward_size to 65207753Smm * LZMA_VLI_UNKNOWN so that it is convenient to use 66207753Smm * lzma_stream_flags_compare() when both Stream Header and Stream 67207753Smm * Footer have been decoded. 68207753Smm */ 69207753Smm lzma_vli backward_size; 70207753Smm# define LZMA_BACKWARD_SIZE_MIN 4 71207753Smm# define LZMA_BACKWARD_SIZE_MAX (LZMA_VLI_C(1) << 34) 72207753Smm 73207753Smm /** 74207753Smm * \brief Check ID 75207753Smm * 76207753Smm * This indicates the type of the integrity check calculated from 77207753Smm * uncompressed data. 78207753Smm */ 79207753Smm lzma_check check; 80207753Smm 81207753Smm /* 82207753Smm * Reserved space to allow possible future extensions without 83207753Smm * breaking the ABI. You should not touch these, because the 84207753Smm * names of these variables may change. 85207753Smm * 86207753Smm * (We will never be able to use all of these since Stream Flags 87207753Smm * is just two bytes plus Backward Size of four bytes. But it's 88207753Smm * nice to have the proper types when they are needed.) 89207753Smm */ 90207753Smm lzma_reserved_enum reserved_enum1; 91207753Smm lzma_reserved_enum reserved_enum2; 92207753Smm lzma_reserved_enum reserved_enum3; 93207753Smm lzma_reserved_enum reserved_enum4; 94207753Smm lzma_bool reserved_bool1; 95207753Smm lzma_bool reserved_bool2; 96207753Smm lzma_bool reserved_bool3; 97207753Smm lzma_bool reserved_bool4; 98207753Smm lzma_bool reserved_bool5; 99207753Smm lzma_bool reserved_bool6; 100207753Smm lzma_bool reserved_bool7; 101207753Smm lzma_bool reserved_bool8; 102207753Smm uint32_t reserved_int1; 103207753Smm uint32_t reserved_int2; 104207753Smm 105207753Smm} lzma_stream_flags; 106207753Smm 107207753Smm 108207753Smm/** 109207753Smm * \brief Encode Stream Header 110207753Smm * 111207753Smm * \param options Stream Header options to be encoded. 112207753Smm * options->backward_size is ignored and doesn't 113207753Smm * need to be initialized. 114207753Smm * \param out Beginning of the output buffer of 115207753Smm * LZMA_STREAM_HEADER_SIZE bytes. 116207753Smm * 117207753Smm * \return - LZMA_OK: Encoding was successful. 118207753Smm * - LZMA_OPTIONS_ERROR: options->version is not supported by 119207753Smm * this liblzma version. 120207753Smm * - LZMA_PROG_ERROR: Invalid options. 121207753Smm */ 122207753Smmextern LZMA_API(lzma_ret) lzma_stream_header_encode( 123207753Smm const lzma_stream_flags *options, uint8_t *out) 124207753Smm lzma_nothrow lzma_attr_warn_unused_result; 125207753Smm 126207753Smm 127207753Smm/** 128207753Smm * \brief Encode Stream Footer 129207753Smm * 130207753Smm * \param options Stream Footer options to be encoded. 131207753Smm * \param out Beginning of the output buffer of 132207753Smm * LZMA_STREAM_HEADER_SIZE bytes. 133207753Smm * 134207753Smm * \return - LZMA_OK: Encoding was successful. 135207753Smm * - LZMA_OPTIONS_ERROR: options->version is not supported by 136207753Smm * this liblzma version. 137207753Smm * - LZMA_PROG_ERROR: Invalid options. 138207753Smm */ 139207753Smmextern LZMA_API(lzma_ret) lzma_stream_footer_encode( 140207753Smm const lzma_stream_flags *options, uint8_t *out) 141207753Smm lzma_nothrow lzma_attr_warn_unused_result; 142207753Smm 143207753Smm 144207753Smm/** 145207753Smm * \brief Decode Stream Header 146207753Smm * 147215187Smm * \param options Target for the decoded Stream Header options. 148207753Smm * \param in Beginning of the input buffer of 149207753Smm * LZMA_STREAM_HEADER_SIZE bytes. 150207753Smm * 151207753Smm * options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to 152207753Smm * help comparing Stream Flags from Stream Header and Stream Footer with 153207753Smm * lzma_stream_flags_compare(). 154207753Smm * 155207753Smm * \return - LZMA_OK: Decoding was successful. 156207753Smm * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 157207753Smm * buffer cannot be Stream Header. 158207753Smm * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the header 159207753Smm * is corrupt. 160207753Smm * - LZMA_OPTIONS_ERROR: Unsupported options are present 161207753Smm * in the header. 162207753Smm * 163207753Smm * \note When decoding .xz files that contain multiple Streams, it may 164207753Smm * make sense to print "file format not recognized" only if 165207753Smm * decoding of the Stream Header of the _first_ Stream gives 166207753Smm * LZMA_FORMAT_ERROR. If non-first Stream Header gives 167207753Smm * LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is 168207753Smm * probably more appropriate. 169207753Smm * 170207753Smm * For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if 171207753Smm * LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() 172207753Smm * when decoding non-first Stream. 173207753Smm */ 174207753Smmextern LZMA_API(lzma_ret) lzma_stream_header_decode( 175207753Smm lzma_stream_flags *options, const uint8_t *in) 176207753Smm lzma_nothrow lzma_attr_warn_unused_result; 177207753Smm 178207753Smm 179207753Smm/** 180207753Smm * \brief Decode Stream Footer 181207753Smm * 182215187Smm * \param options Target for the decoded Stream Header options. 183207753Smm * \param in Beginning of the input buffer of 184207753Smm * LZMA_STREAM_HEADER_SIZE bytes. 185207753Smm * 186207753Smm * \return - LZMA_OK: Decoding was successful. 187207753Smm * - LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given 188207753Smm * buffer cannot be Stream Footer. 189207753Smm * - LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer 190207753Smm * is corrupt. 191207753Smm * - LZMA_OPTIONS_ERROR: Unsupported options are present 192207753Smm * in Stream Footer. 193207753Smm * 194207753Smm * \note If Stream Header was already decoded successfully, but 195207753Smm * decoding Stream Footer returns LZMA_FORMAT_ERROR, the 196207753Smm * application should probably report some other error message 197207753Smm * than "file format not recognized", since the file more likely 198207753Smm * is corrupt (possibly truncated). Stream decoder in liblzma 199207753Smm * uses LZMA_DATA_ERROR in this situation. 200207753Smm */ 201207753Smmextern LZMA_API(lzma_ret) lzma_stream_footer_decode( 202207753Smm lzma_stream_flags *options, const uint8_t *in) 203207753Smm lzma_nothrow lzma_attr_warn_unused_result; 204207753Smm 205207753Smm 206207753Smm/** 207207753Smm * \brief Compare two lzma_stream_flags structures 208207753Smm * 209207753Smm * backward_size values are compared only if both are not 210207753Smm * LZMA_VLI_UNKNOWN. 211207753Smm * 212207753Smm * \return - LZMA_OK: Both are equal. If either had backward_size set 213207753Smm * to LZMA_VLI_UNKNOWN, backward_size values were not 214207753Smm * compared or validated. 215207753Smm * - LZMA_DATA_ERROR: The structures differ. 216207753Smm * - LZMA_OPTIONS_ERROR: version in either structure is greater 217207753Smm * than the maximum supported version (currently zero). 218207753Smm * - LZMA_PROG_ERROR: Invalid value, e.g. invalid check or 219207753Smm * backward_size. 220207753Smm */ 221207753Smmextern LZMA_API(lzma_ret) lzma_stream_flags_compare( 222207753Smm const lzma_stream_flags *a, const lzma_stream_flags *b) 223207753Smm lzma_nothrow lzma_attr_pure; 224