blob: 7b8581cc2cb1384800dd4ad1f31fe6273c73eb6d [file] [log] [blame]
Tianjie Xua5dcb7c2018-09-25 12:25:15 -07001.TH "decode.h" 3 "Thu Feb 22 2018" "Brotli" \" -*- nroff -*-
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +01002.ad l
3.nh
4.SH NAME
5decode.h \- API for Brotli decompression\&.
6
7.SH SYNOPSIS
8.br
9.PP
10.SS "Macros"
11
12.in +1c
13.ti -1c
14.RI "#define \fBBROTLI_DECODER_ERROR_CODES_LIST\fP(BROTLI_ERROR_CODE, SEPARATOR) "
15.br
16.RI "\fITemplate that evaluates items of \fBBrotliDecoderErrorCode\fP\&. \fP"
17.ti -1c
18.RI "#define \fBBROTLI_LAST_ERROR_CODE\fP BROTLI_DECODER_ERROR_UNREACHABLE"
19.br
20.RI "\fIThe value of the last error code, negative integer\&. \fP"
21.in -1c
22.SS "Typedefs"
23
24.in +1c
25.ti -1c
Eugene Kliuchnikov05d5f3d2017-06-13 12:52:56 +020026.RI "typedef enum \fBBrotliDecoderParameter\fP \fBBrotliDecoderParameter\fP"
27.br
28.RI "\fIOptions to be used with \fBBrotliDecoderSetParameter\fP\&. \fP"
29.ti -1c
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +010030.RI "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP"
31.br
32.RI "\fIOpaque structure that holds decoder state\&. \fP"
33.in -1c
34.SS "Enumerations"
35.SS "Functions"
36
37.in +1c
38.ti -1c
39.RI "\fBBrotliDecoderState\fP * \fBBrotliDecoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
40.br
41.RI "\fICreates an instance of \fBBrotliDecoderState\fP and initializes it\&. \fP"
42.ti -1c
43.RI "\fBBrotliDecoderResult\fP \fBBrotliDecoderDecompress\fP (size_t encoded_size, const uint8_t encoded_buffer[encoded_size], size_t *decoded_size, uint8_t decoded_buffer[*decoded_size])"
44.br
45.RI "\fIPerforms one-shot memory-to-memory decompression\&. \fP"
46.ti -1c
47.RI "\fBBrotliDecoderResult\fP \fBBrotliDecoderDecompressStream\fP (\fBBrotliDecoderState\fP *state, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)"
48.br
49.RI "\fIDecompresses the input stream to the output stream\&. \fP"
50.ti -1c
51.RI "void \fBBrotliDecoderDestroyInstance\fP (\fBBrotliDecoderState\fP *state)"
52.br
53.RI "\fIDeinitializes and frees \fBBrotliDecoderState\fP instance\&. \fP"
54.ti -1c
55.RI "const char * \fBBrotliDecoderErrorString\fP (\fBBrotliDecoderErrorCode\fP c)"
56.br
57.RI "\fIConverts error code to a c-string\&. \fP"
58.ti -1c
59.RI "\fBBrotliDecoderErrorCode\fP \fBBrotliDecoderGetErrorCode\fP (const \fBBrotliDecoderState\fP *state)"
60.br
61.RI "\fIAcquires a detailed error code\&. \fP"
62.ti -1c
63.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderHasMoreOutput\fP (const \fBBrotliDecoderState\fP *state)"
64.br
65.RI "\fIChecks if decoder has more output\&. \fP"
66.ti -1c
67.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsFinished\fP (const \fBBrotliDecoderState\fP *state)"
68.br
69.RI "\fIChecks if decoder instance reached the final state\&. \fP"
70.ti -1c
71.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsUsed\fP (const \fBBrotliDecoderState\fP *state)"
72.br
73.RI "\fIChecks if instance has already consumed input\&. \fP"
74.ti -1c
Eugene Kliuchnikov05d5f3d2017-06-13 12:52:56 +020075.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderSetParameter\fP (\fBBrotliDecoderState\fP *state, \fBBrotliDecoderParameter\fP param, uint32_t value)"
76.br
77.RI "\fISets the specified parameter to the given decoder instance\&. \fP"
78.ti -1c
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +010079.RI "const uint8_t * \fBBrotliDecoderTakeOutput\fP (\fBBrotliDecoderState\fP *state, size_t *size)"
80.br
81.RI "\fIAcquires pointer to internal output buffer\&. \fP"
82.ti -1c
83.RI "uint32_t \fBBrotliDecoderVersion\fP (void)"
84.br
85.RI "\fIGets a decoder library version\&. \fP"
86.in -1c
87.SH "Detailed Description"
88.PP
89API for Brotli decompression\&.
90
91
92.SH "Macro Definition Documentation"
93.PP
94.SS "#define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR)"
95
96.PP
97Template that evaluates items of \fBBrotliDecoderErrorCode\fP\&. Example:
98.PP
99.nf
100// Log Brotli error code\&.
101switch (brotliDecoderErrorCode) {
102#define CASE_(PREFIX, NAME, CODE) \
103 case BROTLI_DECODER ## PREFIX ## NAME: \
104 LOG(INFO) << "error code:" << #NAME; \
105 break;
106#define NEWLINE_
107BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_)
108#undef CASE_
109#undef NEWLINE_
110 default: LOG(FATAL) << "unknown brotli error code";
111}
112
113.fi
114.PP
115
116.SS "#define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE"
117
118.PP
119The value of the last error code, negative integer\&. All other error code values are in the range from \fBBROTLI_LAST_ERROR_CODE\fP to \fC-1\fP\&. There are also 4 other possible non-error codes \fC0\fP \&.\&. \fC3\fP in \fBBrotliDecoderErrorCode\fP enumeration\&.
120.SH "Typedef Documentation"
121.PP
Eugene Kliuchnikov05d5f3d2017-06-13 12:52:56 +0200122.SS "typedef enum \fBBrotliDecoderParameter\fP \fBBrotliDecoderParameter\fP"
123
124.PP
125Options to be used with \fBBrotliDecoderSetParameter\fP\&.
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100126.SS "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP"
127
128.PP
129Opaque structure that holds decoder state\&. Allocated and initialized with \fBBrotliDecoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliDecoderDestroyInstance\fP\&.
130.SH "Enumeration Type Documentation"
131.PP
132.SS "enum \fBBrotliDecoderErrorCode\fP"
133
134.PP
135Error code for detailed logging / production debugging\&. See \fBBrotliDecoderGetErrorCode\fP and \fBBROTLI_LAST_ERROR_CODE\fP\&.
Eugene Kliuchnikov05d5f3d2017-06-13 12:52:56 +0200136.SS "enum \fBBrotliDecoderParameter\fP"
137
138.PP
139Options to be used with \fBBrotliDecoderSetParameter\fP\&.
140.PP
141\fBEnumerator\fP
142.in +1c
143.TP
144\fB\fIBROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION \fP\fP
145Disable 'canny' ring buffer allocation strategy\&. Ring buffer is allocated according to window size, despite the real size of the content\&.
Tianjie Xua5dcb7c2018-09-25 12:25:15 -0700146.TP
147\fB\fIBROTLI_DECODER_PARAM_LARGE_WINDOW \fP\fP
148Flag that determines if 'Large Window Brotli' is used\&.
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100149.SS "enum \fBBrotliDecoderResult\fP"
150
151.PP
152Result type for \fBBrotliDecoderDecompress\fP and \fBBrotliDecoderDecompressStream\fP functions\&.
153.PP
154\fBEnumerator\fP
155.in +1c
156.TP
157\fB\fIBROTLI_DECODER_RESULT_ERROR \fP\fP
158Decoding error, e\&.g\&. corrupted input or memory allocation problem\&.
159.TP
160\fB\fIBROTLI_DECODER_RESULT_SUCCESS \fP\fP
161Decoding successfully completed\&.
162.TP
163\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT \fP\fP
164Partially done; should be called again with more input\&.
165.TP
166\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT \fP\fP
167Partially done; should be called again with more output\&.
168.SH "Function Documentation"
169.PP
170.SS "\fBBrotliDecoderState\fP* BrotliDecoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
171
172.PP
173Creates an instance of \fBBrotliDecoderState\fP and initializes it\&. The instance can be used once for decoding and should then be destroyed with \fBBrotliDecoderDestroyInstance\fP, it cannot be reused for a new decoding session\&.
174.PP
Tianjie Xua5dcb7c2018-09-25 12:25:15 -0700175\fCalloc_func\fP and \fCfree_func\fP \fBMUST\fP be both zero or both non-zero\&. In the case they are both zero, default memory allocators are used\&. \fCopaque\fP is passed to \fCalloc_func\fP and \fCfree_func\fP when they are called\&. \fCfree_func\fP has to return without doing anything when asked to free a NULL pointer\&.
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100176.PP
177\fBParameters:\fP
178.RS 4
179\fIalloc_func\fP custom memory allocation function
180.br
Tianjie Xua5dcb7c2018-09-25 12:25:15 -0700181\fIfree_func\fP custom memory free function
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100182.br
183\fIopaque\fP custom memory manager handle
184.RE
185.PP
186\fBReturns:\fP
187.RS 4
188\fC0\fP if instance can not be allocated or initialized
189.PP
190pointer to initialized \fBBrotliDecoderState\fP otherwise
191.RE
192.PP
193
194.SS "\fBBrotliDecoderResult\fP BrotliDecoderDecompress (size_t encoded_size, const uint8_t encoded_buffer[encoded_size], size_t * decoded_size, uint8_t decoded_buffer[*decoded_size])"
195
196.PP
197Performs one-shot memory-to-memory decompression\&. Decompresses the data in \fCencoded_buffer\fP into \fCdecoded_buffer\fP, and sets \fC*decoded_size\fP to the decompressed length\&.
198.PP
199\fBParameters:\fP
200.RS 4
201\fIencoded_size\fP size of \fCencoded_buffer\fP
202.br
203\fIencoded_buffer\fP compressed data buffer with at least \fCencoded_size\fP addressable bytes
204.br
205\fIdecoded_size\fP \fBin:\fP size of \fCdecoded_buffer\fP;
206.br
207 \fBout:\fP length of decompressed data written to \fCdecoded_buffer\fP
208.br
209\fIdecoded_buffer\fP decompressed data destination buffer
210.RE
211.PP
212\fBReturns:\fP
213.RS 4
214\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, or \fCdecoded_buffer\fP is not large enough;
215.PP
216\fBBROTLI_DECODER_RESULT_SUCCESS\fP otherwise
217.RE
218.PP
219
220.SS "\fBBrotliDecoderResult\fP BrotliDecoderDecompressStream (\fBBrotliDecoderState\fP * state, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)"
221
222.PP
223Decompresses the input stream to the output stream\&. The values \fC*available_in\fP and \fC*available_out\fP must specify the number of bytes addressable at \fC*next_in\fP and \fC*next_out\fP respectively\&. When \fC*available_out\fP is \fC0\fP, \fCnext_out\fP is allowed to be \fCNULL\fP\&.
224.PP
225After each call, \fC*available_in\fP will be decremented by the amount of input bytes consumed, and the \fC*next_in\fP pointer will be incremented by that amount\&. Similarly, \fC*available_out\fP will be decremented by the amount of output bytes written, and the \fC*next_out\fP pointer will be incremented by that amount\&.
226.PP
227\fCtotal_out\fP, if it is not a null-pointer, will be set to the number of bytes decompressed since the last \fCstate\fP initialization\&.
228.PP
229\fBNote:\fP
230.RS 4
231Input is never overconsumed, so \fCnext_in\fP and \fCavailable_in\fP could be passed to the next consumer after decoding is complete\&.
232.RE
233.PP
234\fBParameters:\fP
235.RS 4
236\fIstate\fP decoder instance
237.br
238\fIavailable_in\fP \fBin:\fP amount of available input;
239.br
240 \fBout:\fP amount of unused input
241.br
242\fInext_in\fP pointer to the next compressed byte
243.br
244\fIavailable_out\fP \fBin:\fP length of output buffer;
245.br
246 \fBout:\fP remaining size of output buffer
247.br
248\fInext_out\fP output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP
249.br
250\fItotal_out\fP number of bytes decompressed so far; can be \fCNULL\fP
251.RE
252.PP
253\fBReturns:\fP
254.RS 4
255\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, arguments were invalid, etc\&.; use \fBBrotliDecoderGetErrorCode\fP to get detailed error code
256.PP
Eugene Kliuchnikov03739d22017-05-29 17:55:14 +0200257\fBBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT\fP decoding is blocked until more input data is provided
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100258.PP
Eugene Kliuchnikov03739d22017-05-29 17:55:14 +0200259\fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP decoding is blocked until more output space is provided
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100260.PP
261\fBBROTLI_DECODER_RESULT_SUCCESS\fP decoding is finished, no more input might be consumed and no more output will be produced
262.RE
263.PP
264
265.SS "void BrotliDecoderDestroyInstance (\fBBrotliDecoderState\fP * state)"
266
267.PP
268Deinitializes and frees \fBBrotliDecoderState\fP instance\&.
269.PP
270\fBParameters:\fP
271.RS 4
272\fIstate\fP decoder instance to be cleaned up and deallocated
273.RE
274.PP
275
276.SS "\fBBrotliDecoderErrorCode\fP BrotliDecoderGetErrorCode (const \fBBrotliDecoderState\fP * state)"
277
278.PP
279Acquires a detailed error code\&. Should be used only after \fBBrotliDecoderDecompressStream\fP returns \fBBROTLI_DECODER_RESULT_ERROR\fP\&.
280.PP
281See also \fBBrotliDecoderErrorString\fP
282.PP
283\fBParameters:\fP
284.RS 4
285\fIstate\fP decoder instance
286.RE
287.PP
288\fBReturns:\fP
289.RS 4
290last saved error code
291.RE
292.PP
293
294.SS "\fBBROTLI_BOOL\fP BrotliDecoderHasMoreOutput (const \fBBrotliDecoderState\fP * state)"
295
296.PP
297Checks if decoder has more output\&.
298.PP
299\fBParameters:\fP
300.RS 4
301\fIstate\fP decoder instance
302.RE
303.PP
304\fBReturns:\fP
305.RS 4
306\fBBROTLI_TRUE\fP, if decoder has some unconsumed output
307.PP
308\fBBROTLI_FALSE\fP otherwise
309.RE
310.PP
311
312.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsFinished (const \fBBrotliDecoderState\fP * state)"
313
314.PP
315Checks if decoder instance reached the final state\&.
316.PP
317\fBParameters:\fP
318.RS 4
319\fIstate\fP decoder instance
320.RE
321.PP
322\fBReturns:\fP
323.RS 4
324\fBBROTLI_TRUE\fP if decoder is in a state where it reached the end of the input and produced all of the output
325.PP
326\fBBROTLI_FALSE\fP otherwise
327.RE
328.PP
329
330.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsUsed (const \fBBrotliDecoderState\fP * state)"
331
332.PP
333Checks if instance has already consumed input\&. Instance that returns \fBBROTLI_FALSE\fP is considered 'fresh' and could be reused\&.
334.PP
335\fBParameters:\fP
336.RS 4
337\fIstate\fP decoder instance
338.RE
339.PP
340\fBReturns:\fP
341.RS 4
342\fBBROTLI_TRUE\fP if decoder has already used some input bytes
343.PP
344\fBBROTLI_FALSE\fP otherwise
345.RE
346.PP
347
Eugene Kliuchnikov05d5f3d2017-06-13 12:52:56 +0200348.SS "\fBBROTLI_BOOL\fP BrotliDecoderSetParameter (\fBBrotliDecoderState\fP * state, \fBBrotliDecoderParameter\fP param, uint32_t value)"
349
350.PP
351Sets the specified parameter to the given decoder instance\&.
352.PP
353\fBParameters:\fP
354.RS 4
355\fIstate\fP decoder instance
356.br
357\fIparam\fP parameter to set
358.br
359\fIvalue\fP new parameter value
360.RE
361.PP
362\fBReturns:\fP
363.RS 4
364\fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid
365.PP
366\fBBROTLI_TRUE\fP if value is accepted
367.RE
368.PP
369
Eugene Kliuchnikovc931e572017-02-28 16:59:52 +0100370.SS "const uint8_t* BrotliDecoderTakeOutput (\fBBrotliDecoderState\fP * state, size_t * size)"
371
372.PP
373Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient:
374.IP "1." 4
375push data to \fBBrotliDecoderDecompressStream\fP, until \fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP is reported
376.IP "2." 4
377use \fBBrotliDecoderTakeOutput\fP to peek bytes and copy to language-specific entity
378.PP
379.PP
380Also this could be useful if there is an output stream that is able to consume all the provided data (e\&.g\&. when data is saved to file system)\&.
381.PP
382\fBAttention:\fP
383.RS 4
384After every call to \fBBrotliDecoderTakeOutput\fP \fC*size\fP bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well\&.
385.RE
386.PP
387\fBNote:\fP
388.RS 4
389Decoder output is not guaranteed to be contiguous\&. This means that after the size-unrestricted call to \fBBrotliDecoderTakeOutput\fP, immediate next call to \fBBrotliDecoderTakeOutput\fP may return more data\&.
390.RE
391.PP
392\fBParameters:\fP
393.RS 4
394\fIstate\fP decoder instance
395.br
396\fIsize\fP \fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled;
397.br
398 \fBout:\fP amount of data pointed by returned pointer and considered consumed;
399.br
400 out value is never greater than in value, unless it is \fC0\fP
401.RE
402.PP
403\fBReturns:\fP
404.RS 4
405pointer to output data
406.RE
407.PP
408
409.SS "uint32_t BrotliDecoderVersion (void)"
410
411.PP
412Gets a decoder library version\&. Look at BROTLI_VERSION for more information\&.
413.SH "Author"
414.PP
415Generated automatically by Doxygen for Brotli from the source code\&.