MdeModulePkg: Copy Brotli algorithm 3rd party source code for library
[mirror_edk2.git] / MdeModulePkg / Library / BrotliCustomDecompressLib / dec / decode.h
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 /* API for Brotli decompression */
8
9 #ifndef BROTLI_DEC_DECODE_H_
10 #define BROTLI_DEC_DECODE_H_
11
12 #include "../common/types.h"
13
14 #if defined(__cplusplus) || defined(c_plusplus)
15 extern "C" {
16 #endif
17
18 typedef struct BrotliDecoderStateStruct BrotliDecoderState;
19
20 typedef enum {
21 /* Decoding error, e.g. corrupt input or memory allocation problem */
22 BROTLI_DECODER_RESULT_ERROR = 0,
23 /* Decoding successfully completed */
24 BROTLI_DECODER_RESULT_SUCCESS = 1,
25 /* Partially done; should be called again with more input */
26 BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT = 2,
27 /* Partially done; should be called again with more output */
28 BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT = 3
29 } BrotliDecoderResult;
30
31 #define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR) \
32 BROTLI_ERROR_CODE(_, NO_ERROR, 0) SEPARATOR \
33 /* Same as BrotliDecoderResult values */ \
34 BROTLI_ERROR_CODE(_, SUCCESS, 1) SEPARATOR \
35 BROTLI_ERROR_CODE(_, NEEDS_MORE_INPUT, 2) SEPARATOR \
36 BROTLI_ERROR_CODE(_, NEEDS_MORE_OUTPUT, 3) SEPARATOR \
37 \
38 /* Errors caused by invalid input */ \
39 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_NIBBLE, -1) SEPARATOR \
40 BROTLI_ERROR_CODE(_ERROR_FORMAT_, RESERVED, -2) SEPARATOR \
41 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_META_NIBBLE, -3) SEPARATOR \
42 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_ALPHABET, -4) SEPARATOR \
43 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_SAME, -5) SEPARATOR \
44 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CL_SPACE, -6) SEPARATOR \
45 BROTLI_ERROR_CODE(_ERROR_FORMAT_, HUFFMAN_SPACE, -7) SEPARATOR \
46 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CONTEXT_MAP_REPEAT, -8) SEPARATOR \
47 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_1, -9) SEPARATOR \
48 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_2, -10) SEPARATOR \
49 BROTLI_ERROR_CODE(_ERROR_FORMAT_, TRANSFORM, -11) SEPARATOR \
50 BROTLI_ERROR_CODE(_ERROR_FORMAT_, DICTIONARY, -12) SEPARATOR \
51 BROTLI_ERROR_CODE(_ERROR_FORMAT_, WINDOW_BITS, -13) SEPARATOR \
52 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_1, -14) SEPARATOR \
53 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_2, -15) SEPARATOR \
54 \
55 /* -16..-20 codes are reserved */ \
56 \
57 /* Memory allocation problems */ \
58 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MODES, -21) SEPARATOR \
59 /* Literal, insert and distance trees together */ \
60 BROTLI_ERROR_CODE(_ERROR_ALLOC_, TREE_GROUPS, -22) SEPARATOR \
61 /* -23..-24 codes are reserved for distinct tree groups */ \
62 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MAP, -25) SEPARATOR \
63 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_1, -26) SEPARATOR \
64 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_2, -27) SEPARATOR \
65 /* -28..-29 codes are reserved for dynamic ringbuffer allocation */ \
66 BROTLI_ERROR_CODE(_ERROR_ALLOC_, BLOCK_TYPE_TREES, -30) SEPARATOR \
67 \
68 /* "Impossible" states */ \
69 BROTLI_ERROR_CODE(_ERROR_, UNREACHABLE, -31)
70
71 typedef enum {
72 #define _BROTLI_COMMA ,
73 #define _BROTLI_ERROR_CODE_ENUM_ITEM(PREFIX, NAME, CODE) \
74 BROTLI_DECODER ## PREFIX ## NAME = CODE
75 BROTLI_DECODER_ERROR_CODES_LIST(_BROTLI_ERROR_CODE_ENUM_ITEM, _BROTLI_COMMA)
76 #undef _BROTLI_ERROR_CODE_ENUM_ITEM
77 #undef _BROTLI_COMMA
78 } BrotliDecoderErrorCode;
79
80 #define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE
81
82 /* Creates the instance of BrotliDecoderState and initializes it. |alloc_func|
83 and |free_func| MUST be both zero or both non-zero. In the case they are both
84 zero, default memory allocators are used. |opaque| is passed to |alloc_func|
85 and |free_func| when they are called. */
86 BrotliDecoderState* BrotliDecoderCreateInstance(
87 brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
88
89 /* Deinitializes and frees BrotliDecoderState instance. */
90 void BrotliDecoderDestroyInstance(BrotliDecoderState* state);
91
92 /* Decompresses the data in |encoded_buffer| into |decoded_buffer|, and sets
93 |*decoded_size| to the decompressed length. */
94 BrotliDecoderResult BrotliDecoderDecompress(
95 size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size,
96 uint8_t* decoded_buffer);
97
98 /* Decompresses the data. Supports partial input and output.
99
100 Must be called with an allocated input buffer in |*next_in| and an allocated
101 output buffer in |*next_out|. The values |*available_in| and |*available_out|
102 must specify the allocated size in |*next_in| and |*next_out| respectively.
103
104 After each call, |*available_in| will be decremented by the amount of input
105 bytes consumed, and the |*next_in| pointer will be incremented by that
106 amount. Similarly, |*available_out| will be decremented by the amount of
107 output bytes written, and the |*next_out| pointer will be incremented by that
108 amount. |total_out|, if it is not a null-pointer, will be set to the number
109 of bytes decompressed since the last state initialization.
110
111 Input is never overconsumed, so |next_in| and |available_in| could be passed
112 to the next consumer after decoding is complete. */
113 BrotliDecoderResult BrotliDecoderDecompressStream(
114 BrotliDecoderState* s, size_t* available_in, const uint8_t** next_in,
115 size_t* available_out, uint8_t** next_out, size_t* total_out);
116
117 /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
118 e.g. for custom static dictionaries for data formats.
119 Not to be confused with the built-in transformable dictionary of Brotli.
120 |size| should be less or equal to 2^24 (16MiB), otherwise the dictionary will
121 be ignored. The dictionary must exist in memory until decoding is done and
122 is owned by the caller. To use:
123 1) Allocate and initialize state with BrotliCreateInstance
124 2) Use BrotliSetCustomDictionary
125 3) Use BrotliDecompressStream
126 4) Clean up and free state with BrotliDestroyState
127 */
128 void BrotliDecoderSetCustomDictionary(
129 BrotliDecoderState* s, size_t size, const uint8_t* dict);
130
131 /* Returns true, if decoder has some unconsumed output.
132 Otherwise returns false. */
133 BROTLI_BOOL BrotliDecoderHasMoreOutput(const BrotliDecoderState* s);
134
135 /* Returns true, if decoder has already received some input bytes.
136 Otherwise returns false. */
137 BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* s);
138
139 /* Returns true, if decoder is in a state where we reached the end of the input
140 and produced all of the output; returns false otherwise. */
141 BROTLI_BOOL BrotliDecoderIsFinished(const BrotliDecoderState* s);
142
143 /* Returns detailed error code after BrotliDecompressStream returns
144 BROTLI_DECODER_RESULT_ERROR. */
145 BrotliDecoderErrorCode BrotliDecoderGetErrorCode(const BrotliDecoderState* s);
146
147 const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c);
148
149 /* DEPRECATED >>> */
150 typedef enum {
151 BROTLI_RESULT_ERROR = 0,
152 BROTLI_RESULT_SUCCESS = 1,
153 BROTLI_RESULT_NEEDS_MORE_INPUT = 2,
154 BROTLI_RESULT_NEEDS_MORE_OUTPUT = 3
155 } BrotliResult;
156 typedef enum {
157 #define _BROTLI_COMMA ,
158 #define _BROTLI_ERROR_CODE_ENUM_ITEM(PREFIX, NAME, CODE) \
159 BROTLI ## PREFIX ## NAME = CODE
160 BROTLI_DECODER_ERROR_CODES_LIST(_BROTLI_ERROR_CODE_ENUM_ITEM, _BROTLI_COMMA)
161 #undef _BROTLI_ERROR_CODE_ENUM_ITEM
162 #undef _BROTLI_COMMA
163 } BrotliErrorCode;
164 typedef struct BrotliStateStruct BrotliState;
165 BrotliState* BrotliCreateState(
166 brotli_alloc_func alloc, brotli_free_func free, void* opaque);
167 void BrotliDestroyState(BrotliState* state);
168 BROTLI_BOOL BrotliDecompressedSize(
169 size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size);
170 BrotliResult BrotliDecompressBuffer(
171 size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size,
172 uint8_t* decoded_buffer);
173 BrotliResult BrotliDecompressStream(
174 size_t* available_in, const uint8_t** next_in, size_t* available_out,
175 uint8_t** next_out, size_t* total_out, BrotliState* s);
176 void BrotliSetCustomDictionary(
177 size_t size, const uint8_t* dict, BrotliState* s);
178 BROTLI_BOOL BrotliStateIsStreamStart(const BrotliState* s);
179 BROTLI_BOOL BrotliStateIsStreamEnd(const BrotliState* s);
180 BrotliErrorCode BrotliGetErrorCode(const BrotliState* s);
181 const char* BrotliErrorString(BrotliErrorCode c);
182 /* <<< DEPRECATED */
183
184 #if defined(__cplusplus) || defined(c_plusplus)
185 } /* extern "C" */
186 #endif
187
188 #endif /* BROTLI_DEC_DECODE_H_ */