NMS SDK 集成一个设备管理功能需要几步？

四步：1) api_snmp_init() 初始化协议栈（单例）；2) api_snmp_agent_create() 创建 Agent（配置版本与共同体）；3) 用 api_snmp_create_get_varbind() 构造 OID 并发起 api_snmp_get()，结果通过注册的响应回调异步返回；4) 退出时 api_snmp_agent_remove() 并 api_snmp_destroy() 释放资源。

为什么 GET 请求没有响应？

依次排查：① 目标 Agent 是否运行、SNMP 版本与共同体是否匹配（-v / -c）；② IP 与端口是否正确（默认 161）；③ 超时时间是否过短（默认 5000ms）；④ V3 请求是否携带 -u 用户名及认证加密参数；⑤ 设备侧是否配置了 NMS 白名单。

Trap 监听如何实现？

两步：先 api_snmp_register_trap_callback() 注册回调，再 api_snmp_start_trap_listener(162) 启动监听线程；收到设备上报的 Trap/Inform 后 SDK 在回调中返回来源 IP、端口与变量绑定列表（最多 64 条）。Windows 运行需管理员权限占用 162 端口。

NMS SDK 和 Agent SDK 怎么配合闭环？

NMS SDK 运行在管理端：161 端口向设备发 GET/SET/GETNEXT/GETBULK 采集数据，162 端口监听设备上报的 Trap/Inform；Agent SDK 运行在设备端：监听 161 提供 MIB 数据，业务异常时向 162 主动上报。可用 xxlsnmpnms CLI 与 Agent Demo 直接联调验证。

CLI、API Demo、网管服务、Web 网桥怎么选？

CLI（xxlsnmpnms）适合联调验证与脚本化运维，命令对齐 Net-SNMP；API Demo（xxl_nms_snmp_demo）演示单窗口前台命令+后台 Trap 监听，适合学习集成；网管服务（xxl_snmp_nms_service）面向万级 Agent 批量运维，常驻后台；Web 网桥（snmp_web_bridge）对外提供 HTTP 8098 接口，适合 Web 前端集成。

xxl NMS SDK API 集成指南：多 Agent 管理与告警监听开发

上一篇《xxlsnmpnms CLI 实战》介绍了命令行的对接验证；本篇为配套的 NMS SDK API 集成指南：以 demo/snmp_api_demo.c 为范本，讲解如何基于 nms_snmp_api.h 把多 Agent 管理、数据采集、Trap 监听接入你自己的网管应用。

一、管理闭环与单窗口双能力架构

NMS ↔ Agent 闭环：161 端口采集数据，162 端口接收告警

snmp_api_demo.c 实现"前台命令交互 + 后台 Trap 监听"的单窗口模式，无需多终端切换：主交互模块接收用户命令（get、set-led1 等）触发 SNMP 操作；后台监听线程独立运行，收到 Trap/Inform 后自动刷新界面并恢复输入提示符，不阻塞前台操作。开发网管工具时可直接复用该架构。

二、四步集成：最小示例代码

// 步骤 1：注册响应回调（异步接收 GET/SET 结果）
static void response_cb(char* agent_ip, uint16 agent_port, char* username,
                        ApiSnmpCmdType cmd_type, ApiSnmpResponse* resp, void* user_data)
{
    // 遍历 resp->varbinds，按 vb->type 解析值；
    // TIMETICKS 除以 100 得秒数，OCTET_STRING 直接读 str_val
}

int main(void)
{
    // 步骤 2：初始化协议栈（单例，只调用一次）
    api_snmp_init();
    api_snmp_register_response_callback(response_cb);

    // 步骤 3：创建 Agent（管理目标设备，配置版本与共同体）
    ApiSnmpAgentConfig cfg = {0};
    cfg.version = API_SNMP_VERSION_2C;
    strcpy(cfg.community, "public");
    api_snmp_agent_create("192.168.3.230", 161, &cfg);

    // 步骤 4：构造 VarBind 并发起 GET（结果经回调返回）
    ApiSnmpVarBind vb;
    api_snmp_create_get_varbind("1.3.6.1.2.1.1.1.0", &vb);
    api_snmp_get("192.168.3.230", 161, NULL, &vb, 1, 2000, NULL);

    // 退出：移除 Agent 并销毁协议栈，避免资源泄漏
    api_snmp_agent_remove("192.168.3.230", 161);
    api_snmp_destroy();
    return 0;
}

开发流程遵循"环境配置 → 初始化 → 功能调用 → 资源释放"闭环：Windows 下 Trap 监听 162 端口需管理员权限，Linux 需注册 SIGINT 处理以便安全退出。

三、API 分组速查（api_snmp_*）

3.1 生命周期

接口	说明
`api_snmp_init()`	初始化 SNMP 模块（必须先调用，建议单例防重复初始化）
`api_snmp_destroy()`	销毁模块，释放全部资源

