decode.h(3) Library Functions Manual decode.h(3)

# [NAME](#NAME)

decode.h - API for Brotli decompression.

# [SYNOPSIS](#SYNOPSIS)

## [Macros](#Macros)

#define **BROTLI\_DECODER\_ERROR\_CODES\_LIST**(BROTLI\_ERROR\_CODE, SEPARATOR)  
*Template that evaluates items of BrotliDecoderErrorCode.* #define **BROTLI\_LAST\_ERROR\_CODE** BROTLI\_DECODER\_ERROR\_UNREACHABLE  
*The value of the last error code, negative integer.*

## [Typedefs](#Typedefs)

typedef void(* **brotli\_decoder\_metadata\_chunk\_func**) (void \*opaque, const uint8\_t \*data, size\_t size)  
*Callback to fire on metadata block chunk becomes available.* typedef void(* **brotli\_decoder\_metadata\_start\_func**) (void \*opaque, size\_t size)  
*Callback to fire on metadata block start.* typedef enum **BrotliDecoderParameter** **BrotliDecoderParameter**  
*Options to be used with BrotliDecoderSetParameter.* typedef struct BrotliDecoderStateStruct **BrotliDecoderState**  
*Opaque structure that holds decoder state.*

## [Enumerations](#Enumerations)

## [Functions](#Functions)

**BROTLI\_BOOL** **BrotliDecoderAttachDictionary** (**BrotliDecoderState** \*state, BrotliSharedDictionaryType type, size\_t data\_size, const uint8\_t data\[data\_size])  
*Adds LZ77 prefix dictionary, adds or replaces built-in static dictionary and transforms.* **BrotliDecoderState** * **BrotliDecoderCreateInstance** (**brotli\_alloc\_func** alloc\_func, **brotli\_free\_func** free\_func, void \*opaque)  
*Creates an instance of BrotliDecoderState and initializes it.* **BrotliDecoderResult** **BrotliDecoderDecompress** (size\_t encoded\_size, const uint8\_t encoded\_buffer\[encoded\_size], size\_t \*decoded\_size, uint8\_t decoded\_buffer\[\*decoded\_size])  
*Performs one-shot memory-to-memory decompression.* **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.* void **BrotliDecoderDestroyInstance** (**BrotliDecoderState** \*state)  
*Deinitializes and frees BrotliDecoderState instance.* const char * **BrotliDecoderErrorString** (**BrotliDecoderErrorCode** c)  
*Converts error code to a c-string.* **BrotliDecoderErrorCode** **BrotliDecoderGetErrorCode** (const **BrotliDecoderState** \*state)  
*Acquires a detailed error code.* **BROTLI\_BOOL** **BrotliDecoderHasMoreOutput** (const **BrotliDecoderState** \*state)  
*Checks if decoder has more output.* **BROTLI\_BOOL** **BrotliDecoderIsFinished** (const **BrotliDecoderState** \*state)  
*Checks if decoder instance reached the final state.* **BROTLI\_BOOL** **BrotliDecoderIsUsed** (const **BrotliDecoderState** \*state)  
*Checks if instance has already consumed input.* 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.* **BROTLI\_BOOL** **BrotliDecoderSetParameter** (**BrotliDecoderState** \*state, **BrotliDecoderParameter** param, uint32\_t value)  
*Sets the specified parameter to the given decoder instance.* const uint8\_t * **BrotliDecoderTakeOutput** (**BrotliDecoderState** \*state, size\_t \*size)  
*Acquires pointer to internal output buffer.* uint32\_t **BrotliDecoderVersion** (void)  
*Gets a decoder library version.*

# [Detailed Description](#Detailed_Description)

API for Brotli decompression.

# [Macro Definition Documentation](#Macro_Definition_Documentation)

## [#define BROTLI\_DECODER\_ERROR\_CODES\_LIST(BROTLI\_ERROR\_CODE, SEPARATOR)](#_define_BROTLI_DECODER_ERROR_CODES_LIST%28BROTLI_ERROR_CODE,_SEPARATOR%29)

Template that evaluates items of **BrotliDecoderErrorCode**. Example:

```
// 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";
}
```

## [#define BROTLI\_LAST\_ERROR\_CODE BROTLI\_DECODER\_ERROR\_UNREACHABLE](#_define_BROTLI_LAST_ERROR_CODE___BROTLI_DECODER_ERROR_UNREACHABLE)

The value of the last error code, negative integer. All other error code values are in the range from **BROTLI\_LAST\_ERROR\_CODE** to -1**. There are also 4 other possible non-error codes 0** .. 3 **in BrotliDecoderErrorCode enumeration.**

# [Typedef Documentation](#Typedef_Documentation)

## [typedef void(* brotli\_decoder\_metadata\_chunk\_func) (void \*opaque, const uint8\_t \*data, size\_t size)](#typedef_void%28*_brotli_decoder_metadata_chunk_func%29_%28void_*opaque,_const_uint8_t_*data,_size_t_size%29)

