核心 API 总览与约定
OnePath™ 统一逻辑网络（Unified Logical Network, ULN）是一个 C 语言通信中间件，提供简洁的 C 接口实现发布/订阅、查询/应答、存活感知与会话管理。本手册是 OnePath 核心数据面 API 的权威参考，本页先讲清贯穿全手册的设计哲学与通用约定。
设计理念
- 单头文件：仅需
#include <onepath.h>即可使用全部核心功能。 - 统一错误码：所有可失败的函数返回
int错误码，ONEPATH_OK（值为0）表示成功，负值表示具体错误。详见 错误码。 - 回调 + 通道双模：数据接收既支持回调（push）模式，也支持拉取（pull）通道模式，按场景自由选择。
- C 接口、C++ 兼容：头文件已含
extern "C"包装，可直接在 C++ 项目中使用，无需额外封装。 - 双变体支持：统一的 API，在编译期选择 full 全功能变体或 tiny 轻量变体。
不透明句柄模型
OnePath 中的所有资源都以不透明句柄（opaque handle）的形式暴露给用户。你拿到的是一个类型化的句柄值，内部结构对用户不可见，只能通过 API 操作。
| 句柄类型 | 说明 |
|---|---|
onepath_session_t | 会话句柄，所有操作的基础 |
onepath_config_t | 配置构建器句柄 |
onepath_publisher_t | 发布者句柄 |
onepath_subscriber_t | 订阅者句柄 |
onepath_responder_t | 应答器句柄 |
onepath_requester_t | 请求者句柄 |
onepath_token_t | 存活令牌句柄 |
onepath_reply_rx_t | 回复接收通道句柄 |
onepath_sample_rx_t | 样本接收通道句柄（拉取模式订阅） |
onepath_shm_pool_t | 共享内存池句柄（仅 full） |
每个通过 onepath_declare_* / onepath_*_create / onepath_open* 创建的句柄，都有对应的 onepath_*_destroy / onepath_close 负责销毁。完整配对见 内存管理。
回调风格
OnePath 的回调统一为 void (*)(数据指针, void *userdata) 形态：第一个参数是事件数据，最后一个参数是你在注册时传入的 userdata 透传指针。两条关键规则：
- 回调可能在内部线程中触发，回调内的代码需自行保证线程安全。
- 所有权区分：订阅 / 应答回调收到的数据已被深拷贝、归用户所有，用完须显式 release；发现 / 信息回调收到的数据仅在回调执行期间有效，如需保留须自行拷贝。详见 回调函数 与 内存管理。
命名约定
- 所有公共符号以
onepath_前缀开头。 - 创建：
onepath_open*（会话）、onepath_declare_*（实体）、onepath_*_create（池/通道）。 - 销毁：
onepath_close（会话）、onepath_*_destroy、onepath_*_release（释放单条接收数据）、onepath_liveliness_undeclare（撤销令牌）。 - 选项结构体统一以
_opts_t结尾，并配有_DEFAULT宏给出默认值；几乎所有接收const *_opts *的接口都允许传NULL取全默认。 - 常量分组前缀：编码
ONEPATH_ENCODING_*、拥塞控制ONEPATH_CC_*、样本类型ONEPATH_SAMPLE_*、节点类型ONEPATH_ROUTER/PEER/CLIENT。
变体选择（一句话）
桌面 / 服务器、需要共享内存零拷贝或高级发布订阅就选 full（链接 libonepath-full.so，定义 -DCONFIG_ONEPATH_VARIANT_FULL=1）；嵌入式 / 边缘网关、对二进制尺寸敏感就选 tiny（链接 libonepath-tiny.so，定义 -DCONFIG_ONEPATH_VARIANT_TINY=1）。两变体核心 API 完全一致，full 独占的能力在 tiny 下于头文件中被剔除，误用会在编译期报错。
本手册导航
| 主题 | 页面 |
|---|---|
| 数据类型与选项结构体 | 数据类型 |
| 全部回调签名与语义 | 回调函数 |
| 会话打开 / 配置 / 关闭 | 会话管理 |
| 发布与订阅 | 发布与订阅 |
| 查询 Get | 查询 |
| 应答器 Responder | Responder |
| 请求器 Requester | Requester |
| 存活感知 Liveliness | 存活感知 |
| 节点信息与发现 | 信息与发现 |
| 路由转发助手 | 转发 |
| 工具函数与常量 | 工具与常量 |
进阶能力（独立页面）：共享内存、高级发布订阅、链路追踪、指标、拓扑感知、三模存储、三模计算、多模冗余 XMR、JSON 操作。