SnmpCreateSession 函数 (winsnmp.h)

项目
08/27/2023

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

SnmpCreateSession 函数请求 Microsoft WinSNMP 实现打开 WinSNMP 应用程序的会话。应用程序可以指定实现应如何向 WinSNMP 会话通知可用的 SNMP 消息和异步事件。应用程序可以指定窗口通知消息或 SNMPAPI_CALLBACK 函数来通知会话。

SnmpCreateSession 函数是 WinSNMP API 版本 2.0 的元素。开发新的 WinSNMP 应用程序时，建议调用 SnmpCreateSession 以打开 WinSNMP 会话，而不是调用 SnmpOpen 函数。

语法

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

参数

[in] hWnd

WinSNMP 应用程序窗口的句柄，用于在异步请求完成或发生陷阱通知时发出通知。此参数是会话的窗口通知消息所必需的。

[in] wMsg

指定一个无符号整数，用于标识要发送到 WinSNMP 应用程序窗口的通知消息。此参数是会话的窗口通知消息所必需的。

[in] fCallBack

指定应用程序定义的特定于会话的SNMPAPI_CALLBACK函数的地址。实现将调用此函数，以在通知可用时通知 WinSNMP 会话。

此参数是指定会话的回调通知所必需的。此参数必须为 NULL 才能指定会话的窗口通知消息。有关其他信息，请参阅以下“备注”部分。

[in] lpClientData

指向要传递给 fCallback 参数指定的回调函数的应用程序定义数据的指针。此参数是可选的，可以为 NULL。如果 fCallback 参数为 NULL，则实现将忽略此参数。

返回值

如果函数成功，则返回值是标识实现为调用应用程序打开的 WinSNMP 会话的句柄。

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

返回代码	说明
SNMPAPI_NOT_INITIALIZED	SnmpStartup 函数未成功完成。
SNMPAPI_ALLOC_ERROR	内存分配期间出错。
SNMPAPI_HWND_INVALID	fCallback 参数为 NULL，但 hWnd 参数不是有效的窗口句柄。
SNMPAPI_MESSAGE_INVALID	fCallback 参数为 NULL，但 wMsg 参数不是有效的消息值。
SNMPAPI_MODE_INVALID	fCallback 参数为 NULL，hWnd 和 wMsg 参数单独有效。但是，这些值在 Windows 平台上互不兼容。
SNMPAPI_OPERATION_INVALID	参数值的组合不会指定回调通知或窗口通知消息。
SNMPAPI_OTHER_ERROR	发生未知或未定义的错误。

注解

SnmpCreateSession 函数返回调用 WinSNMP 应用程序中每个打开的 WinSNMP 会话的唯一句柄。应用程序必须使用 SnmpCreateSession 在其他 WinSNMP 函数调用中返回的会话句柄，以便于实现分配和解除分配资源。

建议 WinSNMP 应用程序对由于调用 SnmpCreateSession 函数而打开的每个会话调用 SnmpClose 函数一次。如果 WinSNMP 应用程序意外终止，则必须在终止之前调用 SnmpCleanup ，以使实现能够解除分配所有资源。

回调通知

如果成功调用 SnmpCreateSession 函数时 fCallback 参数不为 NULL，则实现将使用 fCallback 参数指定的回调函数向会话发出通知。

下面是调用 SnmpCreateSession 函数的示例，该函数请求实现使用回调通知向会话发出有关消息和事件的信号。

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

窗口通知消息

SnmpCreateSession 函数将句柄传递给实现应用程序窗口和通知消息标识符。当应用程序窗口收到 由 wMsg 参数指定的通知消息时，WinSNMP 应用程序必须检索传入协议数据单元 (PDU) 。应用程序通过使用 SnmpCreateSession 返回的会话句柄调用 SnmpRecvMsg 函数来执行此操作。

一个 WinSNMP 应用程序可以打开多个 WinSNMP 会话。如果应用程序使用相同的窗口句柄打开多个会话，建议 WinSNMP 应用程序为每个会话指定唯一 的 wMsg 参数。

下面是调用 SnmpCreateSession 函数的示例，该函数请求实现使用窗口通知消息向会话发出有关消息和事件的信号。

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

要求

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