Callback to fire on metadata block chunk becomes available. This function can be invoked multiple times per metadata block; block should be considered finished when sum of size **matches the announced metadata block size. Chunks contents pointed by data** are transient and shouln not be accessed after leaving the callback.

**Parameters:**

*opaque* callback handle  
*data* pointer to metadata contents  
*size* size of metadata block chunk, at least 1

## [typedef void(* brotli\_decoder\_metadata\_start\_func) (void \*opaque, size\_t size)](#typedef_void%28*_brotli_decoder_metadata_start_func%29_%28void_*opaque,_size_t_size%29)

Callback to fire on metadata block start. After this callback is fired, if size *is not 0*, it is followed by **brotli\_decoder\_metadata\_chunk\_func** as more metadata block contents become accessible.

**Parameters:**

*opaque* callback handle  
*size* size of metadata block

## [typedef enum **BrotliDecoderParameter** **BrotliDecoderParameter**](#typedef_enum_)

Options to be used with **BrotliDecoderSetParameter**.

## [typedef struct BrotliDecoderStateStruct **BrotliDecoderState**](#typedef_struct_BrotliDecoderStateStruct_)

Opaque structure that holds decoder state. Allocated and initialized with **BrotliDecoderCreateInstance**. Cleaned up and deallocated with **BrotliDecoderDestroyInstance**.

# [Enumeration Type Documentation](#Enumeration_Type_Documentation)

## enum **BrotliDecoderErrorCode**

Error code for detailed logging / production debugging. See **BrotliDecoderGetErrorCode** and **BROTLI\_LAST\_ERROR\_CODE**.

## enum **BrotliDecoderParameter**

Options to be used with **BrotliDecoderSetParameter**.

**Enumerator**

[**BROTLI\_DECODER\_PARAM\_DISABLE\_RING\_BUFFER\_REALLOCATION**](#BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION)

Disable 'canny' ring buffer allocation strategy. Ring buffer is allocated according to window size, despite the real size of the content.

[**BROTLI\_DECODER\_PARAM\_LARGE\_WINDOW**](#BROTLI_DECODER_PARAM_LARGE_WINDOW)

Flag that determines if 'Large Window Brotli' is used.

## enum **BrotliDecoderResult**

Result type for **BrotliDecoderDecompress** and **BrotliDecoderDecompressStream** functions.

**Enumerator**

[**BROTLI\_DECODER\_RESULT\_ERROR**](#BROTLI_DECODER_RESULT_ERROR)

Decoding error, e.g. corrupted input or memory allocation problem.

[**BROTLI\_DECODER\_RESULT\_SUCCESS**](#BROTLI_DECODER_RESULT_SUCCESS)

Decoding successfully completed.

[**BROTLI\_DECODER\_RESULT\_NEEDS\_MORE\_INPUT**](#BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT)

Partially done; should be called again with more input.

[**BROTLI\_DECODER\_RESULT\_NEEDS\_MORE\_OUTPUT**](#BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT)

Partially done; should be called again with more output.

# [Function Documentation](#Function_Documentation)

## **BROTLI\_BOOL** BrotliDecoderAttachDictionary (**BrotliDecoderState** * state, BrotliSharedDictionaryType type, size\_t data\_size, const uint8\_t data\[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

## **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

## **BrotliDecoderResult** BrotliDecoderDecompress (size\_t encoded\_size, const uint8\_t encoded\_buffer\[encoded\_size], size\_t * decoded\_size, uint8\_t decoded\_buffer\[\*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*  
*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

## **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  
*available\_in* **in:** amount of available input;  
**out:** amount of unused input  
*next\_in* pointer to the next compressed byte  
*available\_out* **in:** length of output buffer;  
**out:** remaining size of output buffer  
*next\_out* output buffer cursor; can be NULL *if available\_out* is 0  
*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

## [void BrotliDecoderDestroyInstance (**BrotliDecoderState** * state)](#void_BrotliDecoderDestroyInstance_%28)

Deinitializes and frees **BrotliDecoderState** instance.

**Parameters:**

*state* decoder instance to be cleaned up and deallocated

## **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

## **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

## **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

## **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

## [void BrotliDecoderSetMetadataCallbacks (**BrotliDecoderState** * state, **brotli\_decoder\_metadata\_start\_func** start\_func, **brotli\_decoder\_metadata\_chunk\_func** chunk\_func, void * opaque)](#void_BrotliDecoderSetMetadataCallbacks_%28)

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

## **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

## [const uint8\_t* BrotliDecoderTakeOutput (**BrotliDecoderState** * state, size\_t * size)](#const_uint8_t*_BrotliDecoderTakeOutput_%28)

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  
*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

## [uint32\_t BrotliDecoderVersion (void)](#uint32_t_BrotliDecoderVersion_%28void%29)

Gets a decoder library version. Look at BROTLI\_MAKE\_HEX\_VERSION for more information.

# [Author](#Author)

Generated automatically by Doxygen for Brotli from the source code.

August 2021 Brotli

---

Document: decode.h(3) from brotli 1.2.0-r6 (Chainguard OS)
Source: https://github.com/google/brotli.git