decode.c File Reference

#include <brotli/decode.h>
#include <stdlib.h>
#include <string.h>
#include "../common/constants.h"
#include "../common/context.h"
#include "../common/dictionary.h"
#include "../common/platform.h"
#include "../common/shared_dictionary_internal.h"
#include "../common/transform.h"
#include "../common/version.h"
#include "bit_reader.h"
#include "huffman.h"
#include "prefix.h"
#include "state.h"

Macros
#define	BROTLI_FAILURE(CODE)
#define	BROTLI_LOG_UINT(name)
#define	BROTLI_LOG_ARRAY_INDEX(array_name, idx)
#define	HUFFMAN_TABLE_BITS   8U
#define	HUFFMAN_TABLE_MASK   0xFF
#define	BROTLI_SAFE(METHOD)
#define	BROTLI_SAVE_ERROR_CODE(code)
#define	BROTLI_ERROR_CODE_CASE_(PREFIX, NAME, CODE)
#define	BROTLI_NOTHING_

Functions
BROTLI_BOOL	BrotliDecoderSetParameter (BrotliDecoderState *state, BrotliDecoderParameter p, uint32_t value)
BrotliDecoderState *	BrotliDecoderCreateInstance (brotli_alloc_func alloc_func, brotli_free_func free_func, void *opaque)
void	BrotliDecoderDestroyInstance (BrotliDecoderState *state)
BROTLI_BOOL	BrotliDecoderAttachDictionary (BrotliDecoderState *state, BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)])
BrotliDecoderResult	BrotliDecoderDecompress (size_t encoded_size, const uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(encoded_size)], size_t *decoded_size, uint8_t decoded_buffer[BROTLI_ARRAY_PARAM(*decoded_size)])
BrotliDecoderResult	BrotliDecoderDecompressStream (BrotliDecoderState *s, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)
BROTLI_BOOL	BrotliDecoderHasMoreOutput (const BrotliDecoderState *s)
const uint8_t *	BrotliDecoderTakeOutput (BrotliDecoderState *s, size_t *size)
BROTLI_BOOL	BrotliDecoderIsUsed (const BrotliDecoderState *s)
BROTLI_BOOL	BrotliDecoderIsFinished (const BrotliDecoderState *s)
BrotliDecoderErrorCode	BrotliDecoderGetErrorCode (const BrotliDecoderState *s)
const char *	BrotliDecoderErrorString (BrotliDecoderErrorCode c)
uint32_t	BrotliDecoderVersion (void)
void	BrotliDecoderSetMetadataCallbacks (BrotliDecoderState *state, brotli_decoder_metadata_start_func start_func, brotli_decoder_metadata_chunk_func chunk_func, void *opaque)

Macro Definition Documentation

BROTLI_ERROR_CODE_CASE_

#define BROTLI_ERROR_CODE_CASE_	(		PREFIX,
			NAME,
			CODE )

Value:

     case BROTLI_DECODER##PREFIX##NAME:             \
          return #PREFIX #NAME;

BROTLI_FAILURE

#define BROTLI_FAILURE

(

CODE

)

Value:

(BROTLI_DUMP(), CODE)

BROTLI_LOG_ARRAY_INDEX

#define BROTLI_LOG_ARRAY_INDEX	(		array_name,
			idx )

Value:

     BROTLI_LOG(("[%s] %s[%lu] = %lu\n", __func__, #array_name, \
                 (unsigned long)(idx), (unsigned long)array_name[idx]))

BROTLI_LOG_UINT

#define BROTLI_LOG_UINT

(

name

)

