数据类型与结构体
本页汇总 OnePath 核心 API 涉及的数据结构：接收数据样本、查询回复、查询请求、发现节点、节点标识，以及各类选项结构体（*_opts_t）与其默认值宏。句柄类型见 总览，常量取值见 工具与常量。
onepath_sample_t — 数据样本
订阅回调或拉取通道收到的一条数据样本。
c
typedef struct {
const char *key; /* key expression (以 null 结尾) */
const void *data; /* 载荷指针 */
size_t data_len; /* 载荷长度 (字节) */
const char *encoding; /* 编码字符串, 可能为 NULL */
int kind; /* ONEPATH_SAMPLE_PUT 或 ONEPATH_SAMPLE_DELETE */
const void *attachment; /* 附件数据, 可能为 NULL */
size_t attachment_len; /* 附件长度 (字节) */
} onepath_sample_t;| 字段 | 说明 |
|---|---|
key | 数据的 key expression，以 null 结尾的字符串 |
data | 载荷数据指针，长度由 data_len 指定 |
data_len | 载荷字节数 |
encoding | 编码标识字符串（如 "text/plain"），可能为 NULL 表示默认编码 |
kind | 样本类型：ONEPATH_SAMPLE_PUT（数据）或 ONEPATH_SAMPLE_DELETE（删除） |
attachment | 附件数据指针，可能为 NULL |
attachment_len | 附件字节数 |
所有权
回调或拉取通道得到的 onepath_sample_t 已被深拷贝、归用户所有，用完后必须调用 onepath_sample_release() 释放。详见 内存管理。
onepath_reply_t — 查询回复
查询操作（Get / Requester / Liveliness）返回的一条回复。
c
typedef struct {
int is_ok; /* 1 = 数据回复, 0 = 错误回复 */
const char *key; /* key (is_ok 为 1 时有效) */
const void *data; /* 载荷 */
size_t data_len;
const char *encoding; /* 编码字符串, 可能为 NULL */
const char *err_msg; /* 错误消息 (is_ok 为 0 时有效) */
size_t err_msg_len;
} onepath_reply_t;| 字段 | 说明 |
|---|---|
is_ok | 1 表示成功回复（含数据），0 表示错误回复 |
key | 回复的 key expression，仅在 is_ok == 1 时有效 |
data | 载荷数据指针 |
data_len | 载荷字节数 |
encoding | 编码标识字符串，可能为 NULL |
err_msg | 错误描述消息，仅在 is_ok == 0 时有效 |
err_msg_len | 错误消息长度 |
所有权
通过 onepath_reply_recv() / onepath_reply_try_recv() 取得的回复，用完后必须调用 onepath_reply_release() 释放。
onepath_request_t — 查询请求
Responder 回调收到的查询请求。
c
typedef struct {
const char *key; /* 查询 key expression */
const char *parameters; /* 查询参数, 可能为空字符串 */
const void *payload; /* 查询载荷, 可能为 NULL */
size_t payload_len;
void *_opaque; /* 保留字段, 必须保持原值, 不可修改 */
} onepath_request_t;| 字段 | 说明 |
|---|---|
key | 查询的 key expression |
parameters | 查询参数字符串，可能为空字符串 "" |
payload | 查询携带的载荷，可能为 NULL |
payload_len | 载荷字节数 |
_opaque | 内部保留字段，由 OnePath 在创建时填充；用户必须原样透传回 onepath_request_reply 等接口，不可读取或修改，否则行为未定义 |
所有权
回调收到的 onepath_request_t 已被克隆、归用户所有，可保存到队列异步回复；回复完成后必须调用 onepath_request_release() 释放。
onepath_hello_t — 发现节点
通过 scout 发现的网络节点信息。
c
typedef struct {
char zid[33]; /* 16 字节节点 ID 的十六进制字符串 */
int whatami; /* ONEPATH_ROUTER / ONEPATH_PEER / ONEPATH_CLIENT */
const char **locators; /* 以 NULL 结尾的定位器字符串数组 */
size_t num_locators;
} onepath_hello_t;| 字段 | 说明 |
|---|---|
zid | 节点标识符，16 字节 ID 的十六进制表示（32 字符 + null 终止符） |
whatami | 节点类型：ONEPATH_ROUTER、ONEPATH_PEER 或 ONEPATH_CLIENT |
locators | 网络定位器字符串数组，以 NULL 结尾 |
num_locators | 定位器数量 |
TIP
onepath_hello_t 仅在发现回调执行期间有效，如需保留须自行拷贝。
onepath_node_id_t — 节点标识
c
typedef struct {
char zid[33];
} onepath_node_id_t;| 字段 | 说明 |
|---|---|
zid | 节点标识符，16 字节 ID 的十六进制表示（32 字符 + null 终止符） |
信息回调收到的 onepath_node_id_t 同样仅在回调期间有效。
选项结构体
onepath_pub_opts_t — 发布者选项
c
typedef struct {
const char *encoding; /* NULL = 默认编码 */
int congestion_control; /* ONEPATH_CC_DROP (默认) 或 ONEPATH_CC_BLOCK */
} onepath_pub_opts_t;
#define ONEPATH_PUB_OPTS_DEFAULT { NULL, ONEPATH_CC_DROP }| 字段 | 说明 |
|---|---|
encoding | 默认编码字符串，NULL 表示使用引擎默认编码 |
congestion_control | 拥塞控制策略，见 拥塞控制常量 |
onepath_get_opts_t — 查询选项
c
typedef struct {
uint64_t timeout_ms; /* 默认: 5000 ms */
const void *payload; /* 可选查询载荷, 可能为 NULL */
size_t payload_len;
int consolidation; /* 应答合并模式 (v0.10.0+), 默认 AUTO */
int target; /* 查询目标 (v0.10.0+), 默认 BEST_MATCHING */
} onepath_get_opts_t;
#define ONEPATH_GET_OPTS_DEFAULT \
{ 5000, NULL, 0, ONEPATH_CONSOLIDATION_AUTO, ONEPATH_QUERY_TARGET_BEST_MATCHING }| 字段 | 说明 |
|---|---|
timeout_ms | 查询超时（毫秒），默认 5000 |
payload / payload_len | 可选查询载荷，NULL 表示不携带 |
consolidation | 应答合并模式（v0.10.0+），ONEPATH_CONSOLIDATION_AUTO（默认）/ _NONE / _MONOTONIC / _LATEST |
target | 查询目标（v0.10.0+），ONEPATH_QUERY_TARGET_BEST_MATCHING（默认）/ _ALL / _ALL_COMPLETE |
多应答者投票场景
要让查询路由到全部匹配应答者（如多副本投票）须把 target 设为 ONEPATH_QUERY_TARGET_ALL，同时把 consolidation 设为 ONEPATH_CONSOLIDATION_NONE——否则同键应答会被合并，看不到每一份。常量含义见 工具与常量。
onepath_requester_opts_t — Requester 选项
c
typedef struct {
uint64_t timeout_ms; /* 默认: 5000 ms */
} onepath_requester_opts_t;
#define ONEPATH_REQUESTER_OPTS_DEFAULT { 5000 }| 字段 | 说明 |
|---|---|
timeout_ms | 每次查询的超时（毫秒），默认 5000 |
onepath_write_opts_t — 扩展写入选项
c
typedef struct {
const char *encoding; /* NULL = 默认编码 */
const void *attachment; /* NULL = 无附件 */
size_t attachment_len;
} onepath_write_opts_t;
#define ONEPATH_WRITE_OPTS_DEFAULT { NULL, NULL, 0 }| 字段 | 说明 |
|---|---|
encoding | 本次写入的编码字符串，NULL 表示默认编码 |
attachment / attachment_len | 随消息携带的附件数据，NULL 表示无附件 |
用于 onepath_publisher_write() 与 onepath_put_with_opts()，可自定义编码并附带元数据。
其他选项结构体（进阶能力）
以下选项结构体属于进阶能力，定义与用法见对应专题页：