---
name: "decode.h"
section: "3"
platform: "linux"
package: "brotli"
version: "1.2.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/decode.h"
---

# decode.h(3)

API for Brotli decompression.

## NAME

decode.h - API for Brotli decompression.

## SYNOPSIS

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

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

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

API for Brotli decompression.

## Macro Definition Documentation

### #define BROTLI\_DECODER\_ERROR\_CODES\_LIST(BROTLI\_ERROR\_CODE, SEPARATOR)

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

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 void(\* brotli\_decoder\_metadata\_chunk\_func) (void \*opaque, const uint8\_t \*data, size\_t size)

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)

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

Options to be used with **BrotliDecoderSetParameter**.

### typedef struct BrotliDecoderStateStruct BrotliDecoderState

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

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

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

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

### enum BrotliDecoderResult

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

**Enumerator**

- *BROTLI\_DECODER\_RESULT\_ERROR*

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

- *BROTLI\_DECODER\_RESULT\_SUCCESS*

  *Decoding successfully completed.*

- *BROTLI\_DECODER\_RESULT\_NEEDS\_MORE\_INPUT*

  *Partially done; should be called again with more input.*

- *BROTLI\_DECODER\_RESULT\_NEEDS\_MORE\_OUTPUT*

  *Partially done; should be called again with more output.*

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

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

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

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

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

## Author

*Generated automatically by Doxygen for Brotli from the source code.*