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