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/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_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)
BrotliDecoderResult	BrotliDecoderDecompress (size_t encoded_size, const uint8_t *encoded_buffer, size_t *decoded_size, uint8_t *decoded_buffer)
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 ()

Macro Definition Documentation

BROTLI_ERROR_CODE_CASE_

#define BROTLI_ERROR_CODE_CASE_	(		PREFIX,
			NAME,
			CODE )

Value:

     case BROTLI_DECODER##PREFIX##NAME:             \
          return #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;                                        \
          }                                                   \
     }

HUFFMAN_TABLE_BITS

#define HUFFMAN_TABLE_BITS   8U

HUFFMAN_TABLE_MASK

#define HUFFMAN_TABLE_MASK   0xFF

Function Documentation

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,
		size_t *	decoded_size,
		uint8_t *	decoded_buffer )

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

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.