snmpExtensionQueryEx 函数 (snmp.h)

项目
08/26/2023

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

Microsoft SNMP 服务调用 SnmpExtensionQueryEx 函数来处理 SNMP 请求，这些请求在 SNMP 扩展代理注册的一个或多个 MIB 子树中指定变量。此函数是 SNMP 扩展代理 API 的元素。

注意建议使用 SnmpExtensionQueryExex 函数，该函数支持 SNMP 版本 2C (SNMPv2C) 数据类型和多阶段 SNMP SET 操作。如果扩展代理导出 SnmpExtensionQueryEx 函数，SNMP 服务不会调用 SnmpExtensionQuery 函数。

语法

BOOL SNMP_FUNC_TYPE SnmpExtensionQueryEx(
  [in]      UINT            nRequestType,
  [in]      UINT            nTransactionId,
  [in, out] SnmpVarBindList *pVarBindList,
  [in, out] AsnOctetString  *pContextInfo,
  [out]     AsnInteger32    *pErrorStatus,
  [out]     AsnInteger32    *pErrorIndex
);

参数

[in] nRequestType

指定 SNMP 服务请求扩展代理执行的操作类型。此参数的取值可为下列值之一：

值	含义
SNMP_EXTENSION_GET	检索指定变量的值。
SNMP_EXTENSION_GET_NEXT	检索指定变量的字典后续版本的值。
SNMP_EXTENSION_SET_TEST	验证指定变量的值。此操作可最大程度地提高 COMMIT 请求期间成功写入的概率。
SNMP_EXTENSION_SET_COMMIT	将新值写入指定的变量。
SNMP_EXTENSION_SET_UNDO	在 COMMIT 请求之前，将指定变量的值重置为其值。
SNMP_EXTENSION_SET_CLEANUP	释放在以前的请求和操作中分配的资源。

有关 SET 请求类型（即以SNMP_EXTENSION_SET_开头的请求类型）的其他信息，请参阅以下“备注”部分。

[in] nTransactionId

指定作为传入 SNMP 请求 PDU 的唯一标识符的 DWORD 变量。扩展代理可以使用此值来关联涉及同一 PDU 的 SNMP 服务的多个调用。

[in, out] pVarBindList

指向包含相关变量的变量绑定列表的指针。

[in, out] pContextInfo

指向包含用户定义的上下文信息的八进制字符串的指针。

扩展代理可以使用此参数来存储在多阶段 SNMP SET 操作期间使用的上下文信息。扩展代理必须在 CLEANUP 请求期间释放与此参数关联的资源。 SNMP 服务不会释放与此参数关联的任何资源。有关其他信息，请参阅以下“备注”部分。

[out] pErrorStatus

指向用于接收错误状态结果的变量的指针。此参数可以是 SNMPv2C 定义的以下值之一。

错误代码	含义
SNMP_ERRORSTATUS_NOERROR	代理报告在传输过程中未发生任何错误。
SNMP_ERRORSTATUS_TOOBIG	代理无法将请求的 SNMP 操作的结果放入单个 SNMP 消息中。
SNMP_ERRORSTATUS_NOSUCHNAME	请求的 SNMP 操作标识了一个未知变量。
SNMP_ERRORSTATUS_BADVALUE	请求的 SNMP 操作尝试更改变量，但它指定了语法或值错误。
SNMP_ERRORSTATUS_READONLY	请求的 SNMP 操作尝试根据变量的社区配置文件更改不允许更改的变量。
SNMP_ERRORSTATUS_GENERR	在请求的 SNMP 操作期间，出现此处列出的错误以外的错误。
SNMP_ERRORSTATUS_NOACCESS	指定的 SNMP 变量不可访问。
SNMP_ERRORSTATUS_WRONGTYPE	值指定与变量所需的类型不一致的类型。
SNMP_ERRORSTATUS_WRONGLENGTH	值指定与变量所需长度不一致的长度。
SNMP_ERRORSTATUS_WRONGENCODING	值包含与字段的 ASN.1 标记不一致的抽象语法表示法一 (ASN.1) 编码。
SNMP_ERRORSTATUS_WRONGVALUE	值不能分配给变量。
SNMP_ERRORSTATUS_NOCREATION	变量不存在，代理无法创建它。
SNMP_ERRORSTATUS_INCONSISTENTVALUE	该值与其他托管对象的值不一致。
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	将值分配给变量需要分配当前不可用的资源。
SNMP_ERRORSTATUS_COMMITFAILED	未发生验证错误，但未更新任何变量。
SNMP_ERRORSTATUS_UNDOFAILED	未发生验证错误。某些变量已更新，因为无法撤消其赋值。
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	发生授权错误。
SNMP_ERRORSTATUS_NOTWRITABLE	变量存在，但代理无法修改它。
SNMP_ERRORSTATUS_INCONSISTENTNAME	变量不存在;代理无法创建它，因为命名对象实例与其他托管对象的值不一致。

