信息与发现 (Info & Scouting)

本页覆盖会话自省与网络发现：获取本会话的节点 ID、枚举已连接的路由器与对等节点，以及在网络中主动发现节点（scout）。更全面的网络视图（谁承载哪些服务、彼此经什么传输相连）见 拓扑感知。

onepath_info_zid

int onepath_info_zid(onepath_session_t s, onepath_node_id_t *out);

获取当前会话的节点 ID。

• 参数：s — 会话句柄；out — 输出节点 ID（见 onepath_node_id_t）
• 返回值：ONEPATH_OK 成功

onepath_info_routers

int onepath_info_routers(onepath_session_t s, onepath_zid_cb cb, void *userdata);

枚举已连接的路由器节点。

• 参数：s — 会话句柄；cb — 每个路由器节点调用一次的回调；userdata — 用户数据指针
• 返回值：ONEPATH_OK 成功

onepath_info_peers

int onepath_info_peers(onepath_session_t s, onepath_zid_cb cb, void *userdata);

枚举已连接的对等节点。

• 参数：s — 会话句柄；cb — 每个对等节点调用一次的回调；userdata — 用户数据指针
• 返回值：ONEPATH_OK 成功

onepath_scout

int onepath_scout(onepath_hello_cb cb, void *userdata, uint64_t duration_ms);

在网络中发现节点（scouting）。

• 参数：
  • cb — 每发现一个节点调用一次的回调（见 回调函数）
  • userdata — 用户数据指针
  • duration_ms — 发现持续时间（毫秒）
• 返回值：ONEPATH_OK 成功
• 注意：此函数会阻塞指定时长；不需要打开会话即可调用

跨网络发现的变体差异

单机环境下两个变体均可发现本网络节点；但在跨子网 / 跨机的网络环境下，tiny 变体的 scout 可能发现 0 个节点（运行时固有差异，非配置问题），full 变体则可正常发现。这与组播接口配置无关——即使接口选择正确，tiny 在跨网络场景仍可能无响应。如需可靠的跨网络节点发现，建议使用 full 变体，或改用会话级 拓扑感知 以获取网络视图。

示例

/* 本会话节点 ID */
onepath_node_id_t self;
onepath_info_zid(s, &self);
printf("本节点: %s\n", self.zid);

/* 枚举对等节点 */
static void on_peer(const onepath_node_id_t *id, void *userdata) {
    (void)userdata;
    printf("对等节点: %s\n", id->zid);   /* id 仅回调期间有效 */
}
onepath_info_peers(s, on_peer, NULL);

/* 网络发现（无需会话） */
static void on_hello(const onepath_hello_t *hello, void *userdata) {
    (void)userdata;
    printf("发现节点 %s, %zu 个定位器\n", hello->zid, hello->num_locators);
}
onepath_scout(on_hello, NULL, 3000);   /* 阻塞 3 秒 */

内存

onepath_node_id_t 与 onepath_hello_t 均仅在回调执行期间有效，如需保留须自行拷贝。见 内存管理。