会话管理
会话（onepath_session_t）是一切 OnePath 操作的基础：发布、订阅、查询、应答、存活感知都在会话之上进行。本页覆盖会话的打开（默认 / peer / client / 配置文件 / 配置构建器）、配置构建器的逐项设置，以及会话关闭。
打开会话
onepath_open
c
int onepath_open(onepath_session_t *out);以默认配置打开会话（peer 模式，启用多播发现）。
- 参数：
out— 输出会话句柄 - 返回值：
ONEPATH_OK成功，其他为错误码 - 注意：使用完毕后必须调用
onepath_close()关闭
onepath_open_peer
c
int onepath_open_peer(onepath_session_t *out);以 peer 模式打开会话，等价于 onepath_open()。
- 参数：
out— 输出会话句柄 - 返回值：
ONEPATH_OK成功，其他为错误码
onepath_open_client
c
int onepath_open_client(onepath_session_t *out, const char *endpoint);以 client 模式打开会话，连接到指定端点。
- 参数：
out— 输出会话句柄endpoint— 连接端点地址，如"tcp/127.0.0.1:7447"
- 返回值：
ONEPATH_OK成功，ONEPATH_ERR_CONN连接失败
onepath_open_config_file
c
int onepath_open_config_file(onepath_session_t *out, const char *path);从 JSON5 配置文件打开会话。
- 参数：
out— 输出会话句柄path— 配置文件路径
- 返回值：
ONEPATH_OK成功，其他为错误码 - 注意：配置文件格式为 JSON5
onepath_open_with_config
c
int onepath_open_with_config(onepath_session_t *out, onepath_config_t cfg);使用配置构建器打开会话。
- 参数：
out— 输出会话句柄cfg— 配置句柄
- 返回值：
ONEPATH_OK成功 - 注意：内部拷贝配置，调用后
cfg仍有效，用完后须调用onepath_config_destroy()释放
配置构建器
配置构建器（onepath_config_t）提供逐项设置会话参数的方式，设置完成后交给 onepath_open_with_config() 打开会话。典型流程：onepath_config_new → 若干 onepath_config_set_* / onepath_config_add_endpoint → onepath_open_with_config → onepath_config_destroy。
onepath_config_new
c
int onepath_config_new(onepath_config_t *out);创建新的配置构建器。
- 参数：
out— 输出配置句柄 - 返回值：
ONEPATH_OK成功 - 注意：使用完毕后必须调用
onepath_config_destroy()销毁
onepath_config_set_mode
c
int onepath_config_set_mode(onepath_config_t cfg, const char *mode);设置会话模式。
- 参数：
cfg— 配置句柄mode— 模式字符串："peer"、"client"或"router"
- 返回值：
ONEPATH_OK成功
onepath_config_add_endpoint
c
int onepath_config_add_endpoint(onepath_config_t cfg, const char *endpoint);添加连接端点。
- 参数：
cfg— 配置句柄endpoint— 端点地址，如"tcp/192.168.1.1:7447"
- 返回值：
ONEPATH_OK成功 - 注意：可多次调用以添加多个端点
onepath_config_set_tls_ca
两个变体均支持（v0.8.0+）
TLS 在 full 与 tiny 变体下均可用，无需额外配置。
c
int onepath_config_set_tls_ca(onepath_config_t cfg, const char *ca_path);设置 TLS CA 证书路径。
- 参数：
cfg— 配置句柄ca_path— CA 证书文件路径
- 返回值：
ONEPATH_OK成功
onepath_config_set_auth
仅 full 变体可用
该接口在 tiny 变体下于头文件中被剔除，误用会在编译期报错。
c
int onepath_config_set_auth(onepath_config_t cfg, const char *user, const char *password);设置用户名/密码认证。
- 参数：
cfg— 配置句柄user— 用户名password— 密码
- 返回值：
ONEPATH_OK成功
onepath_config_set_json5
c
int onepath_config_set_json5(onepath_config_t cfg, const char *key, const char *json5_value);设置任意 JSON5 配置项，作为高级配置的"逃生舱"。
- 参数：
cfg— 配置句柄key— 配置键路径json5_value— JSON5 格式的值字符串
- 返回值：
ONEPATH_OK成功
onepath_config_enable_shm
仅 full 变体可用
启用同机自动共享内存传输。完整说明见 共享内存。
c
int onepath_config_enable_shm(onepath_config_t cfg, const onepath_shm_opts_t *opts);开启同机自动共享内存零拷贝传输，用户继续使用普通发布/订阅 API、无需手动管理内存池。opts 传 NULL 取全默认。详见 共享内存。
onepath_config_destroy
c
void onepath_config_destroy(onepath_config_t cfg);销毁配置构建器。
- 参数：
cfg— 配置句柄 - 注意：无论是否传给过
onepath_open_with_config()，均须调用此函数释放
关闭会话
onepath_close
c
void onepath_close(onepath_session_t session);关闭并销毁会话。
- 参数：
session— 会话句柄 - 注意：关闭前应先销毁所有在此会话上创建的发布者、订阅者、应答器、请求器、令牌等资源。资源销毁顺序见 内存管理。
示例
c
#include <onepath.h>
onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_set_mode(cfg, "client");
onepath_config_add_endpoint(cfg, "tcp/192.168.1.10:7447");
onepath_session_t s;
if (onepath_open_with_config(&s, cfg) != ONEPATH_OK) {
onepath_config_destroy(cfg);
return 1;
}
onepath_config_destroy(cfg); /* 配置不被会话消费, 须自行销毁 */
/* ... 使用会话 ... */
onepath_close(s);