API 参考 · xtp2

wire 格式速览

xtp2 帧布局（大端） ┌──────────────────────────────────────────────┐ │ magic "xtp\2" 4B 固定标识 + 版本 │ │ total u32 整帧长度 │ │ id u64 消息 ID（请求-应答关联） │ │ flags / type / command / params 各 u16 │ │ body u32 正文长度 │ ├──────────────────────────────────────────────┤ │ [key:u16 value:u16] × params 参数长度表 │ │ command 数据 · 参数数据 · body │ └──────────────────────────────────────────────┘ type：REQUEST / RESPONSE / PUSH / EVENT · id==0 的请求无需回复

limits 默认：整帧 ≤1MiB、参数 ≤256 个、命令/键值长度各有上限——全部可在 xtp2_config 收紧（见下）。解析错误粘性：出错后到 xtp2_reset 之前不再产出消息。

创建与配置（3）

xtp2_config_init 配置

初始化配置为默认值（limits 全默认 + 默认分配器）。

void xtp2_config_init(xtp2_config *config);

约束：max_packet ∈ [32, UINT32_MAX]，其余 limits 须适配 wire

非法配置（如 max_packet 过小）在 create 时返回 E_ARGUMENT——收紧限制不会悄悄失效。

xtp2_create / xtp2_destroy 生命周期

创建 / 销毁处理器。传 NULL config 用默认值。

xtp2_result xtp2_create(const xtp2_config *config, xtp2_processor **out); void xtp2_destroy(xtp2_processor *processor);

线程：单处理器不并发；多处理器互相独立分配器：config 可注入自定义 realloc（须线程安全）

流式解析（2）

xtp2_feed 解析

增量喂入字节：一次至多产出一条消息，consumed 告诉你消费了多少。

xtp2_result xtp2_feed(xtp2_processor *processor, const void *data, size_t size, size_t *consumed, xtp2_message *message);

返回：XTP2_MORE（数据不足）/ XTP2_MESSAGE（产出）/ 负值（粘性错误）消息：值语义出参，回调/循环内使用后丢弃

官方用法（lib/xtp2.h 原文）出处签名

xtp2_processor *rx;
if ( xtp2_create(NULL, &rx) != XTP2_OK ) { ... }
while ( size ) {
    size_t iUsed;
    xtp2_message msg;
    xtp2_result r = xtp2_feed(rx, bytes, size, &iUsed, &msg);
    bytes += iUsed; size -= iUsed;
    if ( r < 0 ) break;                /* 粘性错误 */
    if ( r == XTP2_MESSAGE ) { ... }  /* 用毕/拷贝 msg 再继续 */
    if ( r == XTP2_MORE ) break;    /* 等下一轮数据 */
}

xtp2_finish 解析

流结束检查：EOF 时若还有半包，返回错误（不是静默丢弃）。

xtp2_result xtp2_finish(xtp2_processor *processor);

时机：读到 EOF（连接关闭）时

单帧与编码（3）

xtp2_decode 解析

完整缓冲单帧解码（零增量状态）。

xtp2_result xtp2_decode(xtp2_processor *processor, const void *data, size_t size, const xtp2_limits *limits, xtp2_message *message);

场景：整帧已在手上（内存/文件）

xtp2_measure / xtp2_encode 编码

先量后写：measure 算出所需字节数，encode 写入缓冲。错误时不触碰输出缓冲。

xtp2_result xtp2_measure(const xtp2_message *message, const xtp2_limits *limits, size_t *out_size); xtp2_result xtp2_encode(const xtp2_message *message, const xtp2_limits *limits, void *out, size_t out_size);

纪律：编码源与目标不重叠回环：decode→encode 字节级一致（fuzz 不变量）

参数与错误（5）

xtp2_params / xtp2_param_next 参数

参数迭代器：取头指针 / 前进到下一对 key-value span。

xtp2_iter xtp2_params(const xtp2_message *message); bool xtp2_param_next(xtp2_iter *iter, xtp2_span *key, xtp2_span *value);

span：显式字节长度，绝不隐式 strlen

xtp2_find 参数

按二进制精确匹配查找参数值。

bool xtp2_find(const xtp2_message *message, xtp2_span key, xtp2_span *value);

xtp2_reset / xtp2_error_string 状态

清除粘性错误让处理器可复用 / 错误码转描述文本。

void xtp2_reset(xtp2_processor *processor); const char *xtp2_error_string(xtp2_result result);

语义：错误粘性直到 reset

xtp2 扩展参考