]> pd.if.org Git - zpackage/blob - lzma/api/lzma/stream_flags.h
add newline to zpm-stat usage message
[zpackage] / lzma / api / lzma / stream_flags.h
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;