decode.h(3)

📦
version 1.2.1 · 2 versions
, in centos-stream 10, fedora 43, fedora 44

💖 decode.h — the Brotli decompression API, bestie edition 💖

okay so this is decode.h, a page from the Library Functions Manual, and it's literally the whole API for Brotli decompression. if you've ever wondered how to un-squish a Brotli stream, this is the header that hands you the keys. no cap. 🎀

✨ NAME ✨

decode.h — API for Brotli decompression. that's it, that's the whole vibe. she decompresses. 💅

🌸 SYNOPSIS 🌸

🧚 Macros

  • #define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR) — a template that evaluates items of BrotliDecoderErrorCode. iykyk, you feed it macros and it does the thing.
  • #define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE — the value of the last error code, and it's a negative integer. 🫶

🦋 Typedefs

  • typedef void(* brotli_decoder_metadata_chunk_func) (void *opaque, const uint8_t *data, size_t size) — the callback that fires when a metadata block chunk becomes available.
  • typedef void(* brotli_decoder_metadata_start_func) (void *opaque, size_t size) — the callback that fires on metadata block start.
  • typedef enum BrotliDecoderParameter BrotliDecoderParameter — options to be used with BrotliDecoderSetParameter.
  • typedef struct BrotliDecoderStateStruct BrotliDecoderState — an opaque structure that holds decoder state. main character energy, but you can't peek inside her. 🙈

💜 Enumerations

(she's listed here, the actual enumerators live further down, be patient bestie)

⭐ Functions

  • BROTLI_BOOL BrotliDecoderAttachDictionary (BrotliDecoderState *state, BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size]) — adds an LZ77 prefix dictionary, and adds or replaces the 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 a BrotliDecoderState instance. rest in peace queen 🕊️
  • const char * BrotliDecoderErrorString (BrotliDecoderErrorCode c) — converts an error code to a c-string.
  • BrotliDecoderErrorCode BrotliDecoderGetErrorCode (const BrotliDecoderState *state) — acquires a detailed error code.
  • BROTLI_BOOL BrotliDecoderHasMoreOutput (const BrotliDecoderState *state) — checks if the decoder has more output.
  • BROTLI_BOOL BrotliDecoderIsFinished (const BrotliDecoderState *state) — checks if the decoder instance reached the final state.
  • BROTLI_BOOL BrotliDecoderIsUsed (const BrotliDecoderState *state) — checks if the 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 the 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 a pointer to the internal output buffer.
  • uint32_t BrotliDecoderVersion (void) — gets a decoder library version.

💅 Detailed Description 💅

API for Brotli decompression. periodt.

🍓 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, a 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 the BrotliDecoderErrorCode enumeration. so like, don't panic if you see a tiny number, she's not mad at you 💖

🌈 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; the block should be considered finished when the sum of size matches the announced metadata block size.

⚠️ ngl this part matters: chunks' contents pointed by data are transient and shouln not be accessed after leaving the callback. (yes, "shouln" — we keep the typo, we don't fix the queen's spelling 💀)

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

typedef struct BrotliDecoderStateStruct BrotliDecoderState

Opaque structure that holds decoder state. Allocated and initialized with BrotliDecoderCreateInstance. Cleaned up and deallocated with BrotliDecoderDestroyInstance. she is born, she decodes, she is freed. iconic arc honestly. ✨

👑 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 the 'canny' ring buffer allocation strategy. the 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. ate. 💅
  • 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.

okay bestie, that's part 1 — the rest is still coming, don't go anywhere 🫶

✨ FUNCTION DOCUMENTATION ✨

Bestie, this is the main character section. Every function you get to call, with the receipts on params and return values. Buckle up. 🎀

💖 BrotliDecoderAttachDictionary

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

Adds an LZ77 prefix dictionary, and also adds or replaces the built-in static dictionary and its transforms. Okay so here's the tea: attached dictionary ownership is not transferred. So the data you hand over? You have to keep it accessible until decoding is done and the decoder instance is destroyed. No handing it off and forgetting, bestie. 🙈

Note: Dictionaries can NOT be attached after actual decoding is started. Like, the door closes. That's it.

Parameters:

  • state — decoder instance
  • type — dictionary data format
  • data_size — length of the memory region pointed to by data
  • data — dictionary data, in the format that corresponds to type

