Google Brotli 解码器 API 深度解析

Google Brotli 解码器 API 深度解析

brotli Brotli compression format 项目地址: https://gitcode.com/gh_mirrors/brotl/brotli

概述

Google Brotli 是一种高效的通用无损压缩算法，特别适用于 Web 内容的压缩传输。本文重点分析 Brotli 解码器（解压缩）的 API 接口，帮助开发者理解如何使用 Brotli 进行数据解压缩操作。

核心数据结构

BrotliDecoderState

这是 Brotli 解码器的核心结构体，用于保存解码过程中的所有状态信息。该结构体是不透明的（opaque），意味着开发者不需要了解其内部实现细节，只需通过 API 函数进行操作。

typedef struct BrotliDecoderStateStruct BrotliDecoderState;

解码器生命周期管理

创建解码器实例

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

此函数用于创建并初始化一个新的解码器实例。开发者可以自定义内存分配函数，若不指定则使用默认的内存管理。

销毁解码器实例

void BrotliDecoderDestroyInstance(BrotliDecoderState* state);

使用完毕后必须调用此函数释放解码器占用的资源，避免内存泄漏。

解码操作方式

Brotli 提供两种解码方式：

1. 单次内存到内存解码

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

适用于已知压缩数据全部在内存中的简单场景，一次性完成解压缩。

2. 流式解码

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

适用于需要分块处理数据的场景，如网络传输或大文件处理。提供了更灵活的控制方式。

解码结果处理

解码状态检查

BROTLI_BOOL BrotliDecoderHasMoreOutput(const BrotliDecoderState* state);
BROTLI_BOOL BrotliDecoderIsFinished(const BrotliDecoderState* state);

这些函数用于查询解码器的当前状态，判断是否需要更多输入或是否有更多输出。

错误处理

BrotliDecoderErrorCode BrotliDecoderGetErrorCode(const BrotliDecoderState* state);
const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c);

当解码失败时，可通过这些函数获取详细的错误信息，便于调试和错误处理。

高级功能

字典支持

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

允许附加预定义的字典，可以显著提高特定领域数据的压缩率。

元数据处理

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

设置回调函数来处理压缩数据中的元数据块，为特殊应用场景提供扩展能力。

参数配置

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

可配置的解码参数包括：

• BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION：禁用环形缓冲区重新分配策略
• BROTLI_DECODER_PARAM_LARGE_WINDOW：启用大窗口模式

最佳实践

1. 对于简单应用，优先使用 BrotliDecoderDecompress 单次解码接口
2. 处理流数据时，使用 BrotliDecoderDecompressStream 并合理检查状态
3. 及时释放解码器实例，避免资源泄漏
4. 合理处理错误情况，使用 BrotliDecoderGetErrorCode 获取详细错误信息
5. 对于特定类型数据，考虑使用字典提高压缩率

总结

Google Brotli 解码器 API 设计简洁高效，既提供了简单的单次解压接口，也支持复杂的流式处理场景。通过合理的参数配置和高级功能使用，可以满足各种不同场景下的数据解压需求。理解这些 API 的工作原理和使用方法，可以帮助开发者在应用中更好地利用 Brotli 压缩算法。

brotli Brotli compression format 项目地址: https://gitcode.com/gh_mirrors/brotl/brotli