mirror of
https://github.com/google/brotli.git
synced 2024-11-21 19:20:09 +00:00
409 lines
13 KiB
Groff
Executable File
409 lines
13 KiB
Groff
Executable File
.TH "decode.h" 3 "Tue Feb 28 2017" "Brotli" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
decode.h \- API for Brotli decompression\&.
|
|
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.SS "Macros"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "#define \fBBROTLI_DECODER_ERROR_CODES_LIST\fP(BROTLI_ERROR_CODE, SEPARATOR) "
|
|
.br
|
|
.RI "\fITemplate that evaluates items of \fBBrotliDecoderErrorCode\fP\&. \fP"
|
|
.ti -1c
|
|
.RI "#define \fBBROTLI_LAST_ERROR_CODE\fP BROTLI_DECODER_ERROR_UNREACHABLE"
|
|
.br
|
|
.RI "\fIThe value of the last error code, negative integer\&. \fP"
|
|
.in -1c
|
|
.SS "Typedefs"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP"
|
|
.br
|
|
.RI "\fIOpaque structure that holds decoder state\&. \fP"
|
|
.in -1c
|
|
.SS "Enumerations"
|
|
.SS "Functions"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "\fBBrotliDecoderState\fP * \fBBrotliDecoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
|
|
.br
|
|
.RI "\fICreates an instance of \fBBrotliDecoderState\fP and initializes it\&. \fP"
|
|
.ti -1c
|
|
.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])"
|
|
.br
|
|
.RI "\fIPerforms one-shot memory-to-memory decompression\&. \fP"
|
|
.ti -1c
|
|
.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)"
|
|
.br
|
|
.RI "\fIDecompresses the input stream to the output stream\&. \fP"
|
|
.ti -1c
|
|
.RI "void \fBBrotliDecoderDestroyInstance\fP (\fBBrotliDecoderState\fP *state)"
|
|
.br
|
|
.RI "\fIDeinitializes and frees \fBBrotliDecoderState\fP instance\&. \fP"
|
|
.ti -1c
|
|
.RI "const char * \fBBrotliDecoderErrorString\fP (\fBBrotliDecoderErrorCode\fP c)"
|
|
.br
|
|
.RI "\fIConverts error code to a c-string\&. \fP"
|
|
.ti -1c
|
|
.RI "\fBBrotliDecoderErrorCode\fP \fBBrotliDecoderGetErrorCode\fP (const \fBBrotliDecoderState\fP *state)"
|
|
.br
|
|
.RI "\fIAcquires a detailed error code\&. \fP"
|
|
.ti -1c
|
|
.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderHasMoreOutput\fP (const \fBBrotliDecoderState\fP *state)"
|
|
.br
|
|
.RI "\fIChecks if decoder has more output\&. \fP"
|
|
.ti -1c
|
|
.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsFinished\fP (const \fBBrotliDecoderState\fP *state)"
|
|
.br
|
|
.RI "\fIChecks if decoder instance reached the final state\&. \fP"
|
|
.ti -1c
|
|
.RI "\fBBROTLI_BOOL\fP \fBBrotliDecoderIsUsed\fP (const \fBBrotliDecoderState\fP *state)"
|
|
.br
|
|
.RI "\fIChecks if instance has already consumed input\&. \fP"
|
|
.ti -1c
|
|
.RI "void \fBBrotliDecoderSetCustomDictionary\fP (\fBBrotliDecoderState\fP *state, size_t size, const uint8_t dict[size])"
|
|
.br
|
|
.RI "\fIPrepends LZ77 dictionary\&. \fP"
|
|
.ti -1c
|
|
.RI "const uint8_t * \fBBrotliDecoderTakeOutput\fP (\fBBrotliDecoderState\fP *state, size_t *size)"
|
|
.br
|
|
.RI "\fIAcquires pointer to internal output buffer\&. \fP"
|
|
.ti -1c
|
|
.RI "uint32_t \fBBrotliDecoderVersion\fP (void)"
|
|
.br
|
|
.RI "\fIGets a decoder library version\&. \fP"
|
|
.in -1c
|
|
.SH "Detailed Description"
|
|
.PP
|
|
API for Brotli decompression\&.
|
|
|
|
|
|
.SH "Macro Definition Documentation"
|
|
.PP
|
|
.SS "#define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR)"
|
|
|
|
.PP
|
|
Template that evaluates items of \fBBrotliDecoderErrorCode\fP\&. Example:
|
|
.PP
|
|
.nf
|
|
// Log Brotli error code\&.
|
|
switch (brotliDecoderErrorCode) {
|
|
#define CASE_(PREFIX, NAME, CODE) \
|
|
case BROTLI_DECODER ## PREFIX ## NAME: \
|
|
LOG(INFO) << "error code:" << #NAME; \
|
|
break;
|
|
#define NEWLINE_
|
|
BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_)
|
|
#undef CASE_
|
|
#undef NEWLINE_
|
|
default: LOG(FATAL) << "unknown brotli error code";
|
|
}
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.SS "#define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE"
|
|
|
|
.PP
|
|
The 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\&.
|
|
.SH "Typedef Documentation"
|
|
.PP
|
|
.SS "typedef struct BrotliDecoderStateStruct \fBBrotliDecoderState\fP"
|
|
|
|
.PP
|
|
Opaque structure that holds decoder state\&. Allocated and initialized with \fBBrotliDecoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliDecoderDestroyInstance\fP\&.
|
|
.SH "Enumeration Type Documentation"
|
|
.PP
|
|
.SS "enum \fBBrotliDecoderErrorCode\fP"
|
|
|
|
.PP
|
|
Error code for detailed logging / production debugging\&. See \fBBrotliDecoderGetErrorCode\fP and \fBBROTLI_LAST_ERROR_CODE\fP\&.
|
|
.SS "enum \fBBrotliDecoderResult\fP"
|
|
|
|
.PP
|
|
Result type for \fBBrotliDecoderDecompress\fP and \fBBrotliDecoderDecompressStream\fP functions\&.
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\fB\fIBROTLI_DECODER_RESULT_ERROR \fP\fP
|
|
Decoding error, e\&.g\&. corrupted input or memory allocation problem\&.
|
|
.TP
|
|
\fB\fIBROTLI_DECODER_RESULT_SUCCESS \fP\fP
|
|
Decoding successfully completed\&.
|
|
.TP
|
|
\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT \fP\fP
|
|
Partially done; should be called again with more input\&.
|
|
.TP
|
|
\fB\fIBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT \fP\fP
|
|
Partially done; should be called again with more output\&.
|
|
.SH "Function Documentation"
|
|
.PP
|
|
.SS "\fBBrotliDecoderState\fP* BrotliDecoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
|
|
|
|
.PP
|
|
Creates 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\&.
|
|
.PP
|
|
\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\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIalloc_func\fP custom memory allocation function
|
|
.br
|
|
\fIfree_func\fP custom memory fee function
|
|
.br
|
|
\fIopaque\fP custom memory manager handle
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fC0\fP if instance can not be allocated or initialized
|
|
.PP
|
|
pointer to initialized \fBBrotliDecoderState\fP otherwise
|
|
.RE
|
|
.PP
|
|
|
|
.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])"
|
|
|
|
.PP
|
|
Performs 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\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIencoded_size\fP size of \fCencoded_buffer\fP
|
|
.br
|
|
\fIencoded_buffer\fP compressed data buffer with at least \fCencoded_size\fP addressable bytes
|
|
.br
|
|
\fIdecoded_size\fP \fBin:\fP size of \fCdecoded_buffer\fP;
|
|
.br
|
|
\fBout:\fP length of decompressed data written to \fCdecoded_buffer\fP
|
|
.br
|
|
\fIdecoded_buffer\fP decompressed data destination buffer
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, or \fCdecoded_buffer\fP is not large enough;
|
|
.PP
|
|
\fBBROTLI_DECODER_RESULT_SUCCESS\fP otherwise
|
|
.RE
|
|
.PP
|
|
|
|
.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)"
|
|
|
|
.PP
|
|
Decompresses 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\&.
|
|
.PP
|
|
After 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\&.
|
|
.PP
|
|
\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\&.
|
|
.PP
|
|
\fBNote:\fP
|
|
.RS 4
|
|
Input is never overconsumed, so \fCnext_in\fP and \fCavailable_in\fP could be passed to the next consumer after decoding is complete\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.br
|
|
\fIavailable_in\fP \fBin:\fP amount of available input;
|
|
.br
|
|
\fBout:\fP amount of unused input
|
|
.br
|
|
\fInext_in\fP pointer to the next compressed byte
|
|
.br
|
|
\fIavailable_out\fP \fBin:\fP length of output buffer;
|
|
.br
|
|
\fBout:\fP remaining size of output buffer
|
|
.br
|
|
\fInext_out\fP output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP
|
|
.br
|
|
\fItotal_out\fP number of bytes decompressed so far; can be \fCNULL\fP
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fBBROTLI_DECODER_RESULT_ERROR\fP if input is corrupted, memory allocation failed, arguments were invalid, etc\&.; use \fBBrotliDecoderGetErrorCode\fP to get detailed error code
|
|
.PP
|
|
\fBBROTLI_DECODER_RESULT_NEEDS_MORE_INPUT\fP decoding is blocked until more output space is provided
|
|
.PP
|
|
\fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP decoding is blocked until more input data is provided
|
|
.PP
|
|
\fBBROTLI_DECODER_RESULT_SUCCESS\fP decoding is finished, no more input might be consumed and no more output will be produced
|
|
.RE
|
|
.PP
|
|
|
|
.SS "void BrotliDecoderDestroyInstance (\fBBrotliDecoderState\fP * state)"
|
|
|
|
.PP
|
|
Deinitializes and frees \fBBrotliDecoderState\fP instance\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance to be cleaned up and deallocated
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBBrotliDecoderErrorCode\fP BrotliDecoderGetErrorCode (const \fBBrotliDecoderState\fP * state)"
|
|
|
|
.PP
|
|
Acquires a detailed error code\&. Should be used only after \fBBrotliDecoderDecompressStream\fP returns \fBBROTLI_DECODER_RESULT_ERROR\fP\&.
|
|
.PP
|
|
See also \fBBrotliDecoderErrorString\fP
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
last saved error code
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBBROTLI_BOOL\fP BrotliDecoderHasMoreOutput (const \fBBrotliDecoderState\fP * state)"
|
|
|
|
.PP
|
|
Checks if decoder has more output\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fBBROTLI_TRUE\fP, if decoder has some unconsumed output
|
|
.PP
|
|
\fBBROTLI_FALSE\fP otherwise
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsFinished (const \fBBrotliDecoderState\fP * state)"
|
|
|
|
.PP
|
|
Checks if decoder instance reached the final state\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fBBROTLI_TRUE\fP if decoder is in a state where it reached the end of the input and produced all of the output
|
|
.PP
|
|
\fBBROTLI_FALSE\fP otherwise
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBBROTLI_BOOL\fP BrotliDecoderIsUsed (const \fBBrotliDecoderState\fP * state)"
|
|
|
|
.PP
|
|
Checks if instance has already consumed input\&. Instance that returns \fBBROTLI_FALSE\fP is considered 'fresh' and could be reused\&.
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
\fBBROTLI_TRUE\fP if decoder has already used some input bytes
|
|
.PP
|
|
\fBBROTLI_FALSE\fP otherwise
|
|
.RE
|
|
.PP
|
|
|
|
.SS "void BrotliDecoderSetCustomDictionary (\fBBrotliDecoderState\fP * state, size_t size, const uint8_t dict[size])"
|
|
|
|
.PP
|
|
Prepends LZ77 dictionary\&. Fills the fresh \fBBrotliDecoderState\fP with additional data corpus for LZ77 backward references\&.
|
|
.PP
|
|
\fBNote:\fP
|
|
.RS 4
|
|
Not to be confused with the static dictionary (see RFC7932 section 8)\&.
|
|
.RE
|
|
.PP
|
|
\fBWarning:\fP
|
|
.RS 4
|
|
The dictionary must exist in memory until decoding is done and is owned by the caller\&.
|
|
.RE
|
|
.PP
|
|
Workflow:
|
|
.IP "1." 4
|
|
Allocate and initialize state with \fBBrotliDecoderCreateInstance\fP
|
|
.IP "2." 4
|
|
Invoke \fBBrotliDecoderSetCustomDictionary\fP
|
|
.IP "3." 4
|
|
Use \fBBrotliDecoderDecompressStream\fP
|
|
.IP "4." 4
|
|
Clean up and free state with \fBBrotliDecoderDestroyInstance\fP
|
|
.PP
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.br
|
|
\fIsize\fP length of \fCdict\fP; should be less or equal to 2^24 (16MiB), otherwise the dictionary will be ignored
|
|
.br
|
|
\fIdict\fP 'dictionary'; \fBMUST\fP be the same as used during compression
|
|
.RE
|
|
.PP
|
|
|
|
.SS "const uint8_t* BrotliDecoderTakeOutput (\fBBrotliDecoderState\fP * state, size_t * size)"
|
|
|
|
.PP
|
|
Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient:
|
|
.IP "1." 4
|
|
push data to \fBBrotliDecoderDecompressStream\fP, until \fBBROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT\fP is reported
|
|
.IP "2." 4
|
|
use \fBBrotliDecoderTakeOutput\fP to peek bytes and copy to language-specific entity
|
|
.PP
|
|
.PP
|
|
Also 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)\&.
|
|
.PP
|
|
\fBAttention:\fP
|
|
.RS 4
|
|
After 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\&.
|
|
.RE
|
|
.PP
|
|
\fBNote:\fP
|
|
.RS 4
|
|
Decoder 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\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters:\fP
|
|
.RS 4
|
|
\fIstate\fP decoder instance
|
|
.br
|
|
\fIsize\fP \fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled;
|
|
.br
|
|
\fBout:\fP amount of data pointed by returned pointer and considered consumed;
|
|
.br
|
|
out value is never greater than in value, unless it is \fC0\fP
|
|
.RE
|
|
.PP
|
|
\fBReturns:\fP
|
|
.RS 4
|
|
pointer to output data
|
|
.RE
|
|
.PP
|
|
|
|
.SS "uint32_t BrotliDecoderVersion (void)"
|
|
|
|
.PP
|
|
Gets a decoder library version\&. Look at BROTLI_VERSION for more information\&.
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for Brotli from the source code\&.
|