1/* Copyright 2013 Google Inc. All Rights Reserved.
2
3 Distributed under MIT license.
4 See file LICENSE for detail or copy at https://opensource.org/licenses/MIT
5*/
6
7/**
8 * @file
9 * API for Brotli decompression.
10 */
11
12#ifndef BROTLI_DEC_DECODE_H_
13#define BROTLI_DEC_DECODE_H_
14
15#include <brotli/port.h>
16#include <brotli/shared_dictionary.h>
17#include <brotli/types.h>
18
19#if defined(__cplusplus) || defined(c_plusplus)
20extern "C" {
21#endif
22
23/**
24 * Opaque structure that holds decoder state.
25 *
26 * Allocated and initialized with ::BrotliDecoderCreateInstance.
27 * Cleaned up and deallocated with ::BrotliDecoderDestroyInstance.
28 */
29typedef struct BrotliDecoderStateStruct BrotliDecoderState;
30
31/**
32 * Result type for ::BrotliDecoderDecompress and
33 * ::BrotliDecoderDecompressStream functions.
34 */
35typedef enum {
36 /** Decoding error, e.g. corrupted input or memory allocation problem. */
37 BROTLI_DECODER_RESULT_ERROR = 0,
38 /** Decoding successfully completed. */
39 BROTLI_DECODER_RESULT_SUCCESS = 1,
40 /** Partially done; should be called again with more input. */
41 BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT = 2,
42 /** Partially done; should be called again with more output. */
43 BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT = 3
44} BrotliDecoderResult;
45
46/**
47 * Template that evaluates items of ::BrotliDecoderErrorCode.
48 *
49 * Example: @code {.cpp}
50 * // Log Brotli error code.
51 * switch (brotliDecoderErrorCode) {
52 * #define CASE_(PREFIX, NAME, CODE) \
53 * case BROTLI_DECODER ## PREFIX ## NAME: \
54 * LOG(INFO) << "error code:" << #NAME; \
55 * break;
56 * #define NEWLINE_
57 * BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_)
58 * #undef CASE_
59 * #undef NEWLINE_
60 * default: LOG(FATAL) << "unknown brotli error code";
61 * }
62 * @endcode
63 */
64#define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR) \
65 BROTLI_ERROR_CODE(_, NO_ERROR, 0) SEPARATOR \
66 /* Same as BrotliDecoderResult values */ \
67 BROTLI_ERROR_CODE(_, SUCCESS, 1) SEPARATOR \
68 BROTLI_ERROR_CODE(_, NEEDS_MORE_INPUT, 2) SEPARATOR \
69 BROTLI_ERROR_CODE(_, NEEDS_MORE_OUTPUT, 3) SEPARATOR \
70 \
71 /* Errors caused by invalid input */ \
72 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_NIBBLE, -1) SEPARATOR \
73 BROTLI_ERROR_CODE(_ERROR_FORMAT_, RESERVED, -2) SEPARATOR \
74 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_META_NIBBLE, -3) SEPARATOR \
75 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_ALPHABET, -4) SEPARATOR \
76 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_SAME, -5) SEPARATOR \
77 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CL_SPACE, -6) SEPARATOR \
78 BROTLI_ERROR_CODE(_ERROR_FORMAT_, HUFFMAN_SPACE, -7) SEPARATOR \
79 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CONTEXT_MAP_REPEAT, -8) SEPARATOR \
80 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_1, -9) SEPARATOR \
81 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_2, -10) SEPARATOR \
82 BROTLI_ERROR_CODE(_ERROR_FORMAT_, TRANSFORM, -11) SEPARATOR \
83 BROTLI_ERROR_CODE(_ERROR_FORMAT_, DICTIONARY, -12) SEPARATOR \
84 BROTLI_ERROR_CODE(_ERROR_FORMAT_, WINDOW_BITS, -13) SEPARATOR \
85 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_1, -14) SEPARATOR \
86 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_2, -15) SEPARATOR \
87 BROTLI_ERROR_CODE(_ERROR_FORMAT_, DISTANCE, -16) SEPARATOR \
88 \
89 /* -17 code is reserved */ \
90 \
91 BROTLI_ERROR_CODE(_ERROR_, COMPOUND_DICTIONARY, -18) SEPARATOR \
92 BROTLI_ERROR_CODE(_ERROR_, DICTIONARY_NOT_SET, -19) SEPARATOR \
93 BROTLI_ERROR_CODE(_ERROR_, INVALID_ARGUMENTS, -20) SEPARATOR \
94 \
95 /* Memory allocation problems */ \
96 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MODES, -21) SEPARATOR \
97 /* Literal, insert and distance trees together */ \
98 BROTLI_ERROR_CODE(_ERROR_ALLOC_, TREE_GROUPS, -22) SEPARATOR \
99 /* -23..-24 codes are reserved for distinct tree groups */ \
100 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MAP, -25) SEPARATOR \
101 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_1, -26) SEPARATOR \
102 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_2, -27) SEPARATOR \
103 /* -28..-29 codes are reserved for dynamic ring-buffer allocation */ \
104 BROTLI_ERROR_CODE(_ERROR_ALLOC_, BLOCK_TYPE_TREES, -30) SEPARATOR \
105 \
106 /* "Impossible" states */ \
107 BROTLI_ERROR_CODE(_ERROR_, UNREACHABLE, -31)
108
109/**
110 * Error code for detailed logging / production debugging.
111 *
112 * See ::BrotliDecoderGetErrorCode and ::BROTLI_LAST_ERROR_CODE.
113 */
114typedef enum {
115#define BROTLI_COMMA_ ,
116#define BROTLI_ERROR_CODE_ENUM_ITEM_(PREFIX, NAME, CODE) \
117 BROTLI_DECODER ## PREFIX ## NAME = CODE
118 BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE_ENUM_ITEM_, BROTLI_COMMA_)
119} BrotliDecoderErrorCode;
120#undef BROTLI_ERROR_CODE_ENUM_ITEM_
121#undef BROTLI_COMMA_
122
123/**
124 * The value of the last error code, negative integer.
125 *
126 * All other error code values are in the range from ::BROTLI_LAST_ERROR_CODE
127 * to @c -1. There are also 4 other possible non-error codes @c 0 .. @c 3 in
128 * ::BrotliDecoderErrorCode enumeration.
129 */
130#define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE
131
132/** Options to be used with ::BrotliDecoderSetParameter. */
133typedef enum BrotliDecoderParameter {
134 /**
135 * Disable "canny" ring buffer allocation strategy.
136 *
137 * Ring buffer is allocated according to window size, despite the real size of
138 * the content.
139 */
140 BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION = 0,
141 /**
142 * Flag that determines if "Large Window Brotli" is used.
143 */
144 BROTLI_DECODER_PARAM_LARGE_WINDOW = 1
145} BrotliDecoderParameter;
146
147/**
148 * Sets the specified parameter to the given decoder instance.
149 *
150 * @param state decoder instance
151 * @param param parameter to set
152 * @param value new parameter value
153 * @returns ::BROTLI_FALSE if parameter is unrecognized, or value is invalid
154 * @returns ::BROTLI_TRUE if value is accepted
155 */
156BROTLI_DEC_API BROTLI_BOOL BrotliDecoderSetParameter(
157 BrotliDecoderState* state, BrotliDecoderParameter param, uint32_t value);
158
159/**
160 * Adds LZ77 prefix dictionary, adds or replaces built-in static dictionary and
161 * transforms.
162 *
163 * Attached dictionary ownership is not transferred.
164 * Data provided to this method should be kept accessible until
165 * decoding is finished and decoder instance is destroyed.
166 *
167 * @note Dictionaries can NOT be attached after actual decoding is started.
168 *
169 * @param state decoder instance
170 * @param type dictionary data format
171 * @param data_size length of memory region pointed by @p data
172 * @param data dictionary data in format corresponding to @p type
173 * @returns ::BROTLI_FALSE if dictionary is corrupted,
174 * or dictionary count limit is reached
175 * @returns ::BROTLI_TRUE if dictionary is accepted / attached
176 */
177BROTLI_DEC_API BROTLI_BOOL BrotliDecoderAttachDictionary(
178 BrotliDecoderState* state, BrotliSharedDictionaryType type,
179 size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)]);
180
181/**
182 * Creates an instance of ::BrotliDecoderState and initializes it.
183 *
184 * The instance can be used once for decoding and should then be destroyed with
185 * ::BrotliDecoderDestroyInstance, it cannot be reused for a new decoding
186 * session.
187 *
188 * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the
189 * case they are both zero, default memory allocators are used. @p opaque is
190 * passed to @p alloc_func and @p free_func when they are called. @p free_func
191 * has to return without doing anything when asked to free a NULL pointer.
192 *
193 * @param alloc_func custom memory allocation function
194 * @param free_func custom memory free function
195 * @param opaque custom memory manager handle
196 * @returns @c 0 if instance can not be allocated or initialized
197 * @returns pointer to initialized ::BrotliDecoderState otherwise
198 */
199BROTLI_DEC_API BrotliDecoderState* BrotliDecoderCreateInstance(
200 brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
201
202/**
203 * Deinitializes and frees ::BrotliDecoderState instance.
204 *
205 * @param state decoder instance to be cleaned up and deallocated
206 */
207BROTLI_DEC_API void BrotliDecoderDestroyInstance(BrotliDecoderState* state);
208
209/**
210 * Performs one-shot memory-to-memory decompression.
211 *
212 * Decompresses the data in @p encoded_buffer into @p decoded_buffer, and sets
213 * @p *decoded_size to the decompressed length.
214 *
215 * @param encoded_size size of @p encoded_buffer
216 * @param encoded_buffer compressed data buffer with at least @p encoded_size
217 * addressable bytes
218 * @param[in, out] decoded_size @b in: size of @p decoded_buffer; \n
219 * @b out: length of decompressed data written to
220 * @p decoded_buffer
221 * @param decoded_buffer decompressed data destination buffer
222 * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory
223 * allocation failed, or @p decoded_buffer is not large enough;
224 * @returns ::BROTLI_DECODER_RESULT_SUCCESS otherwise
225 */
226BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompress(
227 size_t encoded_size,
228 const uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(encoded_size)],
229 size_t* decoded_size,
230 uint8_t decoded_buffer[BROTLI_ARRAY_PARAM(*decoded_size)]);
231
232/**
233 * Decompresses the input stream to the output stream.
234 *
235 * The values @p *available_in and @p *available_out must specify the number of
236 * bytes addressable at @p *next_in and @p *next_out respectively.
237 * When @p *available_out is @c 0, @p next_out is allowed to be @c NULL.
238 *
239 * After each call, @p *available_in will be decremented by the amount of input
240 * bytes consumed, and the @p *next_in pointer will be incremented by that
241 * amount. Similarly, @p *available_out will be decremented by the amount of
242 * output bytes written, and the @p *next_out pointer will be incremented by
243 * that amount.
244 *
245 * @p total_out, if it is not a null-pointer, will be set to the number
246 * of bytes decompressed since the last @p state initialization.
247 *
248 * @note Input is never overconsumed, so @p next_in and @p available_in could be
249 * passed to the next consumer after decoding is complete.
250 *
251 * @param state decoder instance
252 * @param[in, out] available_in @b in: amount of available input; \n
253 * @b out: amount of unused input
254 * @param[in, out] next_in pointer to the next compressed byte
255 * @param[in, out] available_out @b in: length of output buffer; \n
256 * @b out: remaining size of output buffer
257 * @param[in, out] next_out output buffer cursor;
258 * can be @c NULL if @p available_out is @c 0
259 * @param[out] total_out number of bytes decompressed so far; can be @c NULL
260 * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory
261 * allocation failed, arguments were invalid, etc.;
262 * use ::BrotliDecoderGetErrorCode to get detailed error code
263 * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT decoding is blocked until
264 * more input data is provided
265 * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT decoding is blocked until
266 * more output space is provided
267 * @returns ::BROTLI_DECODER_RESULT_SUCCESS decoding is finished, no more
268 * input might be consumed and no more output will be produced
269 */
270BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompressStream(
271 BrotliDecoderState* state, size_t* available_in, const uint8_t** next_in,
272 size_t* available_out, uint8_t** next_out, size_t* total_out);
273
274/**
275 * Checks if decoder has more output.
276 *
277 * @param state decoder instance
278 * @returns ::BROTLI_TRUE, if decoder has some unconsumed output
279 * @returns ::BROTLI_FALSE otherwise
280 */
281BROTLI_DEC_API BROTLI_BOOL BrotliDecoderHasMoreOutput(
282 const BrotliDecoderState* state);
283
284/**
285 * Acquires pointer to internal output buffer.
286 *
287 * This method is used to make language bindings easier and more efficient:
288 * -# push data to ::BrotliDecoderDecompressStream,
289 * until ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT is reported
290 * -# use ::BrotliDecoderTakeOutput to peek bytes and copy to language-specific
291 * entity
292 *
293 * Also this could be useful if there is an output stream that is able to
294 * consume all the provided data (e.g. when data is saved to file system).
295 *
296 * @attention After every call to ::BrotliDecoderTakeOutput @p *size bytes of
297 * output are considered consumed for all consecutive calls to the
298 * instance methods; returned pointer becomes invalidated as well.
299 *
300 * @note Decoder output is not guaranteed to be contiguous. This means that
301 * after the size-unrestricted call to ::BrotliDecoderTakeOutput,
302 * immediate next call to ::BrotliDecoderTakeOutput may return more data.
303 *
304 * @param state decoder instance
305 * @param[in, out] size @b in: number of bytes caller is ready to take, @c 0 if
306 * any amount could be handled; \n
307 * @b out: amount of data pointed by returned pointer and
308 * considered consumed; \n
309 * out value is never greater than in value, unless it is @c 0
310 * @returns pointer to output data
311 */
312BROTLI_DEC_API const uint8_t* BrotliDecoderTakeOutput(
313 BrotliDecoderState* state, size_t* size);
314
315/**
316 * Checks if instance has already consumed input.
317 *
318 * Instance that returns ::BROTLI_FALSE is considered "fresh" and could be
319 * reused.
320 *
321 * @param state decoder instance
322 * @returns ::BROTLI_TRUE if decoder has already used some input bytes
323 * @returns ::BROTLI_FALSE otherwise
324 */
325BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* state);
326
327/**
328 * Checks if decoder instance reached the final state.
329 *
330 * @param state decoder instance
331 * @returns ::BROTLI_TRUE if decoder is in a state where it reached the end of
332 * the input and produced all of the output
333 * @returns ::BROTLI_FALSE otherwise
334 */
335BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsFinished(
336 const BrotliDecoderState* state);
337
338/**
339 * Acquires a detailed error code.
340 *
341 * Should be used only after ::BrotliDecoderDecompressStream returns
342 * ::BROTLI_DECODER_RESULT_ERROR.
343 *
344 * See also ::BrotliDecoderErrorString
345 *
346 * @param state decoder instance
347 * @returns last saved error code
348 */
349BROTLI_DEC_API BrotliDecoderErrorCode BrotliDecoderGetErrorCode(
350 const BrotliDecoderState* state);
351
352/**
353 * Converts error code to a c-string.
354 */
355BROTLI_DEC_API const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c);
356
357/**
358 * Gets a decoder library version.
359 *
360 * Look at BROTLI_MAKE_HEX_VERSION for more information.
361 */
362BROTLI_DEC_API uint32_t BrotliDecoderVersion(void);
363
364/**
365 * Callback to fire on metadata block start.
366 *
367 * After this callback is fired, if @p size is not @c 0, it is followed by
368 * ::brotli_decoder_metadata_chunk_func as more metadata block contents become
369 * accessible.
370 *
371 * @param opaque callback handle
372 * @param size size of metadata block
373 */
374typedef void (*brotli_decoder_metadata_start_func)(void* opaque, size_t size);
375
376/**
377 * Callback to fire on metadata block chunk becomes available.
378 *
379 * This function can be invoked multiple times per metadata block; block should
380 * be considered finished when sum of @p size matches the announced metadata
381 * block size. Chunks contents pointed by @p data are transient and shouln not
382 * be accessed after leaving the callback.
383 *
384 * @param opaque callback handle
385 * @param data pointer to metadata contents
386 * @param size size of metadata block chunk, at least @c 1
387 */
388typedef void (*brotli_decoder_metadata_chunk_func)(void* opaque,
389 const uint8_t* data,
390 size_t size);
391
392/**
393 * Sets callback for receiving metadata blocks.
394 *
395 * @param state decoder instance
396 * @param start_func callback on metadata block start
397 * @param chunk_func callback on metadata block chunk
398 * @param opaque callback handle
399 */
400BROTLI_DEC_API void BrotliDecoderSetMetadataCallbacks(
401 BrotliDecoderState* state,
402 brotli_decoder_metadata_start_func start_func,
403 brotli_decoder_metadata_chunk_func chunk_func, void* opaque);
404
405#if defined(__cplusplus) || defined(c_plusplus)
406} /* extern "C" */
407#endif
408
409#endif /* BROTLI_DEC_DECODE_H_ */
410

source code of include/brotli/decode.h