Commit | Line | Data |
---|---|---|
f9995f31 MG |
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 "./state.h" | |
13 | #include "./streams.h" | |
14 | #include "./types.h" | |
15 | ||
16 | #if defined(__cplusplus) || defined(c_plusplus) | |
17 | extern "C" { | |
18 | #endif | |
19 | ||
20 | typedef enum { | |
21 | /* Decoding error, e.g. corrupt input or no memory */ | |
22 | BROTLI_RESULT_ERROR = 0, | |
23 | /* Successfully completely done */ | |
24 | BROTLI_RESULT_SUCCESS = 1, | |
25 | /* Partially done, but must be called again with more input */ | |
26 | BROTLI_RESULT_NEEDS_MORE_INPUT = 2, | |
27 | /* Partially done, but must be called again with more output */ | |
28 | BROTLI_RESULT_NEEDS_MORE_OUTPUT = 3 | |
29 | } BrotliResult; | |
30 | ||
31 | /* BROTLI_FAILURE macro unwraps to BROTLI_RESULT_ERROR in non-debug build. */ | |
32 | /* In debug build it dumps file name, line and pretty function name. */ | |
33 | #if defined(_MSC_VER) || !defined(BROTLI_DEBUG) | |
34 | #define BROTLI_FAILURE() BROTLI_RESULT_ERROR | |
35 | #else | |
36 | #define BROTLI_FAILURE() \ | |
37 | BrotliFailure(__FILE__, __LINE__, __PRETTY_FUNCTION__) | |
38 | static inline BrotliResult BrotliFailure(const char *f, int l, const char *fn) { | |
39 | fprintf(stderr, "ERROR at %s:%d (%s)\n", f, l, fn); | |
40 | fflush(stderr); | |
41 | return BROTLI_RESULT_ERROR; | |
42 | } | |
43 | #endif | |
44 | ||
45 | /* Creates the instance of BrotliState and initializes it. alloc_func and | |
46 | free_func MUST be both zero or both non-zero. In the case they are both zero, | |
47 | default memory allocators are used. opaque parameter is passed to alloc_func | |
48 | and free_func when they are called. */ | |
49 | BrotliState* BrotliCreateState( | |
50 | brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque); | |
51 | ||
52 | /* Deinitializes and frees BrotliState instance. */ | |
53 | void BrotliDestroyState(BrotliState* state); | |
54 | ||
55 | /* Sets *decoded_size to the decompressed size of the given encoded stream. */ | |
56 | /* This function only works if the encoded buffer has a single meta block, */ | |
57 | /* or if it has two meta-blocks, where the first is uncompressed and the */ | |
58 | /* second is empty. */ | |
59 | /* Returns 1 on success, 0 on failure. */ | |
60 | int BrotliDecompressedSize(size_t encoded_size, | |
61 | const uint8_t* encoded_buffer, | |
62 | size_t* decoded_size); | |
63 | ||
64 | /* Decompresses the data in encoded_buffer into decoded_buffer, and sets */ | |
65 | /* *decoded_size to the decompressed length. */ | |
66 | BrotliResult BrotliDecompressBuffer(size_t encoded_size, | |
67 | const uint8_t* encoded_buffer, | |
68 | size_t* decoded_size, | |
69 | uint8_t* decoded_buffer); | |
70 | ||
71 | /* Same as above, but uses the specified input and output callbacks instead */ | |
72 | /* of reading from and writing to pre-allocated memory buffers. */ | |
73 | /* DEPRECATED */ | |
74 | BrotliResult BrotliDecompress(BrotliInput input, BrotliOutput output); | |
75 | ||
76 | /* Same as above, but supports the caller to call the decoder repeatedly with | |
77 | partial data to support streaming. The state must be initialized with | |
78 | BrotliStateInit and reused with every call for the same stream. | |
79 | Return values: | |
80 | 0: failure. | |
81 | 1: success, and done. | |
82 | 2: success so far, end not reached so should call again with more input. | |
83 | The finish parameter is used as follows, for a series of calls with the | |
84 | same state: | |
85 | 0: Every call except the last one must be called with finish set to 0. The | |
86 | last call may have finish set to either 0 or 1. Only if finish is 0, can | |
87 | the function return 2. It may also return 0 or 1, in that case no more | |
88 | calls (even with finish 1) may be made. | |
89 | 1: Only the last call may have finish set to 1. It's ok to give empty input | |
90 | if all input was already given to previous calls. It is also ok to have | |
91 | only one single call in total, with finish 1, and with all input | |
92 | available immediately. That matches the non-streaming case. If finish is | |
93 | 1, the function can only return 0 or 1, never 2. After a finish, no more | |
94 | calls may be done. | |
95 | After everything is done, the state must be cleaned with BrotliStateCleanup | |
96 | to free allocated resources. | |
97 | The given BrotliOutput must always accept all output and make enough space, | |
98 | it returning a smaller value than the amount of bytes to write always results | |
99 | in an error. | |
100 | */ | |
101 | /* DEPRECATED */ | |
102 | BrotliResult BrotliDecompressStreaming(BrotliInput input, BrotliOutput output, | |
103 | int finish, BrotliState* s); | |
104 | ||
105 | /* Same as above, but with memory buffers. | |
106 | Must be called with an allocated input buffer in *next_in and an allocated | |
107 | output buffer in *next_out. The values *available_in and *available_out | |
108 | must specify the allocated size in *next_in and *next_out respectively. | |
109 | The value *total_out must be 0 initially, and will be summed with the | |
110 | amount of output bytes written after each call, so that at the end it | |
111 | gives the complete decoded size. | |
112 | After each call, *available_in will be decremented by the amount of input | |
113 | bytes consumed, and the *next_in pointer will be incremented by that amount. | |
114 | Similarly, *available_out will be decremented by the amount of output | |
115 | bytes written, and the *next_out pointer will be incremented by that | |
116 | amount. | |
117 | ||
118 | The input may be partial. With each next function call, *next_in and | |
119 | *available_in must be updated to point to a next part of the compressed | |
120 | input. The current implementation will always consume all input unless | |
121 | an error occurs, so normally *available_in will always be 0 after | |
122 | calling this function and the next adjacent part of input is desired. | |
123 | ||
124 | In the current implementation, the function requires that there is enough | |
125 | output buffer size to write all currently processed input, so | |
126 | *available_out must be large enough. Since the function updates *next_out | |
127 | each time, as long as the output buffer is large enough you can keep | |
128 | reusing this variable. It is also possible to update *next_out and | |
129 | *available_out yourself before a next call, e.g. to point to a new larger | |
130 | buffer. | |
131 | */ | |
132 | /* DEPRECATED */ | |
133 | BrotliResult BrotliDecompressBufferStreaming(size_t* available_in, | |
134 | const uint8_t** next_in, | |
135 | int finish, | |
136 | size_t* available_out, | |
137 | uint8_t** next_out, | |
138 | size_t* total_out, | |
139 | BrotliState* s); | |
140 | ||
141 | BrotliResult BrotliDecompressStream(size_t* available_in, | |
142 | const uint8_t** next_in, | |
143 | size_t* available_out, | |
144 | uint8_t** next_out, | |
145 | size_t* total_out, | |
146 | BrotliState* s); | |
147 | ||
148 | /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer, | |
149 | e.g. for custom static dictionaries for data formats. | |
150 | Not to be confused with the built-in transformable dictionary of Brotli. | |
151 | The dictionary must exist in memory until decoding is done and is owned by | |
152 | the caller. To use: | |
153 | -initialize state with BrotliStateInit | |
154 | -use BrotliSetCustomDictionary | |
155 | -use BrotliDecompressBufferStreaming | |
156 | -clean up with BrotliStateCleanup | |
157 | */ | |
158 | void BrotliSetCustomDictionary( | |
159 | size_t size, const uint8_t* dict, BrotliState* s); | |
160 | ||
161 | ||
162 | #if defined(__cplusplus) || defined(c_plusplus) | |
163 | } /* extern "C" */ | |
164 | #endif | |
165 | ||
166 | #endif /* BROTLI_DEC_DECODE_H_ */ |