[out] pErrorIndex

指向用于接收错误索引结果的变量的指针。

返回值

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

如果函数失败，则返回值为 FALSE。

注解

SNMP 服务多次调用 SnmpExtensionQueryEx 函数来处理传入的 SNMP SET 请求。该服务可以在 TEST 请求阶段、COMMIT 请求阶段、UNDO 请求阶段和 CLEANUP 请求阶段调用 SnmpExtensionQueryEx 。

TEST 请求

SNMP 服务通过首先调用具有 SNMP_EXTENSION_SET_TEST dwRequestType 的 SnmpExtensionQueryEx 函数来处理 SNMP SET 请求类型。服务调用负责请求中的变量绑定的每个扩展代理。每个扩展代理都必须验证变量绑定列表中的变量。他们可以选择将以下请求所需的任何上下文信息存储在 pContextInfo 参数指向的变量中。

如果 TEST 请求失败，服务将启动 CLEANUP 请求。该服务使用 SnmpExtensionQueryEx 函数再次调用以前向 TEST 请求返回 TRUE 的每个扩展代理。该服务使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 调用每个扩展代理。

COMMIT 请求

如果所有扩展代理都对 TEST 请求返回 TRUE，SNMP 服务将使用 SNMP_EXTENSION_SET_COMMIT dwRequestType 调用每个扩展代理，并使用 SnmpExtensionQueryEx 函数。服务返回扩展代理传递给服务的扩展代理上下文信息。这是扩展代理在测试请求期间在 pContextInfo 参数中传递的上下文信息。扩展代理可以使用上下文信息以特定于检测的方式更新指定变量的值。

如果扩展代理支持回滚处理，则此时它可以更新 pContextInfo 参数中的上下文信息。 SNMP 服务在 UNDO 请求期间将信息传递回扩展代理。

如果所有扩展代理都对 COMMIT 请求返回 TRUE，则服务将使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 使用 SnmpExtensionQueryEx 函数调用每个扩展代理。

如果任何扩展代理未能通过 COMMIT 请求，该服务也会启动 CLEANUP 请求。该服务使用 SnmpExtensionQueryEx 函数再次调用以前向 COMMIT 请求返回 TRUE 的每个扩展代理。该服务使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 调用每个扩展代理。

CLEANUP 请求

该服务会将在 TEST 或 COMMIT 请求期间在 pContextInfo 参数中传递的上下文信息返回给扩展代理。扩展代理此时必须释放与参数关联的资源。

UNDO 请求

如果任何扩展代理向 COMMIT 请求返回 FALSE，SNMP 服务将终止 COMMIT 请求。该服务调用每个向 COMMIT 请求返回 TRUE 且 dwRequestType 为 SNMP_EXTENSION_SET_UNDO 的扩展代理。这会向扩展代理发出 COMMIT 请求失败的信号，它们必须启动回滚处理。

扩展代理必须尝试将相关变量的值重置回 COMMIT 请求失败之前的值。为此，扩展代理使用在 COMMIT 请求期间 pContextInfo 参数中返回的上下文信息。

如果任何扩展代理向 UNDO 请求返回 FALSE ，则整个 SET 操作将失败并显示错误代码SNMP_ERRORSTATUS_UNDOFAILED。如果所有扩展代理都对 UNDO 请求返回 TRUE，SNMP SET 操作将失败，并显示失败 COMMIT 请求的扩展代理设置的错误代码。

在 UNDO 请求之后，服务始终使用 SNMP_EXTENSION_SET_CLEANUP dwRequestType 使用 SnmpExtensionQueryEx 函数调用每个扩展代理。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	snmp.h