Agent SDK 集成一个业务 OID 需要几步？

五步：1) 实现 MIB 读/写回调函数；2) agent_snmp_init() 初始化协议栈（配置共同体、引擎 ID、监听端口）；3) agent_snmp_mib_register() 注册业务 OID 并绑定回调；4) agent_snmp_start() 启动监听；5) 主循环持续调用 agent_snmp_loop()（多线程 OS 自动调度），退出时先 agent_snmp_stop() 再 agent_snmp_deinit()。

MIB 读回调返回的数据为什么 NMS 读不到？

最常见原因是回调中漏设 value_len 字段。SDK 编解码依赖该字段，读回调必须同时填充 type、value 与 value_len（如 sizeof(int32)），否则返回数据无法正确编码。

Trap 和 Inform 在 Agent SDK 里怎么选？

Trap 为单向报文，NMS 不确认，适合普通告警；Inform 等待 NMS 应答确认（无应答自动重传），适合严重告警。Agent SDK 分别提供 agent_snmp_trap_custom() 与 agent_snmp_inform_custom()，target_ip 传 NULL 使用默认 NMS，target_port 传 0 默认 162。

v1v2_only / v3_xxlcrypto / v3_libtom 三个版本怎么选？

v1v2_only 仅支持 SNMPv1/v2c，体积最小；v3_xxlcrypto 为默认版本，完整支持 v1/v2c/v3 且使用自研 XXL 加密；v3_libtom 使用 libtomcrypt 第三方加密，仅 Linux 可编译（Windows 仅有 MSVC 静态库，MinGW 不兼容）。

如何限制哪些 NMS 能访问设备？

使用 IP 白名单：agent_snmp_whitelist_add() 添加允许访问的 NMS IPv4（最多 8 条），白名单之外的 IP 请求将被拒绝；也可在 xxlsnmpd.ini 的 [whitelist] 段配置 allow_ip（逗号分隔）。白名单为空表示允许所有 IP 访问。

xxl Agent SDK 快速集成与 API 速查：设备端 SNMP 能力开发指南

上一篇《xxl Agent SDK 演示 CLI》介绍了设备端命令行实战；本篇为配套的 API 集成指南：聚焦如何把 agent_snmp_api.h 的协议能力接入你自己的业务程序——从最小集成代码开始，到全量接口速查、平台与库版本选型、集成排错，业务开发人员可直接对照开发。

一、五步集成：最小示例代码

以"温度采集 OID 暴露给网管"为例，完整链路只需五步（与 demo/appdemo.c 同构）：

Agent SDK 集成五步：回调 → 初始化 → 注册 OID → 启动 → 主循环与退出

// 步骤 1：实现业务 MIB 读回调（NMS 查询时被调用）
static AgentSnmpError read_temp(const char* oid, AgentSnmpVarBind* out_val, void* user_arg)
{
    out_val->type = AGENT_SNMP_BER_INTEGER;
    out_val->value.int_val = hardware_get_temp();   // 换成你的真实采集逻辑
    out_val->value_len = sizeof(int32);             // 必须赋值数据长度
    return AGENT_SNMP_ERR_SUCCESS;
}

int main(void)
{
    // 步骤 2：初始化协议栈
    ApiSnmpConfig cfg = {0};
    strcpy(cfg.ro_community, "public");
    strcpy(cfg.rw_community, "private");
    memcpy(cfg.engine_id, "DEV001", 6);
    cfg.engine_id_len = 6;
    cfg.snmp_listen_port = 161;
    cfg.mib_poll_ms = 1000;
    if (agent_snmp_init(&cfg) != AGENT_SNMP_ERR_SUCCESS) return -1;

    // 步骤 3：注册业务 OID（绑定回调，1000ms 自动轮询刷新）
    agent_snmp_mib_register(".1.3.6.1.4.1.12345.1.1.0",
                            AGENT_MIB_READ_ONLY, read_temp, NULL, 1000, NULL);

    // 步骤 4：启动 UDP 监听
    agent_snmp_start();

    // 步骤 5：主循环（多线程 OS 自动调度；裸机 10ms 周期调用）
    while (1) {
        agent_snmp_loop();
        /* 业务逻辑：温度超限时主动上报 */
        /* agent_snmp_trap_custom(NULL, 0, ".1.3.6.1.4.1.12345.2.1", &vb, 1); */
        sleep(10);
    }

    agent_snmp_stop();    // 退出：先停监听
    agent_snmp_deinit();  // 再释放全部资源
    return 0;
}

要点提醒：读回调必须同时设置 type、value 与 value_len——SDK 编解码依赖长度字段，漏设会导致 NMS 读到空值；无 OS 裸机场景需在 10ms 周期内反复调用 agent_snmp_loop() 驱动协议栈。

二、API 分组速查（agent_snmp_*）

2.1 生命周期

接口	说明
`agent_snmp_init(cfg)`	初始化协议栈，cfg 禁止 NULL
`agent_snmp_start()`	启动 UDP 监听、MIB 轮询、Trap 队列、V3 计时模块
`agent_snmp_stop()`	临时停止监听与任务，资源不销毁
`agent_snmp_deinit()`	彻底释放套接字/内存/互斥锁，退出必须调用
`agent_snmp_loop()`	无 OS 裸机 10ms 轮询入口；多线程 OS 自动调度无需调用
`agent_snmp_get_state()`	查询运行状态（未初始化/已停止/运行中）
`agent_snmp_get_community()`	读取当前 v1/v2c 读写共同体
`agent_snmp_get_engine_id()`	读取 SNMPv3 引擎 ID，返回实际字节长度

