回调函数

OnePath 通过回调向用户投递异步事件：数据样本、查询请求、节点发现、节点枚举、匹配状态变化、数据丢失通知。所有回调都遵循 void (*)(事件数据, void *userdata) 形态，userdata 是注册时传入的透传指针。回调可能在 OnePath 内部线程中触发，回调内代码需自行保证线程安全。

onepath_sample_cb — 数据样本回调

typedef void (*onepath_sample_cb)(onepath_sample_t *sample, void *userdata);

用于 订阅 和 存活感知订阅。sample 已被深拷贝、归用户所有，可自由保存、传递给其他线程。用完后必须调用 onepath_sample_release(sample) 释放。

onepath_request_cb — 查询请求回调

typedef void (*onepath_request_cb)(onepath_request_t *query, void *userdata);

用于 Responder。query 已被克隆、归用户所有，可保存到队列中异步调用 onepath_request_reply() 发送回复。回复完成后必须调用 onepath_request_release(query) 释放。

onepath_hello_cb — 发现回调

typedef void (*onepath_hello_cb)(const onepath_hello_t *hello, void *userdata);

用于 节点发现 scout。每发现一个节点调用一次。hello 指针仅在回调执行期间有效，如需保留须自行拷贝。

onepath_zid_cb — 节点 ID 回调

typedef void (*onepath_zid_cb)(const onepath_node_id_t *id, void *userdata);

用于枚举已连接的路由器或对等节点（见 信息与发现）。id 指针仅在回调期间有效。

onepath_matching_cb — 匹配状态回调

typedef void (*onepath_matching_cb)(int has_match, void *userdata);

当 Requester 的匹配状态发生变化时调用。has_match 为 1 表示存在匹配的 responder，为 0 表示无匹配。

onepath_miss_cb — 丢失通知回调

typedef void (*onepath_miss_cb)(unsigned int missed_count, void *userdata);

当高级订阅者检测到数据丢失时调用，missed_count 为丢失的样本数量。仅用于 高级发布订阅。

内存归属速记

• sample（onepath_sample_cb）/ query（onepath_request_cb）：归你所有，用完须 release。
• hello（onepath_hello_cb）/ id（onepath_zid_cb）：仅回调期间有效，要留须自己拷贝。

完整规则见 内存管理。