SnmpGetPduData 函数 (winsnmp.h)

  • 项目

[SNMP 可用于“要求”部分中指定的操作系统。 它可能在后续版本中变更或不可用。 请改用 Windows 远程管理，这是 WS-Man 的 Microsoft 实现。]

WinSNMP SnmpGetPduData 函数从指定的 SNMP 协议数据单元返回所选数据字段 (PDU) 。

语法

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetPduData(
  [in]  HSNMP_PDU   PDU,
  [out] smiLPINT    PDU_type,
  [out] smiLPINT32  request_id,
  [out] smiLPINT    error_status,
  [out] smiLPINT    error_index,
  [out] LPHSNMP_VBL varbindlist
);

参数

[in] PDU

SNMP PDU 的句柄。

[out] PDU_type

指向接收指定 PDU 的PDU_type 字段的变量的指针。 此参数可以是 NULL，也可以是以下值之一。

值 含义
SNMP_PDU_GET
从指定的 SNMP 变量中搜索和检索值。
SNMP_PDU_GETNEXT
在不知道变量的确切名称的情况下搜索和检索 SNMP 变量的值。
SNMP_PDU_RESPONSE
回复 SNMP_PDU_GET 或 SNMP_PDU_GETNEXT 请求。
SNMP_PDU_SET
将值存储在指定的 SNMP 变量中。
SNMP_PDU_GETBULK
使用单个请求搜索和检索多个值。
SNMP_PDU_TRAP
在 SNMPv2C 下发生异常事件时，向管理系统发出警报。

[out] request_id

指向一个变量的指针，该变量接收指定 PDU 的request_id 字段。 此参数可以为 NULL。

[out] error_status

指向接收指定 PDU 的error_status 字段的变量的指针。 如果 PDU_type 参数等于 SNMP_PDU_GETBULK，则此参数接收 PDU non_repeaters 字段的值。

此参数可以是 NULL，也可以是以下值之一。 前六个错误常见于 SNMP 版本 1 (SNMPv1) 和 SNMP 版本 2C 框架 (SNMPv2C) 。 其余错误仅在 SNMPv2C 下可用。

错误代码 含义
SNMP_ERROR_NOERROR
 代理报告在传输过程中未发生任何错误。
SNMP_ERROR_TOOBIG
 代理无法将请求的 SNMP 操作的结果放入单个 SNMP 消息中。
SNMP_ERROR_NOSUCHNAME
 请求的 SNMP 操作标识了一个未知变量。
SNMP_ERROR_BADVALUE
 请求的 SNMP 操作尝试更改变量，但它指定了语法或值错误。
SNMP_ERROR_READONLY
 请求的 SNMP 操作尝试根据变量的社区配置文件更改不允许更改的变量。
SNMP_ERROR_GENERR
 在请求的 SNMP 操作期间，出现此处列出的错误以外的错误。
SNMP_ERROR_NOACCESS
 指定的 SNMP 变量不可访问。
SNMP_ERROR_WRONGTYPE
 值指定与变量所需的类型不一致的类型。
SNMP_ERROR_WRONGLENGTH
 值指定与变量所需长度不一致的长度。
SNMP_ERROR_WRONGENCODING
 值包含与字段的 ASN.1 标记不一致的抽象语法表示法一 (ASN.1) 编码。
SNMP_ERROR_WRONGVALUE
 值不能分配给变量。
SNMP_ERROR_NOCREATION
 变量不存在，代理无法创建它。
SNMP_ERROR_INCONSISTENTVALUE
 该值与其他托管对象的值不一致。
SNMP_ERROR_RESOURCEUNAVAILABLE
 将值分配给变量需要分配当前不可用的资源。
SNMP_ERROR_COMMITFAILED
 未发生验证错误，但未更新任何变量。
SNMP_ERROR_UNDOFAILED
 未发生验证错误。 某些变量已更新，因为无法撤消其赋值。
SNMP_ERROR_AUTHORIZATIONERROR
 发生授权错误。
SNMP_ERROR_NOTWRITABLE
 变量存在，但代理无法修改它。
SNMP_ERROR_INCONSISTENTNAME
 变量不存在;代理无法创建它，因为命名对象实例与其他托管对象的值不一致。

[out] error_index

指向接收指定 PDU 的error_index 字段的变量的指针。

如果 PDU_type 参数等于 SNMP_PDU_GETBULK，则此参数接收指定 PDU 的 max_repetitions 字段的值。 此参数可以为 NULL。

[out] varbindlist

指向一个变量的指针，该变量接收指向指定 PDU 的变量绑定列表字段的句柄。 此参数可以为 NULL。 有关其他信息，请参阅以下“备注”部分。

返回值

如果函数成功，则返回值SNMPAPI_SUCCESS。

如果函数失败，则返回值SNMPAPI_FAILURE。 若要获取扩展错误信息，请调用 SnmpGetLastError。 SnmpGetLastError 函数可能会返回以下错误之一。

返回代码 说明
SNMPAPI_NOT_INITIALIZED
 SnmpStartup 函数未成功完成。
SNMPAPI_ALLOC_ERROR
 内存分配期间出错。
SNMPAPI_NOOP
 所有输出参数均为 NULL。 未执行 SNMP 操作。
SNMPAPI_PDU_INVALID
 PDU 类型无效。
SNMPAPI_OTHER_ERROR
 发生未知或未定义错误。

注解

SnmpGetPduData 函数的所有参数是必需的。 但是，除 PDU 参数之外的所有参数都可以为 NULL。 在应用程序作为 NULL 传递的参数中， SnmpGetPduData 函数不返回值。

如果 varbindlist 参数不为 NULL，SnmpGetPduData 函数始终返回新变量绑定列表对象的句柄。 此外，如果 PDU 参数指定新的 PDU，则函数还会将句柄附加到新的 PDU。

当应用程序使用不为 NULL 的 varbindlist 参数调用 SnmpGetPduData，但 PDU 参数指定现有 PDU 时，该函数将返回新的重复变量绑定列表的句柄。 函数调用不会干扰附加到现有 PDU 的句柄。 现有 PDU 是应用程序通过调用 SnmpCreatePdu 函数创建的 PDU，或者应用程序使用对 SnmpGetPduData 的调用接收并读取的 PDU。

当应用程序使用 SnmpCreatePdu 创建 PDU 时，或者在应用程序使用 SnmpGetPduData 读取 PDU 后，Microsoft WinSNMP 实现要求应用程序“知道”PDU 字段的值。 如果应用程序使用 SnmpGetPduData 再次读取 PDU，则调用将生成指定 PDU 的变量绑定列表的副本。 这种类型的对 SnmpGetPduData 的调用也会复制 PDU 的句柄。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 winsnmp.h
Library Wsnmp32.lib
DLL Wsnmp32.dll

另请参阅

SnmpCreatePdu

SnmpDuplicateVbl

WinSNMP 函数

WinSNMP API 概述