Returns:

  • BROTLI_FALSE if the dictionary is corrupted, or if the dictionary count limit is reached
  • BROTLI_TRUE if the 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. Ngl this is where it all begins. The instance can be used once for decoding and should then be destroyed with BrotliDecoderDestroyInstance — it cannot be reused for a new decoding session. One and done, one-shot icon behavior. 💅

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 gets passed to alloc_func and free_func when they're called. And free_func has to return without doing anything when asked to free a NULL pointer. That's the rule, fr fr.

Parameters:

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

Returns:

  • 0 if the instance can not be allocated or initialized
  • a pointer to the initialized BrotliDecoderState otherwise 🫶

🌸 BrotliDecoderDecompress

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. No streaming, no drama, just in and out. 🔥

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 the decompressed data written to decoded_buffer
  • decoded_buffer — decompressed data destination buffer

Returns:

  • BROTLI_DECODER_RESULT_ERROR if the 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. Okay so this one's the workhorse, the main character, the whole vibe. 👑

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. So polite. So considerate. 🧚

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 the input is corrupted, memory allocation failed, arguments were invalid, etc.; use BrotliDecoderGetErrorCode to get the 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 the BrotliDecoderState instance. The farewell tour. Say your goodbyes, clean up after yourself, leave no trace. 💜

Parameters:

  • state — decoder instance to be cleaned up and deallocated

🔍 BrotliDecoderGetErrorCode

BrotliDecoderErrorCode BrotliDecoderGetErrorCode (const BrotliDecoderState *
    state)

Acquires a detailed error code. Should be used only after BrotliDecoderDecompressStream returns BROTLI_DECODER_RESULT_ERROR. Like, don't come asking for the error code before there's an error, bestie. It's giving premature. 😭

See also BrotliDecoderErrorString

Parameters:

  • state — decoder instance

Returns:

  • the last saved error code

✨ BrotliDecoderHasMoreOutput

BROTLI_BOOL BrotliDecoderHasMoreOutput (const BrotliDecoderState * state)

Checks if the decoder has more output. Vibe check on the output buffer. 🍓

Parameters:

  • state — decoder instance

Returns:

  • BROTLI_TRUE if the decoder has some unconsumed output
  • BROTLI_FALSE otherwise

🏁 BrotliDecoderIsFinished

BROTLI_BOOL BrotliDecoderIsFinished (const BrotliDecoderState * state)

Checks if the decoder instance reached the final state. Did we make it to the end? Did we finish the story? 📖

Parameters:

  • state — decoder instance

Returns:

  • BROTLI_TRUE if the 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 the instance has already consumed input. An instance that returns BROTLI_FALSE is considered 'fresh' and could be reused. Fresh like a brand new day, no cap. 🌸

Parameters:

  • state — decoder instance

Returns:

  • BROTLI_TRUE if the 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 the callback for receiving metadata blocks. The little extra info packets get their own delivery service. 💌

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. Tuning the vibes, adjusting the dials. ⚙️

Parameters:

  • state — decoder instance
  • param — parameter to set
  • value — new parameter value

Returns:

  • BROTLI_FALSE if the parameter is unrecognized, or the value is invalid
  • BROTLI_TRUE if the value is accepted ✅

👑 BrotliDecoderTakeOutput

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

Acquires a pointer to the 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 a 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 the file system). Slay, efficient queen. 💅

Attention: After every call to BrotliDecoderTakeOutput, *size bytes of output are considered consumed for all consecutive calls to the instance methods; the returned pointer becomes invalidated as well. So like, don't hold onto that pointer, bestie, it's gone. 💀
Note: Decoder output is not guaranteed to be contiguous. This means that after the size-unrestricted call to BrotliDecoderTakeOutput, the immediate next call to BrotliDecoderTakeOutput may return more data. Not me getting surprise extra bytes. 🙈

Parameters:

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

Returns:

  • pointer to output data

🏷️ BrotliDecoderVersion

uint32_t BrotliDecoderVersion (void)

Gets the decoder library version. Look at BROTLI_MAKE_HEX_VERSION for more information. Gotta know which era of the library you're living in. ⭐

💜 AUTHOR

Generated automatically by Doxygen for Brotli from the source code.

And that's a wrap, bestie! 🎀 This was Brotli's decode.h(3), served up by the Brotli crew and dated August 2021 — automatically generated by Doxygen from the source code, because even docs deserve a glow-up. Go forth and decode responsibly. ✨💖🦋

📦 where this page comes from