(1) fecal 使用接口介绍本章介绍fecal的接口使用方法，配合一个样例程序详细讲解如何使用编码器生成冗余保护数据

欢迎来到 fecal 的世界！这是一个功能强大的前向错误纠正（Forward Error Correction, FEC）库。在深入研究它的内部奥秘之前，我们首先需要了解如何与它进行交互。本章将向您介绍 fecal 的公共 C 语言接口。

想象一下，fecal 库就像一座复杂的工厂，里面有各种精密的机器和高效的流水线。而你，作为一名开发者，是来使用这座工厂生产产品的客户。你不需要了解每一台机器的构造和工作原理，你只需要一个简单的订单窗口，告诉工厂你需要什么，然后拿到成品即可。

fecal 的公共接口就是这个订单窗口。它隐藏了内部复杂的 C++ 实现，为你提供了一套简单、统一的 C 语言函数，让你能够轻松地创建编码器、解码器，并执行数据恢复任务。

为什么需要一个公共接口？

在网络通信中，数据包丢失是一个常见问题。比如，你正在视频通话，突然画面卡顿或出现马赛克，这很可能就是因为一部分视频数据包在传输过程中丢失了。fecal 的核心使命就是解决这个问题。它通过生成一些额外的“冗余”数据包，使得接收方在丢失部分原始数据包的情况下，依然能够完整地恢复出原始数据。

这个公共接口的设计目标就是让这个过程尽可能简单。它解决了以下问题：

易用性：提供简单的 C 函数，而不是暴露复杂的 C++ 类和模板。这使得任何熟悉 C 语言的开发者都能快速上手。
稳定性：C 语言的 ABI（应用程序二进制接口）非常稳定。这意味着即使 fecal 内部的 C++ 代码更新换代，只要 C 接口保持不变，你的应用程序就无需重新编译。
封装性：将内部的复杂逻辑（如伽罗瓦域 (GF(256)) 运算）封装起来，让你只需关注“输入什么”和“得到什么”。

核心组件概览

fecal 的公共接口主要围绕几个核心概念构建，这些概念都定义在头文件 fecal.h 中。

graph TD
    A[用户应用程序] --> B{"FEC公共接口(fecal.h)"}
    subgraph fecal库内部
        B --> C[编码器]
        B --> D[解码器]
    end

    C -- 生成 --> E[冗余数据]
    D -- 接收 --> F[原始数据 + 冗余数据]
    D -- 恢复 --> G[丢失的原始数据]

    style B fill:#f9f,stroke:#333,stroke-width:2px

初始化 (fecal_init)：在使用库的任何功能之前，必须先调用这个函数来完成一些全局设置。就像启动一台机器的总开关。
符号 (FecalSymbol)：这是一个标准的数据容器。无论是你想要保护的原始数据块，还是库生成的冗余数据块，都被统一称为“符号”。它是一个简单的结构体，包含了数据指针、大小和索引。
```
// fecal.h
typedef struct FecalSymbolT
{
    void* Data;      // 指向数据缓冲区的指针
    unsigned Bytes;  // 数据缓冲区的大小（字节）
    unsigned Index;  // 数据的索引
} FecalSymbol;
```
这个结构体让数据交换变得清晰明了。
编码器 (FecalEncoder)：当你提供一组原始数据符号后，编码器 (Encoder)负责生成用于恢复的冗余符号。
解码器 (FecalDecoder)：当数据传输后，解码器 (Decoder) 接收它收到的所有符号（包括原始符号和冗余符号），并在数据不完整时尝试恢复丢失的部分。
资源释放 (fecal_free)：编码器和解码器在创建时会分配内存。当你使用完毕后，需要调用此函数来释放这些资源，避免内存泄漏。

一个简单的端到端示例

让我们通过一个具体的场景来感受一下 fecal 公共接口的用法。

场景：我们要发送 3 个数据包，但担心其中一个可能会在网络中丢失。因此，我们决定生成 1 个额外的冗余包来保护我们的数据。

第 1 步：发送方（编码）

发送方需要将原始数据打包，并生成一个冗余包。

初始化 fecal 库。

#include "fecal.h"

// 检查库版本并初始化
if (fecal_init() != Fecal_Success) {
    // 初始化失败，处理错误
    return -1;
}

这是使用 fecal 的第一步，永远不要忘记它。

准备原始数据。

// 假设我们有 3 个数据包，每个 10 字节
const unsigned kPacketCount = 3;
const unsigned kPacketSize = 10;
char original_data[kPacketCount][kPacketSize] = {
    "packet 0", // 数据包 0
    "packet 1", // 数据包 1
    "packet 2"  // 数据包 2
};

// 将数据指针存入一个数组
void* input_data[kPacketCount];
for (unsigned i = 0; i < kPacketCount; ++i) {
    input_data[i] = original_data[i];
}

fecal 需要一个指向所有原始数据块的指针数组。

创建编码器。
```
uint64_t total_bytes = kPacketCount * kPacketSize;

// 创建编码器
FecalEncoder encoder = fecal_encoder_create(
    kPacketCount,
    input_data,
    total_bytes
);
```
我们告诉 fecal 我们有多少个原始数据包以及它们的总大小。fecal 会返回一个 FecalEncoder 句柄，它像一个遥控器，后续我们将用它来操作编码器。

生成冗余包。

char recovery_buffer[kPacketSize]; // 为冗余包准备缓冲区
FecalSymbol recovery_symbol;
recovery_symbol.Data = recovery_buffer;
recovery_symbol.Bytes = kPacketSize;
recovery_symbol.Index = 0; // 第一个冗余包，索引从 0 开始

