From c931e576d2a7ae3dba9a7fc369895e3d31bb3f8b Mon Sep 17 00:00:00 2001 From: Eugene Kliuchnikov Date: Tue, 28 Feb 2017 16:59:52 +0100 Subject: [PATCH] Move `java/` to `java/org/brotli/` to fix `sources.jar` structure (#517) Also added man pages to `docs/` --- docs/decode.h.3 | 408 ++++++++++++ docs/encode.h.3 | 592 ++++++++++++++++++ docs/types.h.3 | 117 ++++ java/{ => org/brotli}/dec/BUILD | 0 java/{ => org/brotli}/dec/BitReader.java | 0 java/{ => org/brotli}/dec/BitReaderTest.java | 0 .../brotli}/dec/BrotliInputStream.java | 0 .../brotli}/dec/BrotliRuntimeException.java | 0 java/{ => org/brotli}/dec/Context.java | 0 java/{ => org/brotli}/dec/Decode.java | 0 java/{ => org/brotli}/dec/DecodeTest.java | 0 java/{ => org/brotli}/dec/Dictionary.java | 0 java/{ => org/brotli}/dec/DictionaryTest.java | 0 java/{ => org/brotli}/dec/Huffman.java | 0 .../brotli}/dec/HuffmanTreeGroup.java | 0 java/{ => org/brotli}/dec/Prefix.java | 0 java/{ => org/brotli}/dec/RunningState.java | 0 java/{ => org/brotli}/dec/State.java | 0 java/{ => org/brotli}/dec/SynthTest.java | 0 java/{ => org/brotli}/dec/Transform.java | 0 java/{ => org/brotli}/dec/TransformTest.java | 0 java/{ => org/brotli}/dec/Utils.java | 0 .../brotli}/dec/WordTransformType.java | 0 java/{ => org/brotli}/dec/pom.xml | 12 +- java/{ => org/brotli}/integration/BUILD | 6 +- .../brotli}/integration/BundleChecker.java | 0 .../brotli}/integration/fuzz_data.zip | Bin java/{ => org/brotli}/integration/pom.xml | 0 .../brotli}/integration/test_data.zip | Bin java/{ => org/brotli}/pom.xml | 0 30 files changed, 1128 insertions(+), 7 deletions(-) create mode 100755 docs/decode.h.3 create mode 100755 docs/encode.h.3 create mode 100755 docs/types.h.3 rename java/{ => org/brotli}/dec/BUILD (100%) rename java/{ => org/brotli}/dec/BitReader.java (100%) rename java/{ => org/brotli}/dec/BitReaderTest.java (100%) rename java/{ => org/brotli}/dec/BrotliInputStream.java (100%) rename java/{ => org/brotli}/dec/BrotliRuntimeException.java (100%) rename java/{ => org/brotli}/dec/Context.java (100%) rename java/{ => org/brotli}/dec/Decode.java (100%) rename java/{ => org/brotli}/dec/DecodeTest.java (100%) rename java/{ => org/brotli}/dec/Dictionary.java (100%) rename java/{ => org/brotli}/dec/DictionaryTest.java (100%) rename java/{ => org/brotli}/dec/Huffman.java (100%) rename java/{ => org/brotli}/dec/HuffmanTreeGroup.java (100%) rename java/{ => org/brotli}/dec/Prefix.java (100%) rename java/{ => org/brotli}/dec/RunningState.java (100%) rename java/{ => org/brotli}/dec/State.java (100%) rename java/{ => org/brotli}/dec/SynthTest.java (100%) rename java/{ => org/brotli}/dec/Transform.java (100%) rename java/{ => org/brotli}/dec/TransformTest.java (100%) rename java/{ => org/brotli}/dec/Utils.java (100%) rename java/{ => org/brotli}/dec/WordTransformType.java (100%) rename java/{ => org/brotli}/dec/pom.xml (87%) rename java/{ => org/brotli}/integration/BUILD (83%) rename java/{ => org/brotli}/integration/BundleChecker.java (100%) rename java/{ => org/brotli}/integration/fuzz_data.zip (100%) rename java/{ => org/brotli}/integration/pom.xml (100%) rename java/{ => org/brotli}/integration/test_data.zip (100%) rename java/{ => org/brotli}/pom.xml (100%) diff --git a/docs/decode.h.3 b/docs/decode.h.3 new file mode 100755 index 0000000..13cc57a --- /dev/null +++ b/docs/decode.h.3 @@ -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\&. diff --git a/docs/encode.h.3 b/docs/encode.h.3 new file mode 100755 index 0000000..51570b7 --- /dev/null +++ b/docs/encode.h.3 @@ -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\&. diff --git a/docs/types.h.3 b/docs/types.h.3 new file mode 100755 index 0000000..7dd8dc4 --- /dev/null +++ b/docs/types.h.3 @@ -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\&. diff --git a/java/dec/BUILD b/java/org/brotli/dec/BUILD similarity index 100% rename from java/dec/BUILD rename to java/org/brotli/dec/BUILD diff --git a/java/dec/BitReader.java b/java/org/brotli/dec/BitReader.java similarity index 100% rename from java/dec/BitReader.java rename to java/org/brotli/dec/BitReader.java diff --git a/java/dec/BitReaderTest.java b/java/org/brotli/dec/BitReaderTest.java similarity index 100% rename from java/dec/BitReaderTest.java rename to java/org/brotli/dec/BitReaderTest.java diff --git a/java/dec/BrotliInputStream.java b/java/org/brotli/dec/BrotliInputStream.java similarity index 100% rename from java/dec/BrotliInputStream.java rename to java/org/brotli/dec/BrotliInputStream.java diff --git a/java/dec/BrotliRuntimeException.java b/java/org/brotli/dec/BrotliRuntimeException.java similarity index 100% rename from java/dec/BrotliRuntimeException.java rename to java/org/brotli/dec/BrotliRuntimeException.java diff --git a/java/dec/Context.java b/java/org/brotli/dec/Context.java similarity index 100% rename from java/dec/Context.java rename to java/org/brotli/dec/Context.java diff --git a/java/dec/Decode.java b/java/org/brotli/dec/Decode.java similarity index 100% rename from java/dec/Decode.java rename to java/org/brotli/dec/Decode.java diff --git a/java/dec/DecodeTest.java b/java/org/brotli/dec/DecodeTest.java similarity index 100% rename from java/dec/DecodeTest.java rename to java/org/brotli/dec/DecodeTest.java diff --git a/java/dec/Dictionary.java b/java/org/brotli/dec/Dictionary.java similarity index 100% rename from java/dec/Dictionary.java rename to java/org/brotli/dec/Dictionary.java diff --git a/java/dec/DictionaryTest.java b/java/org/brotli/dec/DictionaryTest.java similarity index 100% rename from java/dec/DictionaryTest.java rename to java/org/brotli/dec/DictionaryTest.java diff --git a/java/dec/Huffman.java b/java/org/brotli/dec/Huffman.java similarity index 100% rename from java/dec/Huffman.java rename to java/org/brotli/dec/Huffman.java diff --git a/java/dec/HuffmanTreeGroup.java b/java/org/brotli/dec/HuffmanTreeGroup.java similarity index 100% rename from java/dec/HuffmanTreeGroup.java rename to java/org/brotli/dec/HuffmanTreeGroup.java diff --git a/java/dec/Prefix.java b/java/org/brotli/dec/Prefix.java similarity index 100% rename from java/dec/Prefix.java rename to java/org/brotli/dec/Prefix.java diff --git a/java/dec/RunningState.java b/java/org/brotli/dec/RunningState.java similarity index 100% rename from java/dec/RunningState.java rename to java/org/brotli/dec/RunningState.java diff --git a/java/dec/State.java b/java/org/brotli/dec/State.java similarity index 100% rename from java/dec/State.java rename to java/org/brotli/dec/State.java diff --git a/java/dec/SynthTest.java b/java/org/brotli/dec/SynthTest.java similarity index 100% rename from java/dec/SynthTest.java rename to java/org/brotli/dec/SynthTest.java diff --git a/java/dec/Transform.java b/java/org/brotli/dec/Transform.java similarity index 100% rename from java/dec/Transform.java rename to java/org/brotli/dec/Transform.java diff --git a/java/dec/TransformTest.java b/java/org/brotli/dec/TransformTest.java similarity index 100% rename from java/dec/TransformTest.java rename to java/org/brotli/dec/TransformTest.java diff --git a/java/dec/Utils.java b/java/org/brotli/dec/Utils.java similarity index 100% rename from java/dec/Utils.java rename to java/org/brotli/dec/Utils.java diff --git a/java/dec/WordTransformType.java b/java/org/brotli/dec/WordTransformType.java similarity index 100% rename from java/dec/WordTransformType.java rename to java/org/brotli/dec/WordTransformType.java diff --git a/java/dec/pom.xml b/java/org/brotli/dec/pom.xml similarity index 87% rename from java/dec/pom.xml rename to java/org/brotli/dec/pom.xml index 4d4935c..36a9069 100755 --- a/java/dec/pom.xml +++ b/java/org/brotli/dec/pom.xml @@ -14,18 +14,21 @@ ${project.groupId}:${project.artifactId} - . - . + ../../.. + ../../.. org.apache.maven.plugins maven-compiler-plugin + + **/dec/*.java + **/*Test*.java - **/*Test*.java + **/dec/*Test*.java @@ -42,7 +45,7 @@ - **/*.java + **/dec/*.java **/*Test*.java @@ -63,6 +66,7 @@ jar + . **/*Test*.java diff --git a/java/integration/BUILD b/java/org/brotli/integration/BUILD similarity index 83% rename from java/integration/BUILD rename to java/org/brotli/integration/BUILD index 9171e9e..6c1bc48 100755 --- a/java/integration/BUILD +++ b/java/org/brotli/integration/BUILD @@ -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", diff --git a/java/integration/BundleChecker.java b/java/org/brotli/integration/BundleChecker.java similarity index 100% rename from java/integration/BundleChecker.java rename to java/org/brotli/integration/BundleChecker.java diff --git a/java/integration/fuzz_data.zip b/java/org/brotli/integration/fuzz_data.zip similarity index 100% rename from java/integration/fuzz_data.zip rename to java/org/brotli/integration/fuzz_data.zip diff --git a/java/integration/pom.xml b/java/org/brotli/integration/pom.xml similarity index 100% rename from java/integration/pom.xml rename to java/org/brotli/integration/pom.xml diff --git a/java/integration/test_data.zip b/java/org/brotli/integration/test_data.zip similarity index 100% rename from java/integration/test_data.zip rename to java/org/brotli/integration/test_data.zip diff --git a/java/pom.xml b/java/org/brotli/pom.xml similarity index 100% rename from java/pom.xml rename to java/org/brotli/pom.xml