3.2 Agent 管理（多设备集中管理）

接口	说明
`api_snmp_agent_create(ip, port, config)`	创建 Agent，config 含 version / community
`api_snmp_agent_remove(ip, port)`	移除 Agent，释放连接资源
`api_snmp_agent_exist(ip, port)`	检查 Agent 是否存在（避免重复创建）
`api_snmp_get_agent_count() / get_agent_list()`	获取已管理 Agent 数量与信息列表
`api_snmp_user_add / user_remove / get_user_count / get_user_list`	V3 用户的增删与查询

3.3 数据交互（GET / NEXT / BULK / SET）

接口	说明
`api_snmp_get(ip, port, user, varbinds, cnt, timeout, ud)`	GET：读取指定 OID 值，支持批量（单请求上限 10 条）
`api_snmp_get_next(...)`	GET-NEXT：遍历 MIB 树下一个节点
`api_snmp_get_bulk(..., non_repeaters, max_repetitions, ...)`	GET-BULK：批量遍历（v2c/v3），对应 CLI 的 -Cn / -Cr
`api_snmp_set(...)`	SET：设置 OID 值（varbinds 需含类型与值）

V1/V2C 请求 username 传 NULL；timeout 单位毫秒；user_data 在回调中原样带回。demo 中默认超时 2000ms。

3.4 Trap 监听与回调

接口	说明
`api_snmp_start_trap_listener(port)`	启动 Trap 监听（默认 162），接收设备主动上报
`api_snmp_stop_trap_listener()`	停止 Trap 监听
`api_snmp_register_response_callback(cb)`	注册请求响应回调（GET/SET 等结果异步返回）
`api_snmp_register_trap_callback(cb, user_data)`	注册 Trap 回调（收到告警时触发）

回调中 ApiSnmpResponse 携带 request_id、错误码、协议错误状态（如 noSuchInstance=16）与变量绑定列表；ApiSnmpTrapMessage 携带版本、安全参数与最多 64 条变量绑定。

3.5 工具接口

接口	说明
`api_snmp_create_get_varbind(oid, vb)`	构造 GET 用 VarBind（无需值）
`api_snmp_create_set_varbind(oid, type_str, value_str, vb)`	构造 SET 用 VarBind（type_str 如 "int" / "string"）
`api_snmp_mib_load(path)`	加载 MIB 文件（OID 名称↔数字转换）
`api_snmp_oid_validate(oid)`	校验 OID 合法性
`api_snmp_error_to_str / error_status_to_str`	API 错误码 / 协议错误状态转可读文本
`api_snmp_set_log_level(level)`	设置日志级别（DEBUG/INFO/WARN/ERROR）

四、四种交付形态与 CLI 速查

程序	定位	典型用法
xxlsnmpnms	CLI 工具（Net-SNMP 风格，联调首选）	get / set / getnext / bulkwalk / traplisten
xxl_nms_snmp_demo_*	API 交互 Demo（单窗口双能力）	start-listen / get / set-led1 / bulkwalk / exit
xxl_snmp_nms_service_*	网管服务（万级 Agent，常驻后台）	后台运行，动态库加载，多 OID 批量操作
snmp_web_bridge	Web 网桥（HTTP 8098）	代理转发 NMS 请求（127.0.0.1:8099），日志同步前端

# CLI 常用命令（命令风格对齐 Net-SNMP，零成本迁移）
xxlsnmpnms get -v 2c -c public 192.168.3.230 1.3.6.1.2.1.1.1.0
xxlsnmpnms getnext -v 2c -c public 192.168.3.230 1.3.6.1.2.1.1
xxlsnmpnms bulkwalk -v 2c -c public 192.168.3.230 1.3.6.1.2.1.1 -Cn 0 -Cr 5
xxlsnmpnms traplisten -p 162
# V3 示例：-u 用户名 -a 认证算法 -A 认证密码 -x 加密算法 -X 加密密码

五、平台与端口矩阵

平台	SDK 库	交付程序
Linux x86_64	libxxl_nms_sdk.so（+ 静态库 .a / .map）	xxlsnmpnms、xxl_nms_snmp_demo_linux、xxl_snmp_nms_service_linux、snmp_web_bridge
Windows x86_64	xxl_nms_sdk.dll（+ .lib）	xxlsnmpnms.exe、xxl_nms_snmp_demo_windows.exe、xxl_snmp_nms_service_windows.exe、snmp_web_bridge.exe
ARM64	libxxl_nms_sdk_arm64.so（+ .a / .map）	snmp_web_bridge_arm64

端口	用途
161	远端设备 SNMP 查询默认端口（CLI -dp 可改）
162	NMS Trap/Inform 监听默认端口（CLI -p 可改）
8098 / 8099	Web 网桥 HTTP 对外端口 / NMS 代理端口