// 生成冗余数据
fecal_encode(encoder, &recovery_symbol);

我们准备一个 FecalSymbol 结构，填入我们准备好的缓冲区和期望的冗余包索引，然后调用 fecal_encode。函数执行后，recovery_buffer 中就包含了神奇的冗余数据。

释放资源。
```
fecal_free(encoder);
```
编码完成后，记得用 fecal_free 清理编码器占用的内存。

现在，发送方总共有 4 个数据包可以发送：3 个原始包 + 1 个冗余包。

第 2 步：接收方（解码）

假设在传输过程中，索引为 1 的原始包（内容为 "packet 1"）不幸丢失了。接收方收到了原始包 0、原始包 2 和我们生成的冗余包。

初始化 fecal 库（同样需要）。
```
fecal_init();
```

创建解码器。

// 使用与编码器相同的参数创建解码器
uint64_t total_bytes = kPacketCount * kPacketSize;
FecalDecoder decoder = fecal_decoder_create(kPacketCount, total_bytes);

解码器需要知道原始数据的布局（总共有多少个包，总大小是多少），以便为恢复工作做准备。

添加收到的数据。

// 添加收到的原始包 0
FecalSymbol original_0;
original_0.Data = original_data[0]; // "packet 0"
original_0.Bytes = kPacketSize;
original_0.Index = 0;
fecal_decoder_add_original(decoder, &original_0);

// 添加收到的原始包 2
FecalSymbol original_2;
original_2.Data = original_data[2]; // "packet 2"
original_2.Bytes = kPacketSize;
original_2.Index = 2;
fecal_decoder_add_original(decoder, &original_2);

// 添加收到的冗余包
FecalSymbol recovery_0;
recovery_0.Data = recovery_buffer; // 之前生成的冗余数据
recovery_0.Bytes = kPacketSize;
recovery_0.Index = 0;
fecal_decoder_add_recovery(decoder, &recovery_0);

我们把手头有的牌（收到的数据包）都告诉解码器。注意，我们使用 fecal_decoder_add_original 添加原始包，用 fecal_decoder_add_recovery 添加冗余包。

执行解码。

RecoveredSymbols recovered;
int result = fecal_decode(decoder, &recovered);

if (result == Fecal_Success) {
    // 成功恢复！
    // recovered.Count 会是 1
    // recovered.Symbols[0].Index 会是 1
    // recovered.Symbols[0].Data 指向已恢复的数据
}

调用 fecal_decode 触发恢复过程。如果收到的数据足够（在这个例子中，3 个包足以恢复 3 个原始包中的任意 1 个），函数会返回 Fecal_Success，并且 recovered 结构体中会包含所有被恢复的数据包信息。

释放资源。
```
fecal_free(decoder);
```
解码器使用完毕后，同样需要释放。

通过这个简单的流程，我们成功地利用一个冗余包恢复了丢失的数据包！

接口背后的秘密

你可能会好奇，fecal_encoder_create 这样的 C 函数是如何与 fecal 库内部的 C++ 世界协同工作的？这背后的技术被称为 C Wrapper 或 Adapter Pattern。

fecal.h 是对外的 C 语言接口，而 fecal.cpp 则是连接 C 和 C++ 世界的桥梁。

让我们看看 fecal_encoder_create 在 fecal.cpp 中的简化实现：

// 来自 fecal.cpp
FECAL_EXPORT FecalEncoder fecal_encoder_create(unsigned input_count, ...)
{
    // ... 其他代码 ...

    // 1. 在堆上创建一个 C++ Encoder 对象
    fecal::Encoder* encoder = new fecal::Encoder;
    
    // 2. 调用该 C++ 对象的成员函数进行初始化
    encoder->Initialize(input_count, ...);

    // 3. 将 C++ 对象指针“伪装”成一个通用的 C 指针返回
    return reinterpret_cast<FecalEncoder>(encoder);
}

这个过程可以用一个时序图来表示：

sequenceDiagram
    participant UserApp as 用户应用程序 (C)
    participant PublicAPI as FEC 公共接口 (fecal.cpp)
    participant EncoderClass as fecal::Encoder (C++ 内部类)

    UserApp->>PublicAPI: 调用 fecal_encoder_create(...)
    PublicAPI->>EncoderClass: new fecal::Encoder()
    PublicAPI->>EncoderClass: 调用 Initialize(...) 方法
    EncoderClass-->>PublicAPI: 返回初始化结果
    PublicAPI-->>UserApp: 返回 FecalEncoder 句柄

FecalEncoder 类型本质上是一个不透明的指针。C 代码持有这个指针，但并不知道它指向一个 C++ 对象。当 C 代码调用 fecal_encode(encoder, ...) 时，fecal.cpp 中的代码会再次将这个指针转换回 fecal::Encoder* 类型，然后调用其对应的 C++ 成员函数。

这种设计模式非常巧妙，它完美地实现了我们之前提到的所有优点：易用、稳定且封装良好。

总结

在本章中，我们学习了 fecal 库的门户——它的公共 C 语言接口。我们了解到：

该接口旨在提供一种简单、稳定的方式来使用 fecal 的核心功能。
主要操作包括：初始化库、创建编码器/解码器、添加数据、执行编解码以及释放资源。
通过一个端到端的例子，我们实践了如何利用 fecal 来保护数据并在发生丢失时进行恢复。
我们还窥探了接口背后的 C/C++ 桥接机制，理解了它是如何将复杂的内部实现封装起来的。

现在你已经掌握了与 fecal 沟通的基本语言。在下一章中，我们将推开第一扇门，深入探索这个接口背后的第一个核心组件：编码器 (Encoder)，去看看冗余数据包究竟是如何被创造出来的。