2.2 MIB 节点管理

接口	说明
`agent_snmp_mib_register(oid, perm, read, write, poll_ms, arg)`	注册 OID 节点，绑定读写回调；poll_ms=0 关闭自动采集
`agent_snmp_mib_unregister(oid)`	动态注销节点
`agent_snmp_mib_refresh(vb)`	业务数据变更时主动刷新 OID 缓存
`agent_snmp_mib_get_count()`	已注册节点总数（上限 32）

2.3 SNMPv3 USM 安全用户

接口	说明
`agent_snmp_set_engine_id(id, len)`	动态设置引擎 ID，自动重算全部用户密钥
`agent_snmp_v3_user_add(user)`	新增 USM 用户，自动基于引擎 ID 派生密钥
`agent_snmp_v3_user_del(username)`	删除 USM 用户
`agent_snmp_v3_user_get(username, out)`	查询用户明文配置（密钥不对外）
`agent_snmp_v3_get_count()`	用户总数（上限 5）

2.4 Trap / Inform 主动上报

接口	说明
`agent_snmp_trap_custom(ip, port, oid, params, cnt)`	Trap 单向上报；ip=NULL 用默认 NMS，port=0 默认 162
`agent_snmp_inform_custom(ip, port, oid, params, cnt)`	Inform 可靠上报，等待 NMS 应答确认

上报口径：告警由 Agent 侧业务 APP 或 CLI 触发，NMS 侧仅监听接收；单条 Trap 变量绑定上限 8 个；发送队列满载返回 AGENT_SNMP_ERR_TRAP_QUEUE_FULL。

2.5 日志与工具

接口	说明
`agent_snmp_set_log_level(level)`	运行时切换 DEBUG/INFO/WARN/ERROR
`agent_snmp_oid_validate(oid)`	校验点分十进制 OID 格式
`agent_snmp_err_to_str(err)`	错误码转可读文本（静态内存）
`agent_snmp_whitelist_add/remove/clear/get_count()`	NMS 访问白名单：添加/删除/清空/统计（上限 8 条）

三、关键数据结构与资源上限

3.1 核心结构体

结构体	关键字段
`ApiSnmpConfig`	ro_community / rw_community、engine_id[32]+len、snmp_listen_port、mib_poll_ms、init_log_level、max_mib_node、max_v3_user
`AgentSnmpVarBind`	oid_str[128]、type（BER）、value 联合体（int/uint/str/bytes/ip）、value_len
`AgentSnmpV3User`	username[32]、auth_alg + auth_pass、priv_alg + priv_pass
`AgentSnmpConfig`	完整全局配置快照：版本开关、共同体、V3 安全、本地引擎信息、白名单等

3.2 资源上限与端口

项	值	项	值
SNMP 监听端口	161	最大 MIB 节点	32
Trap 目标端口	162	最大 V3 用户	5
单 Trap 变量绑定	8	白名单条数	8
引擎 ID 长度	≤32 字节	最大消息长度	1024

3.3 算法枚举

类型	取值
认证（RFC3414）	NONE / MD5 / SHA1 / SHA256 / SHA256_FULL
加密（RFC3414）	NONE / DES / AES128 / 3DES / AES192 / AES256
密码编码	ASCII（Linux 默认）/ UTF-16LE（Windows 默认）

四、平台与库版本矩阵

版本	协议能力	加密实现	支持平台
v1v2_only	v1 / v2c	无	Linux / Windows / ARM32 / ARM64
v3_xxlcrypto（默认）	v1 / v2c / v3	自研 XXL 加密	Linux / Windows / ARM32 / ARM64
v3_libtom	v1 / v2c / v3	libtomcrypt	仅 Linux（Windows 仅有 MSVC 静态库，MinGW 不兼容）

# 一键编译（自动识别本机平台，编译 v1v2_only + v3_xxlcrypto）
./build_all_agent.sh

# 分步编译：先共享组件（动态库），再 API Demo
./build_agent_shared.sh -p linux -ver v3_xxlcrypto
./build_api_demo.sh -p linux -ver v3_xxlcrypto

# 产物：bin/linux/v3_xxlcrypto/xxl_agent_snmp_demo_linux_v3_xxlcrypto

配置项通过同目录 xxlsnmpd.ini 注入（[community] / [snmp] / [usm_user] / [whitelist] / [system] 五个段落），支持共同体、端口、版本开关、引擎 ID、V3 用户、白名单、系统信息；配置文件不合法时回退内置默认值并在日志中提示。

五、错误码速查（节选）

错误码	含义	错误码	含义
0 SUCCESS	成功	14 AUTH_FAILED	认证失败
2 INIT	初始化失败	15 PRIV_FAILED	加解密失败
4 PORT_IN_USE	端口被占用	16 TIME_OUT_OF_SYNC	V3 引擎时间不同步
8 OID_INVALID	OID 格式无效	18 TRAP_QUEUE_FULL	Trap 队列满载
10 MIB_FULL	MIB 节点已满（32）	21 LICENSE_LIMITED	许可证受限（试用包）