网络拓扑感知 API
网络拓扑感知（Topology）让应用发现统一逻辑网络中有哪些节点、各节点承载哪些服务、节点之间用什么传输相连。本页是纯 API 参考，覆盖两类操作：本节点一跳局部视图（onepath_topology_local）与全局拓扑聚合（拓扑 agent + onepath_topology_snapshot）。概念解读、可视化思路与端到端示例见 网络拓扑感知。
可用性：两个变体（Full / Tiny）均支持，接口与用法一致。
onepath_topology_local与onepath_topology_agent_start在后端不具备自省能力时返回ONEPATH_ERR_UNSUPPORTED——接口始终存在、可正常编译链接，应用据此优雅降级。
数据类型
拓扑 API 的返回值由 6 个结构体描述：3 个用于局部视图（onepath_topo_link_t / onepath_topo_neighbor_t / onepath_topo_local_t），3 个用于全局图（onepath_topo_node_t / onepath_topo_edge_t / onepath_topo_graph_t）。节点以 节点 ID（sid，十六进制字符串） 标识，节点承载的 服务 以 服务标识（sign） 字符串数组给出。
onepath_topo_link_t — 一条物理链路
描述拓扑边一端的传输层信息，由 locator 解析得到。
| 字段 | 类型 | 说明 |
|---|---|---|
proto | char[16] | 传输协议（tcp / udp / serial / ...），由 locator 解析 |
dst | char[128] | 远端 locator（协议 + 地址） |
src | char[128] | 本端 locator |
mtu | uint16_t | 最大传输单元（字节），0 表示未知 |
reliable | int | 1 = 可靠链路，0 = 非可靠 / 未知 |
is_streamed | int | 1 = 流式链路 |
onepath_topo_neighbor_t — 一个直连邻居
onepath_topo_local_t.neighbors 数组的元素，描述与本节点直接相邻的一个节点。
| 字段 | 类型 | 说明 |
|---|---|---|
sid | char[33] | 邻居节点 ID（十六进制） |
whatami | int | 节点类型：ONEPATH_ROUTER / ONEPATH_PEER / ONEPATH_CLIENT |
is_shm | int | 1 = 该传输已启用共享内存 |
is_multicast | int | 1 = 组播传输 |
links | onepath_topo_link_t * | 该邻居的链路数组 |
num_links | size_t | 链路数量 |
onepath_topo_local_t — 本节点局部视图（1-hop）
onepath_topology_local() 的输出。枚举本会话所有直连传输与链路，加上本节点自身承载的服务清单。
| 字段 | 类型 | 说明 |
|---|---|---|
self_sid | char[33] | 本节点 ID |
self_whatami | int | 本节点类型 |
neighbors | onepath_topo_neighbor_t * | 直连邻居数组 |
num_neighbors | size_t | 邻居数量 |
services | const char ** | 本节点承载的服务 sign 数组（来自本会话已声明的发布者 / 订阅者 / 响应者 / 存活令牌） |
num_services | size_t | 服务数量 |
onepath_topo_node_t — 全局图中的一个节点
onepath_topo_graph_t.nodes 数组的元素。
| 字段 | 类型 | 说明 |
|---|---|---|
sid | char[33] | 节点 ID |
whatami | int | 节点类型 |
services | const char ** | 该节点承载的服务 sign 数组 |
num_services | size_t | 服务数量 |
onepath_topo_edge_t — 全局图中的一条边
onepath_topo_graph_t.edges 数组的元素，描述两个节点之间的一条连接。
| 字段 | 类型 | 说明 |
|---|---|---|
a_sid | char[33] | 边的一端节点 ID |
b_sid | char[33] | 边的另一端节点 ID |
proto | char[16] | 该边的传输协议标签 |
is_shm | int | 1 = 该边已启用共享内存 |
onepath_topo_graph_t — 聚合后的全局拓扑图
onepath_topology_snapshot() 的输出。各节点上报的局部视图合并去重为一张图：节点为各局部视图节点与邻居的并集，边为各局部邻接的并集。
| 字段 | 类型 | 说明 |
|---|---|---|
nodes | onepath_topo_node_t * | 节点数组 |
num_nodes | size_t | 节点数量 |
edges | onepath_topo_edge_t * | 边数组 |
num_edges | size_t | 边数量 |
函数
onepath_topology_local
int onepath_topology_local(onepath_session_t s, onepath_topo_local_t *out);获取本节点的局部拓扑视图（1-hop）。枚举本会话的所有直连传输与链路并填充 out；services 字段来自本会话已声明实体注册表（发布者 / 订阅者 / 响应者 / 存活令牌的 sign）。out 内部为堆分配，使用完毕须调用 onepath_topology_local_free()。
- 参数：
s— 会话句柄out— 成功时写入局部拓扑视图
- 返回值：
ONEPATH_OK成功；ONEPATH_ERR_UNSUPPORTED当前后端不支持自省；ONEPATH_ERR_NOMEM内存分配失败 - 注意：成功后必须配对调用
onepath_topology_local_free()
onepath_topology_local_free
void onepath_topology_local_free(onepath_topo_local_t *local);释放 onepath_topology_local() 分配的资源。
- 参数：
local— 待释放的局部拓扑视图，可为NULL
onepath_topology_agent_start
int onepath_topology_agent_start(onepath_session_t s);启动本节点的拓扑 agent。声明存活令牌 @onepath/topo/<self-id> 宣告在线，并注册响应端 @onepath/topo/<self-id>，收到查询时返回本节点局部拓扑视图。中继节点（router / peer）启动 agent 后，其下游 client 即使自身不跑 agent 也能被监测端发现。接口幂等。
- 参数：
s— 会话句柄 - 返回值：
ONEPATH_OK成功；ONEPATH_ERR_UNSUPPORTED当前后端不支持自省 - 注意：停止 agent 调用
onepath_topology_agent_stop()；onepath_close()也会自动停止
onepath_topology_agent_stop
void onepath_topology_agent_stop(onepath_session_t s);停止本节点的拓扑 agent 并释放资源。
- 参数：
s— 会话句柄，可为NULL
onepath_topology_snapshot
int onepath_topology_snapshot(onepath_session_t s, onepath_topo_graph_t *out,
uint64_t timeout_ms);查询并聚合全局拓扑图。向 @onepath/topo 通配键发起一次 Get，收集网络中所有运行 agent 的节点的局部视图，合并去重为一张全局图（节点 ∪ 邻居，边为各局部邻接的并集）。out 内部为堆分配，使用完毕须调用 onepath_topology_graph_free()。
- 参数：
s— 会话句柄out— 成功时写入全局拓扑图timeout_ms— 查询超时（毫秒），0表示默认5000ms
- 返回值：
ONEPATH_OK成功；ONEPATH_ERR_UNSUPPORTED当前后端不支持；ONEPATH_ERR_NOMEM内存分配失败；其他错误码表示查询失败 - 注意：成功后必须配对调用
onepath_topology_graph_free()；全局图的完整性取决于哪些节点运行了 agent
onepath_topology_graph_free
void onepath_topology_graph_free(onepath_topo_graph_t *graph);释放 onepath_topology_snapshot() 分配的资源。
- 参数：
graph— 待释放的全局拓扑图，可为NULL
内存与所有权
onepath_topology_local() 与 onepath_topology_snapshot() 通过 out 参数返回的结构体内部为堆分配，必须与对应的 free 函数严格配对；free 函数接受 NULL，可安全空转。
| 创建（堆分配 out） | 销毁 |
|---|---|
onepath_topology_local(s, &local) | onepath_topology_local_free(&local) |
onepath_topology_snapshot(s, &graph, t) | onepath_topology_graph_free(&graph) |
agent 的生命周期另成一对，且会随会话关闭自动收尾：
| 创建 | 销毁 |
|---|---|
onepath_topology_agent_start(s) | onepath_topology_agent_stop(s)（onepath_close() 亦自动停止） |
优雅降级
onepath_topology_local / onepath_topology_agent_start 在不支持自省的后端返回 ONEPATH_ERR_UNSUPPORTED，而非失败。应用应检查返回值并在该码下跳过拓扑相关逻辑，而非终止运行。
相关指南
- 网络拓扑感知 — 概念解读、两层模型、可视化思路与端到端示例