Value:

     BROTLI_LOG(("[%s] %s = %lu\n", __func__, #name, (unsigned long)(name)))

BROTLI_NOTHING_

#define BROTLI_NOTHING_

BROTLI_SAFE

#define BROTLI_SAFE

(

METHOD

)

Value:

     {                                                        \
          if (safe)                                           \
          {                                                   \
               if (!Safe##METHOD)                             \
               {                                              \
                    result = BROTLI_DECODER_NEEDS_MORE_INPUT; \
                    goto saveStateAndReturn;                  \
               }                                              \
          }                                                   \
          else                                                \
          {                                                   \
               METHOD;                                        \
          }                                                   \
     }

BROTLI_SAVE_ERROR_CODE

#define BROTLI_SAVE_ERROR_CODE

(

code

)

Value:

     SaveErrorCode(s, (code), input_size - *available_in)

HUFFMAN_TABLE_BITS

#define HUFFMAN_TABLE_BITS   8U

HUFFMAN_TABLE_MASK

#define HUFFMAN_TABLE_MASK   0xFF

Function Documentation

BrotliDecoderAttachDictionary()

BROTLI_BOOL BrotliDecoderAttachDictionary	(	BrotliDecoderState *	state,
		BrotliSharedDictionaryType	type,
		size_t	data_size,
		const uint8_t	data[BROTLI_ARRAY_PARAM(data_size)] )

Adds LZ77 prefix dictionary, adds or replaces built-in static dictionary and transforms.

Attached dictionary ownership is not transferred. Data provided to this method should be kept accessible until decoding is finished and decoder instance is destroyed.

Note

Dictionaries can NOT be attached after actual decoding is started.

Parameters

state	decoder instance
type	dictionary data format
data_size	length of memory region pointed by data
data	dictionary data in format corresponding to type

Returns

BROTLI_FALSE if dictionary is corrupted, or dictionary count limit is reached

BROTLI_TRUE if dictionary is accepted / attached

BrotliDecoderCreateInstance()

BrotliDecoderState * BrotliDecoderCreateInstance	(	brotli_alloc_func	alloc_func,
		brotli_free_func	free_func,
		void *	opaque )

Creates an instance of BrotliDecoderState and initializes it.

The instance can be used once for decoding and should then be destroyed with BrotliDecoderDestroyInstance, it cannot be reused for a new decoding session.

alloc_func and free_func MUST be both zero or both non-zero. In the case they are both zero, default memory allocators are used. opaque is passed to alloc_func and free_func when they are called. free_func has to return without doing anything when asked to free a NULL pointer.

Parameters

alloc_func	custom memory allocation function
free_func	custom memory free function
opaque	custom memory manager handle

Returns

0 if instance can not be allocated or initialized

pointer to initialized BrotliDecoderState otherwise

BrotliDecoderDecompress()

BrotliDecoderResult BrotliDecoderDecompress	(	size_t	encoded_size,
		const uint8_t	encoded_buffer[BROTLI_ARRAY_PARAM(encoded_size)],
		size_t *	decoded_size,
		uint8_t	decoded_buffer[BROTLI_ARRAY_PARAM(*decoded_size)] )

Performs one-shot memory-to-memory decompression.

Decompresses the data in encoded_buffer into decoded_buffer, and sets *decoded_size to the decompressed length.

Parameters

	encoded_size	size of encoded_buffer
	encoded_buffer	compressed data buffer with at least encoded_size addressable bytes
[in,out]	decoded_size	in: size of decoded_buffer; out: length of decompressed data written to decoded_buffer
	decoded_buffer	decompressed data destination buffer

Returns

BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory allocation failed, or decoded_buffer is not large enough;

BROTLI_DECODER_RESULT_SUCCESS otherwise

BrotliDecoderDecompressStream()

BrotliDecoderResult BrotliDecoderDecompressStream	(	BrotliDecoderState *	state,
		size_t *	available_in,
		const uint8_t **	next_in,
		size_t *	available_out,
		uint8_t **	next_out,
		size_t *	total_out )

Decompresses the input stream to the output stream.

The values *available_in and *available_out must specify the number of bytes addressable at *next_in and *next_out respectively. When *available_out is 0, next_out is allowed to be NULL.

After each call, *available_in will be decremented by the amount of input bytes consumed, and the *next_in pointer will be incremented by that amount. Similarly, *available_out will be decremented by the amount of output bytes written, and the *next_out pointer will be incremented by that amount.

total_out, if it is not a null-pointer, will be set to the number of bytes decompressed since the last state initialization.

Note

Input is never overconsumed, so next_in and available_in could be passed to the next consumer after decoding is complete.

Parameters

	state	decoder instance
[in,out]	available_in	in: amount of available input; out: amount of unused input
[in,out]	next_in	pointer to the next compressed byte
[in,out]	available_out	in: length of output buffer; out: remaining size of output buffer
[in,out]	next_out	output buffer cursor; can be NULL if available_out is 0
[out]	total_out	number of bytes decompressed so far; can be NULL

Returns

BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory allocation failed, arguments were invalid, etc.; use BrotliDecoderGetErrorCode to get detailed error code

BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT decoding is blocked until more input data is provided

BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT decoding is blocked until more output space is provided

BROTLI_DECODER_RESULT_SUCCESS decoding is finished, no more input might be consumed and no more output will be produced

BrotliDecoderDestroyInstance()

void BrotliDecoderDestroyInstance

(

BrotliDecoderState *

state

)

Deinitializes and frees BrotliDecoderState instance.

Parameters

state

decoder instance to be cleaned up and deallocated

BrotliDecoderErrorString()

const char * BrotliDecoderErrorString

(

BrotliDecoderErrorCode

c

)

Converts error code to a c-string.

BrotliDecoderGetErrorCode()

BrotliDecoderErrorCode BrotliDecoderGetErrorCode

(

const BrotliDecoderState *

state

)

Acquires a detailed error code.

Should be used only after BrotliDecoderDecompressStream returns BROTLI_DECODER_RESULT_ERROR.

See also BrotliDecoderErrorString

Parameters

state

decoder instance

Returns

last saved error code

BrotliDecoderHasMoreOutput()

BROTLI_BOOL BrotliDecoderHasMoreOutput

(

const BrotliDecoderState *

state

)

Checks if decoder has more output.

Parameters

state

decoder instance

Returns

BROTLI_TRUE, if decoder has some unconsumed output

BROTLI_FALSE otherwise

BrotliDecoderIsFinished()

BROTLI_BOOL BrotliDecoderIsFinished

(

const BrotliDecoderState *

state

)

Checks if decoder instance reached the final state.

Parameters

state

decoder instance

Returns

BROTLI_TRUE if decoder is in a state where it reached the end of the input and produced all of the output

BROTLI_FALSE otherwise

BrotliDecoderIsUsed()

BROTLI_BOOL BrotliDecoderIsUsed

(

const BrotliDecoderState *

state

)

Checks if instance has already consumed input.

Instance that returns BROTLI_FALSE is considered "fresh" and could be reused.

Parameters

state

decoder instance

Returns

BROTLI_TRUE if decoder has already used some input bytes

BROTLI_FALSE otherwise

BrotliDecoderSetMetadataCallbacks()

void BrotliDecoderSetMetadataCallbacks	(	BrotliDecoderState *	state,
		brotli_decoder_metadata_start_func	start_func,
		brotli_decoder_metadata_chunk_func	chunk_func,
		void *	opaque )

Sets callback for receiving metadata blocks.

Parameters

state	decoder instance
start_func	callback on metadata block start
chunk_func	callback on metadata block chunk
opaque	callback handle

BrotliDecoderSetParameter()

BROTLI_BOOL BrotliDecoderSetParameter	(	BrotliDecoderState *	state,
		BrotliDecoderParameter	param,
		uint32_t	value )

Sets the specified parameter to the given decoder instance.

Parameters

state	decoder instance
param	parameter to set
value	new parameter value

Returns

BROTLI_FALSE if parameter is unrecognized, or value is invalid

BROTLI_TRUE if value is accepted

BrotliDecoderTakeOutput()

const uint8_t * BrotliDecoderTakeOutput	(	BrotliDecoderState *	state,
		size_t *	size )

Acquires pointer to internal output buffer.

This method is used to make language bindings easier and more efficient:

1. push data to BrotliDecoderDecompressStream, until BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT is reported
2. use BrotliDecoderTakeOutput to peek bytes and copy to language-specific entity

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).

Attention

After every call to BrotliDecoderTakeOutput *size bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well.

Note

Decoder output is not guaranteed to be contiguous. This means that after the size-unrestricted call to BrotliDecoderTakeOutput, immediate next call to BrotliDecoderTakeOutput may return more data.

Parameters

	state	decoder instance
[in,out]	size	in: number of bytes caller is ready to take, 0 if any amount could be handled; out: amount of data pointed by returned pointer and considered consumed; out value is never greater than in value, unless it is 0

Returns

pointer to output data

BrotliDecoderVersion()

uint32_t BrotliDecoderVersion

(

void

)

Gets a decoder library version.

Look at BROTLI_VERSION for more information.