snmpRegister 函数 (winsnmp.h)

项目
03/13/2024

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

WinSNMP SnmpRegister 函数注册或取消注册 WinSNMP 应用程序以用于陷阱和通知接收。应用程序可以注册和接收陷阱和通知，或者取消注册和禁用陷阱和通知。

WinSNMP 应用程序可以注册或取消注册一种类型的陷阱或通知，或者针对所有陷阱和通知，具体取决于通知参数的值。

语法

SNMPAPI_STATUS SNMPAPI_CALL SnmpRegister(
  [in] HSNMP_SESSION session,
  [in] HSNMP_ENTITY  srcEntity,
  [in] HSNMP_ENTITY  dstEntity,
  [in] HSNMP_CONTEXT context,
  [in] smiLPCOID     notification,
  [in] smiUINT32     state
);

参数

[in] session

正在注册或取消注册陷阱和通知的 WinSNMP 会话的句柄。

[in] srcEntity

管理实体的句柄，该实体是注册请求的源。此实体充当 SNMP 管理员角色，将收到陷阱或通知。

由于实现不使用此参数来筛选到达 WinSNMP 应用程序的陷阱和通知，因此 WinSNMP 管理器应用程序通常会在此参数中传递 NULL 。

如果此参数为 NULL，则 Microsoft WinSNMP 实现将注册或取消注册陷阱和通知请求的所有源。

请注意，SnmpRecvMsg 函数的 srcEntity 参数具有不同的角色。在该函数中， srcEntity 接收发送陷阱的实体的句柄。

[in] dstEntity

注册请求接收方管理实体的句柄。此实体充当 SNMP 代理角色，将发送陷阱或通知。

如果此参数为 NULL，则实现将注册或取消注册 WinSNMP 应用程序以获取来自所有管理实体的陷阱和通知。

请注意，SnmpRecvMsg 函数的 dstEntity 参数接收注册陷阱通知的管理实体的句柄。

[in] context

上下文的句柄，上下文是一组托管对象资源。

如果此参数为 NULL，则实现将为每个上下文注册或取消注册 WinSNMP 应用程序的陷阱和通知。

[in] notification

指向 smiOID 结构的指针，该结构包含一种类型的陷阱或通知的模式匹配序列。实现使用此序列来标识 WinSNMP 应用程序正在为其注册或注销的陷阱或通知的类型。有关其他信息，请参阅以下“备注”部分。

如果此参数为 NULL，则实现将注册或取消注册来自 dstEntity 参数指定的管理实体或实体的所有陷阱和通知的 WinSNMP 应用程序。

[in] state

指定一个无符号长整数变量，该变量指示 WinSNMP 应用程序是注册以接收陷阱和通知，还是正在注销。此参数应等于以下值之一，但如果它包含不同的值，则实现将注册应用程序。

值	含义
SNMPAPI_OFF	禁用陷阱和通知。
SNMPAPI_ON	注册以接收陷阱和通知。

返回值

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

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

返回代码	说明
SNMPAPI_NOT_INITIALIZED	SnmpStartup 函数未成功完成。
SNMPAPI_ALLOC_ERROR	内存分配期间出错。
SNMPAPI_SESSION_INVALID	会话参数无效。
SNMPAPI_ENTITY_INVALID	一个或两个实体参数无效。
SNMPAPI_CONTEXT_INVALID	上下文参数无效。
SNMPAPI_OID_INVALID	通知参数无效。
SNMPAPI_TL_NOT_INITIALIZED	网络传输层未初始化，或者无法启动 SNMPTRAP.EXE 服务。
SNMPAPI_TL_IN_USE	陷阱端口不可用。
SNMPAPI_TL_NOT_AVAILABLE	网络子系统失败。
SNMPAPI_OTHER_ERROR	发生未知或未定义的错误。

有关详细信息，请参阅网络传输错误。

注解

通常，WinSNMP 管理器应用程序（而不是代理应用程序）调用 SnmpRegister 函数。

请务必注意，对于不是管理员的用户，仅当 SNMP 陷阱服务已启动时， SnmpRegister 函数才会在 Windows 2000 和 Windows XP 上成功。

如果 WinSNMP 应用程序在调用 srcEntity、dstEntity、context 或 notification 参数中的 SnmpRegister 函数时传递 NULL，则实现不会使用该参数来筛选到达 WinSNMP 应用程序的陷阱和通知。如果应用程序在前面提到的所有参数中传递 NULL ，则实现会将所有收到的通知传递到会话。

如果 WinSNMP 应用程序注册接收特定类型的陷阱或通知，则必须定义对应于该类型的陷阱的对象标识符，即 smiOID 结构。通知参数必须指向此结构。 RFC 1907“简单网络管理协议版本 2 的管理信息库 (SNMPv2) ”定义了陷阱和通知对象标识符。有关详细信息，请参阅管理陷阱和通知和将陷阱从 SNMPv1 转换为 SNMPv2C。

实现使用通知参数的值作为模式来匹配收到的陷阱和通知。例如，如果 WinSNMP 应用程序在通知参数中传递 n 个子标识符，并且接收的陷阱中的前 n 个子标识符匹配所有传递的子标识符，则陷阱对象标识符为匹配项。如果收到的陷阱的子标识符少于 n，则对象标识符不匹配。如果存在匹配项，则实现会将陷阱或通知发送到 WinSNMP 应用程序。

如果任何或所有 dstEntity、 srcEntity 或 上下文 参数均为 NULL，则实现可能需要在后续调用 SnmpRecvMsg 函数时为该函数的相应参数分配资源。当 WinSNMP 应用程序不再需要 SnmpRecvMsg 返回的资源时，应用程序必须使用与资源对应的函数释放单个资源。有关详细信息，请参阅 SnmpFreeEntity 和 SnmpFreeContext。

有关详细信息，请参阅多个陷阱注册。

要求

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