mirror of
https://github.com/google/brotli.git
synced 2024-11-21 11:10:04 +00:00
Move java/ to java/org/brotli/ to fix sources.jar structure (#517)
Also added man pages to `docs/`
This commit is contained in:
Eugene Kliuchnikov
GitHub
parent
aaac88a1e0
commit
c931e576d2
408
docs/decode.h.3
Executable file
408
docs/decode.h.3
Executable file
@ -0,0 +1,408 @@
|
||||
.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\&.
|
||||
592
docs/encode.h.3
Executable file
592
docs/encode.h.3
Executable file
@ -0,0 +1,592 @@
|
||||
.TH "encode.h" 3 "Tue Feb 28 2017" "Brotli" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
encode.h \- API for Brotli compression\&.
|
||||
|
||||
.SH SYNOPSIS
|
||||
.br
|
||||
.PP
|
||||
.SS "Macros"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_DEFAULT_MODE\fP \fBBROTLI_MODE_GENERIC\fP"
|
||||
.br
|
||||
.RI "\fIDefault value for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_DEFAULT_QUALITY\fP 11"
|
||||
.br
|
||||
.RI "\fIDefault value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_DEFAULT_WINDOW\fP 22"
|
||||
.br
|
||||
.RI "\fIDefault value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP 24"
|
||||
.br
|
||||
.RI "\fIMaximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MAX_QUALITY\fP 11"
|
||||
.br
|
||||
.RI "\fIMaximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MAX_WINDOW_BITS\fP 24"
|
||||
.br
|
||||
.RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP 16"
|
||||
.br
|
||||
.RI "\fIMinimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MIN_QUALITY\fP 0"
|
||||
.br
|
||||
.RI "\fIMinimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_MIN_WINDOW_BITS\fP 10"
|
||||
.br
|
||||
.RI "\fIMinimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
|
||||
.in -1c
|
||||
.SS "Typedefs"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
|
||||
.br
|
||||
.RI "\fIOptions for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
|
||||
.ti -1c
|
||||
.RI "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
|
||||
.br
|
||||
.RI "\fIOperations that can be performed by streaming encoder\&. \fP"
|
||||
.ti -1c
|
||||
.RI "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
|
||||
.br
|
||||
.RI "\fIOptions to be used with \fBBrotliEncoderSetParameter\fP\&. \fP"
|
||||
.ti -1c
|
||||
.RI "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
|
||||
.br
|
||||
.RI "\fIOpaque structure that holds encoder state\&. \fP"
|
||||
.in -1c
|
||||
.SS "Enumerations"
|
||||
.SS "Functions"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompress\fP (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t *encoded_size, uint8_t encoded_buffer[*encoded_size])"
|
||||
.br
|
||||
.RI "\fIPerforms one-shot memory-to-memory compression\&. \fP"
|
||||
.ti -1c
|
||||
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompressStream\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderOperation\fP op, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)"
|
||||
.br
|
||||
.RI "\fICompresses input stream to output stream\&. \fP"
|
||||
.ti -1c
|
||||
.RI "\fBBrotliEncoderState\fP * \fBBrotliEncoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
|
||||
.br
|
||||
.RI "\fICreates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fP"
|
||||
.ti -1c
|
||||
.RI "void \fBBrotliEncoderDestroyInstance\fP (\fBBrotliEncoderState\fP *state)"
|
||||
.br
|
||||
.RI "\fIDeinitializes and frees \fBBrotliEncoderState\fP instance\&. \fP"
|
||||
.ti -1c
|
||||
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderHasMoreOutput\fP (\fBBrotliEncoderState\fP *state)"
|
||||
.br
|
||||
.RI "\fIChecks if encoder has more output\&. \fP"
|
||||
.ti -1c
|
||||
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderIsFinished\fP (\fBBrotliEncoderState\fP *state)"
|
||||
.br
|
||||
.RI "\fIChecks if encoder instance reached the final state\&. \fP"
|
||||
.ti -1c
|
||||
.RI "size_t \fBBrotliEncoderMaxCompressedSize\fP (size_t input_size)"
|
||||
.br
|
||||
.RI "\fICalculates the output size bound for the given \fCinput_size\fP\&. \fP"
|
||||
.ti -1c
|
||||
.RI "void \fBBrotliEncoderSetCustomDictionary\fP (\fBBrotliEncoderState\fP *state, size_t size, const uint8_t dict[size])"
|
||||
.br
|
||||
.RI "\fIPrepends imaginary LZ77 dictionary\&. \fP"
|
||||
.ti -1c
|
||||
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderSetParameter\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
|
||||
.br
|
||||
.RI "\fISets the specified parameter to the given encoder instance\&. \fP"
|
||||
.ti -1c
|
||||
.RI "const uint8_t * \fBBrotliEncoderTakeOutput\fP (\fBBrotliEncoderState\fP *state, size_t *size)"
|
||||
.br
|
||||
.RI "\fIAcquires pointer to internal output buffer\&. \fP"
|
||||
.ti -1c
|
||||
.RI "uint32_t \fBBrotliEncoderVersion\fP (void)"
|
||||
.br
|
||||
.RI "\fIGets an encoder library version\&. \fP"
|
||||
.in -1c
|
||||
.SH "Detailed Description"
|
||||
.PP
|
||||
API for Brotli compression\&.
|
||||
|
||||
|
||||
.SH "Macro Definition Documentation"
|
||||
.PP
|
||||
.SS "#define BROTLI_DEFAULT_MODE \fBBROTLI_MODE_GENERIC\fP"
|
||||
|
||||
.PP
|
||||
Default value for \fBBROTLI_PARAM_MODE\fP parameter\&.
|
||||
.SS "#define BROTLI_DEFAULT_QUALITY 11"
|
||||
|
||||
.PP
|
||||
Default value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
|
||||
.SS "#define BROTLI_DEFAULT_WINDOW 22"
|
||||
|
||||
.PP
|
||||
Default value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
|
||||
.SS "#define BROTLI_MAX_INPUT_BLOCK_BITS 24"
|
||||
|
||||
.PP
|
||||
Maximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
|
||||
.SS "#define BROTLI_MAX_QUALITY 11"
|
||||
|
||||
.PP
|
||||
Maximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
|
||||
.SS "#define BROTLI_MAX_WINDOW_BITS 24"
|
||||
|
||||
.PP
|
||||
Maximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
|
||||
.PP
|
||||
\fBNote:\fP
|
||||
.RS 4
|
||||
equal to \fCBROTLI_MAX_DISTANCE_BITS\fP constant\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "#define BROTLI_MIN_INPUT_BLOCK_BITS 16"
|
||||
|
||||
.PP
|
||||
Minimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
|
||||
.SS "#define BROTLI_MIN_QUALITY 0"
|
||||
|
||||
.PP
|
||||
Minimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
|
||||
.SS "#define BROTLI_MIN_WINDOW_BITS 10"
|
||||
|
||||
.PP
|
||||
Minimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
|
||||
.SH "Typedef Documentation"
|
||||
.PP
|
||||
.SS "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
|
||||
|
||||
.PP
|
||||
Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
|
||||
.SS "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
|
||||
|
||||
.PP
|
||||
Operations that can be performed by streaming encoder\&.
|
||||
.SS "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
|
||||
|
||||
.PP
|
||||
Options to be used with \fBBrotliEncoderSetParameter\fP\&.
|
||||
.SS "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
|
||||
|
||||
.PP
|
||||
Opaque structure that holds encoder state\&. Allocated and initialized with \fBBrotliEncoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliEncoderDestroyInstance\fP\&.
|
||||
.SH "Enumeration Type Documentation"
|
||||
.PP
|
||||
.SS "enum \fBBrotliEncoderMode\fP"
|
||||
|
||||
.PP
|
||||
Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
|
||||
.PP
|
||||
\fBEnumerator\fP
|
||||
.in +1c
|
||||
.TP
|
||||
\fB\fIBROTLI_MODE_GENERIC \fP\fP
|
||||
Default compression mode\&. In this mode compressor does not know anything in advance about the properties of the input\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_MODE_TEXT \fP\fP
|
||||
Compression mode for UTF-8 formatted text input\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_MODE_FONT \fP\fP
|
||||
Compression mode used in WOFF 2\&.0\&.
|
||||
.SS "enum \fBBrotliEncoderOperation\fP"
|
||||
|
||||
.PP
|
||||
Operations that can be performed by streaming encoder\&.
|
||||
.PP
|
||||
\fBEnumerator\fP
|
||||
.in +1c
|
||||
.TP
|
||||
\fB\fIBROTLI_OPERATION_PROCESS \fP\fP
|
||||
Process input\&. Encoder may postpone producing output, until it has processed enough input\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_OPERATION_FLUSH \fP\fP
|
||||
Produce output for all processed input\&. Actual flush is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FLUSH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&.
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
Until flush is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
|
||||
.RE
|
||||
.PP
|
||||
When flush is complete, output data will be sufficient for decoder to reproduce all the given input\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_OPERATION_FINISH \fP\fP
|
||||
Finalize the stream\&. Actual finalization is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FLUSH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&.
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
Until finalization is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
|
||||
.RE
|
||||
.PP
|
||||
Helper function \fBBrotliEncoderIsFinished\fP checks if stream is finalized and output fully dumped\&.
|
||||
.PP
|
||||
Adding more input data to finalized stream is impossible\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_OPERATION_EMIT_METADATA \fP\fP
|
||||
Emit metadata block to stream\&. Metadata is opaque to Brotli: neither encoder, nor decoder processes this data or relies on it\&. It may be used to pass some extra information from encoder client to decoder client without interfering with main data stream\&.
|
||||
.PP
|
||||
\fBNote:\fP
|
||||
.RS 4
|
||||
Encoder may emit empty metadata blocks internally, to pad encoded stream to byte boundary\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
Until emitting metadata is complete client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
|
||||
.PP
|
||||
The whole content of input buffer is considered to be the content of metadata block\&. Do \fBNOT\fP \fIappend\fP metadata to input stream, before it is depleted with other operations\&.
|
||||
.RE
|
||||
.PP
|
||||
Stream is soft-flushed before metadata block is emitted\&. Metadata block \fBMUST\fP be no longer than than 16MiB\&.
|
||||
.SS "enum \fBBrotliEncoderParameter\fP"
|
||||
|
||||
.PP
|
||||
Options to be used with \fBBrotliEncoderSetParameter\fP\&.
|
||||
.PP
|
||||
\fBEnumerator\fP
|
||||
.in +1c
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_MODE \fP\fP
|
||||
Tune encoder for specific input\&. \fBBrotliEncoderMode\fP enumerates all available values\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_QUALITY \fP\fP
|
||||
The main compression speed-density lever\&. The higher the quality, the slower the compression\&. Range is from \fBBROTLI_MIN_QUALITY\fP to \fBBROTLI_MAX_QUALITY\fP\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_LGWIN \fP\fP
|
||||
Recommended sliding LZ77 window size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than window size\&.
|
||||
.PP
|
||||
Window size is \fC(1 << value) - 16\fP\&.
|
||||
.PP
|
||||
Range is from \fBBROTLI_MIN_WINDOW_BITS\fP to \fBBROTLI_MAX_WINDOW_BITS\fP\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_LGBLOCK \fP\fP
|
||||
Recommended input block size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than input block size\&.
|
||||
.PP
|
||||
Range is from \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP to \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP\&.
|
||||
.PP
|
||||
\fBNote:\fP
|
||||
.RS 4
|
||||
Bigger input block size allows better compression, but consumes more memory\&.
|
||||
.br
|
||||
The rough formula of memory used for temporary input storage is \fC3 << lgBlock\fP\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING \fP\fP
|
||||
Flag that affects usage of 'literal context modeling' format feature\&. This flag is a 'decoding-speed vs compression ratio' trade-off\&.
|
||||
.TP
|
||||
\fB\fIBROTLI_PARAM_SIZE_HINT \fP\fP
|
||||
Estimated total input size for all \fBBrotliEncoderCompressStream\fP calls\&. The default value is 0, which means that the total input size is unknown\&.
|
||||
.SH "Function Documentation"
|
||||
.PP
|
||||
.SS "\fBBROTLI_BOOL\fP BrotliEncoderCompress (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t * encoded_size, uint8_t encoded_buffer[*encoded_size])"
|
||||
|
||||
.PP
|
||||
Performs one-shot memory-to-memory compression\&. Compresses the data in \fCinput_buffer\fP into \fCencoded_buffer\fP, and sets \fC*encoded_size\fP to the compressed length\&.
|
||||
.PP
|
||||
\fBNote:\fP
|
||||
.RS 4
|
||||
If \fBBrotliEncoderMaxCompressedSize\fP(\fCinput_size\fP) returns non-zero value, then output is guaranteed to be no longer than that\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIquality\fP quality parameter value, e\&.g\&. \fBBROTLI_DEFAULT_QUALITY\fP
|
||||
.br
|
||||
\fIlgwin\fP lgwin parameter value, e\&.g\&. \fBBROTLI_DEFAULT_WINDOW\fP
|
||||
.br
|
||||
\fImode\fP mode parameter value, e\&.g\&. \fBBROTLI_DEFAULT_MODE\fP
|
||||
.br
|
||||
\fIinput_size\fP size of \fCinput_buffer\fP
|
||||
.br
|
||||
\fIinput_buffer\fP input data buffer with at least \fCinput_size\fP addressable bytes
|
||||
.br
|
||||
\fIencoded_size\fP \fBin:\fP size of \fCencoded_buffer\fP;
|
||||
.br
|
||||
\fBout:\fP length of compressed data written to \fCencoded_buffer\fP, or \fC0\fP if compression fails
|
||||
.br
|
||||
\fIencoded_buffer\fP compressed data destination buffer
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fBBROTLI_FALSE\fP in case of compression error
|
||||
.PP
|
||||
\fBBROTLI_FALSE\fP if output buffer is too small
|
||||
.PP
|
||||
\fBBROTLI_TRUE\fP otherwise
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBBROTLI_BOOL\fP BrotliEncoderCompressStream (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderOperation\fP op, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)"
|
||||
|
||||
.PP
|
||||
Compresses input stream to 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
|
||||
Internally workflow consists of 3 tasks:
|
||||
.IP "1." 4
|
||||
(optionally) copy input data to internal buffer
|
||||
.IP "2." 4
|
||||
actually compress data and (optionally) store it to internal buffer
|
||||
.IP "3." 4
|
||||
(optionally) copy compressed bytes from internal buffer to output stream
|
||||
.PP
|
||||
.PP
|
||||
Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller\&.
|
||||
.PP
|
||||
\fCop\fP is used to perform flush, finish the stream, or inject metadata block\&. See \fBBrotliEncoderOperation\fP for more information\&.
|
||||
.PP
|
||||
Flushing the stream means forcing encoding of all input passed to encoder and completing the current output block, so it could be fully decoded by stream decoder\&. To perform flush set \fCop\fP to \fBBROTLI_OPERATION_FLUSH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&.
|
||||
.PP
|
||||
Finishing the stream means encoding of all input passed to encoder and adding specific 'final' marks, so stream decoder could determine that stream is complete\&. To perform finish set \fCop\fP to \fBBROTLI_OPERATION_FINISH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&.
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
When flushing and finishing, \fCop\fP should not change until operation is complete; input stream should not be swapped, reduced or extended as well\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder instance
|
||||
.br
|
||||
\fIop\fP requested operation
|
||||
.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 input byte
|
||||
.br
|
||||
\fIavailable_out\fP \fBin:\fP length of output buffer;
|
||||
.br
|
||||
\fBout:\fP remaining size of output buffer
|
||||
.br
|
||||
\fInext_out\fP compressed output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP
|
||||
.br
|
||||
\fItotal_out\fP number of bytes produced so far; can be \fCNULL\fP
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fBBROTLI_FALSE\fP if there was an error
|
||||
.PP
|
||||
\fBBROTLI_TRUE\fP otherwise
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBBrotliEncoderState\fP* BrotliEncoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
|
||||
|
||||
.PP
|
||||
Creates an instance of \fBBrotliEncoderState\fP and initializes it\&. \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 \fBBrotliEncoderState\fP otherwise
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "void BrotliEncoderDestroyInstance (\fBBrotliEncoderState\fP * state)"
|
||||
|
||||
.PP
|
||||
Deinitializes and frees \fBBrotliEncoderState\fP instance\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP decoder instance to be cleaned up and deallocated
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBBROTLI_BOOL\fP BrotliEncoderHasMoreOutput (\fBBrotliEncoderState\fP * state)"
|
||||
|
||||
.PP
|
||||
Checks if encoder has more output\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder instance
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fBBROTLI_TRUE\fP, if encoder has some unconsumed output
|
||||
.PP
|
||||
\fBBROTLI_FALSE\fP otherwise
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBBROTLI_BOOL\fP BrotliEncoderIsFinished (\fBBrotliEncoderState\fP * state)"
|
||||
|
||||
.PP
|
||||
Checks if encoder instance reached the final state\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder instance
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fBBROTLI_TRUE\fP if encoder 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 "size_t BrotliEncoderMaxCompressedSize (size_t input_size)"
|
||||
|
||||
.PP
|
||||
Calculates the output size bound for the given \fCinput_size\fP\&.
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
Result is not applicable to \fBBrotliEncoderCompressStream\fP output, because every 'flush' adds extra overhead bytes, and some encoder settings (e\&.g\&. quality \fC0\fP and \fC1\fP) might imply a 'soft flush' after every chunk of input\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIinput_size\fP size of projected input
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fC0\fP if result does not fit \fCsize_t\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "void BrotliEncoderSetCustomDictionary (\fBBrotliEncoderState\fP * state, size_t size, const uint8_t dict[size])"
|
||||
|
||||
.PP
|
||||
Prepends imaginary LZ77 dictionary\&. Fills the fresh \fBBrotliEncoderState\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
|
||||
Workflow:
|
||||
.IP "1." 4
|
||||
Allocate and initialize state with \fBBrotliEncoderCreateInstance\fP
|
||||
.IP "2." 4
|
||||
Set \fBBROTLI_PARAM_LGWIN\fP parameter
|
||||
.IP "3." 4
|
||||
Invoke \fBBrotliEncoderSetCustomDictionary\fP
|
||||
.IP "4." 4
|
||||
Use \fBBrotliEncoderCompressStream\fP
|
||||
.IP "5." 4
|
||||
Clean up and free state with \fBBrotliEncoderDestroyInstance\fP
|
||||
.PP
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder instance
|
||||
.br
|
||||
\fIsize\fP length of \fCdict\fP; at most 'window size' bytes are used
|
||||
.br
|
||||
\fIdict\fP 'dictionary'; \fBMUST\fP use same dictionary during decompression
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "\fBBROTLI_BOOL\fP BrotliEncoderSetParameter (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
|
||||
|
||||
.PP
|
||||
Sets the specified parameter to the given encoder instance\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder instance
|
||||
.br
|
||||
\fIparam\fP parameter to set
|
||||
.br
|
||||
\fIvalue\fP new parameter value
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid
|
||||
.PP
|
||||
\fBBROTLI_FALSE\fP if value of parameter can not be changed at current encoder state (e\&.g\&. when encoding is started, window size might be already encoded and therefore it is impossible to change it)
|
||||
.PP
|
||||
\fBBROTLI_TRUE\fP if value is accepted
|
||||
.RE
|
||||
.PP
|
||||
\fBWarning:\fP
|
||||
.RS 4
|
||||
invalid values might be accepted in case they would not break encoding process\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "const uint8_t* BrotliEncoderTakeOutput (\fBBrotliEncoderState\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 \fBBrotliEncoderCompressStream\fP, until \fBBrotliEncoderHasMoreOutput\fP returns BROTL_TRUE
|
||||
.IP "2." 4
|
||||
use \fBBrotliEncoderTakeOutput\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 \fBBrotliEncoderTakeOutput\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
|
||||
Encoder output is not guaranteed to be contiguous\&. This means that after the size-unrestricted call to \fBBrotliEncoderTakeOutput\fP, immediate next call to \fBBrotliEncoderTakeOutput\fP may return more data\&.
|
||||
.RE
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIstate\fP encoder 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 BrotliEncoderVersion (void)"
|
||||
|
||||
.PP
|
||||
Gets an encoder library version\&. Look at BROTLI_VERSION for more information\&.
|
||||
.SH "Author"
|
||||
.PP
|
||||
Generated automatically by Doxygen for Brotli from the source code\&.
|
||||
117
docs/types.h.3
Executable file
117
docs/types.h.3
Executable file
@ -0,0 +1,117 @@
|
||||
.TH "types.h" 3 "Tue Feb 28 2017" "Brotli" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
types.h \- Common types used in decoder and encoder API\&.
|
||||
|
||||
.SH SYNOPSIS
|
||||
.br
|
||||
.PP
|
||||
.SS "Macros"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_BOOL\fP int"
|
||||
.br
|
||||
.RI "\fIA portable \fCbool\fP replacement\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_FALSE\fP 0"
|
||||
.br
|
||||
.RI "\fIPortable \fCfalse\fP replacement\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBBROTLI_TRUE\fP 1"
|
||||
.br
|
||||
.RI "\fIPortable \fCtrue\fP replacement\&. \fP"
|
||||
.ti -1c
|
||||
.RI "#define \fBTO_BROTLI_BOOL\fP(X) (!!(X) ? \fBBROTLI_TRUE\fP : \fBBROTLI_FALSE\fP)"
|
||||
.br
|
||||
.RI "\fI\fCbool\fP to \fBBROTLI_BOOL\fP conversion macros\&. \fP"
|
||||
.in -1c
|
||||
.SS "Typedefs"
|
||||
|
||||
.in +1c
|
||||
.ti -1c
|
||||
.RI "typedef void *(* \fBbrotli_alloc_func\fP) (void *opaque, size_t size)"
|
||||
.br
|
||||
.RI "\fIAllocating function pointer type\&. \fP"
|
||||
.ti -1c
|
||||
.RI "typedef void(* \fBbrotli_free_func\fP) (void *opaque, void *address)"
|
||||
.br
|
||||
.RI "\fIDeallocating function pointer type\&. \fP"
|
||||
.in -1c
|
||||
.SH "Detailed Description"
|
||||
.PP
|
||||
Common types used in decoder and encoder API\&.
|
||||
|
||||
|
||||
.SH "Macro Definition Documentation"
|
||||
.PP
|
||||
.SS "#define BROTLI_BOOL int"
|
||||
|
||||
.PP
|
||||
A portable \fCbool\fP replacement\&. \fBBROTLI_BOOL\fP is a 'documentation' type: actually it is \fCint\fP, but in API it denotes a type, whose only values are \fBBROTLI_TRUE\fP and \fBBROTLI_FALSE\fP\&.
|
||||
.PP
|
||||
\fBBROTLI_BOOL\fP values passed to Brotli should either be \fBBROTLI_TRUE\fP or \fBBROTLI_FALSE\fP, or be a result of \fBTO_BROTLI_BOOL\fP macros\&.
|
||||
.PP
|
||||
\fBBROTLI_BOOL\fP values returned by Brotli should not be tested for equality with \fCtrue\fP, \fCfalse\fP, \fBBROTLI_TRUE\fP, \fBBROTLI_FALSE\fP, but rather should be evaluated, for example:
|
||||
.PP
|
||||
.nf
|
||||
if (SomeBrotliFunction(encoder, BROTLI_TRUE) &&
|
||||
!OtherBrotliFunction(decoder, BROTLI_FALSE)) {
|
||||
bool x = !!YetAnotherBrotliFunction(encoder, TO_BROLTI_BOOL(2 * 2 == 4));
|
||||
DoSomething(x);
|
||||
}
|
||||
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS "#define BROTLI_FALSE 0"
|
||||
|
||||
.PP
|
||||
Portable \fCfalse\fP replacement\&.
|
||||
.SS "#define BROTLI_TRUE 1"
|
||||
|
||||
.PP
|
||||
Portable \fCtrue\fP replacement\&.
|
||||
.SS "#define TO_BROTLI_BOOL(X) (!!(X) ? \fBBROTLI_TRUE\fP : \fBBROTLI_FALSE\fP)"
|
||||
|
||||
.PP
|
||||
\fCbool\fP to \fBBROTLI_BOOL\fP conversion macros\&.
|
||||
.SH "Typedef Documentation"
|
||||
.PP
|
||||
.SS "typedef void*(* brotli_alloc_func) (void *opaque, size_t size)"
|
||||
|
||||
.PP
|
||||
Allocating function pointer type\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIopaque\fP custom memory manager handle provided by client
|
||||
.br
|
||||
\fIsize\fP requested memory region size; can not be \fC0\fP
|
||||
.RE
|
||||
.PP
|
||||
\fBReturns:\fP
|
||||
.RS 4
|
||||
\fC0\fP in the case of failure
|
||||
.PP
|
||||
a valid pointer to a memory region of at least \fCsize\fP bytes long otherwise
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SS "typedef void(* brotli_free_func) (void *opaque, void *address)"
|
||||
|
||||
.PP
|
||||
Deallocating function pointer type\&. This function \fBSHOULD\fP do nothing if \fCaddress\fP is \fC0\fP\&.
|
||||
.PP
|
||||
\fBParameters:\fP
|
||||
.RS 4
|
||||
\fIopaque\fP custom memory manager handle provided by client
|
||||
.br
|
||||
\fIaddress\fP memory region pointer returned by \fBbrotli_alloc_func\fP, or \fC0\fP
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.SH "Author"
|
||||
.PP
|
||||
Generated automatically by Doxygen for Brotli from the source code\&.
|
||||
@ -14,18 +14,21 @@
|
||||
<name>${project.groupId}:${project.artifactId}</name>
|
||||
|
||||
<build>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<testSourceDirectory>.</testSourceDirectory>
|
||||
<sourceDirectory>../../..</sourceDirectory>
|
||||
<testSourceDirectory>../../..</testSourceDirectory>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<configuration>
|
||||
<includes>
|
||||
<include>**/dec/*.java</include>
|
||||
</includes>
|
||||
<excludes>
|
||||
<exclude>**/*Test*.java</exclude>
|
||||
</excludes>
|
||||
<testIncludes>
|
||||
<include>**/*Test*.java</include>
|
||||
<include>**/dec/*Test*.java</include>
|
||||
</testIncludes>
|
||||
</configuration>
|
||||
</plugin>
|
||||
@ -42,7 +45,7 @@
|
||||
</goals>
|
||||
<configuration>
|
||||
<includes>
|
||||
<include>**/*.java</include>
|
||||
<include>**/dec/*.java</include>
|
||||
</includes>
|
||||
<excludes>
|
||||
<exclude>**/*Test*.java</exclude>
|
||||
@ -63,6 +66,7 @@
|
||||
<goal>jar</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<sourcepath>.</sourcepath>
|
||||
<sourceFileExcludes>
|
||||
<exclude>**/*Test*.java</exclude>
|
||||
</sourceFileExcludes>
|
||||
@ -4,7 +4,7 @@
|
||||
java_library(
|
||||
name = "bundle_checker_lib",
|
||||
srcs = ["BundleChecker.java"],
|
||||
deps = ["//java/dec:lib"],
|
||||
deps = ["//java/org/brotli/dec:lib"],
|
||||
)
|
||||
|
||||
java_binary(
|
||||
@ -15,7 +15,7 @@ java_binary(
|
||||
|
||||
java_test(
|
||||
name = "bundle_checker_data_test",
|
||||
args = ["java/integration/test_data.zip"],
|
||||
args = ["java/org/brotli/integration/test_data.zip"],
|
||||
data = ["test_data.zip"],
|
||||
main_class = "org.brotli.integration.BundleChecker",
|
||||
use_testrunner = 0,
|
||||
@ -26,7 +26,7 @@ java_test(
|
||||
name = "bundle_checker_fuzz_test",
|
||||
args = [
|
||||
"-s",
|
||||
"java/integration/fuzz_data.zip"
|
||||
"java/org/brotli/integration/fuzz_data.zip"
|
||||
],
|
||||
data = ["fuzz_data.zip"],
|
||||
main_class = "org.brotli.integration.BundleChecker",
|
||||
Loading…
Reference in New Issue
Block a user