[This is preliminary documentation and subject to change.]
The SnmpCreateSession function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP manager application. The application can specify how the implementation should inform the WinSNMP session of available SNMP messages and asynchronous events. The application can specify a Windows notification message or an SNMPAPI_CALLBACK function to notify the session.
Note The SnmpCreateSession function is an element of the WinSNMP Manager API, version 2.0, which has not been finalized. The Microsoft WinSNMP implementation supports this function because it provides an alternative to the SnmpOpen function for manager applications that are not Windows-based.
HSNMP_SESSION SnmpCreateSession(
HWND hWnd, // handle to the notification window
UINT wMsg, // window notification message number
SNMPAPI_CALLBACK pfnCallBack, // notification callback function
LPVOID lpClientData // pointer to callback function data
);
This parameter is required to specify callback notifications for the session. This parameter must be NULL to specify Windows notification messages for the session. For additional information, see the following Remarks section.
If the function succeeds, the return value is a handle that identifies the WinSNMP session that the implementation opens for the calling manager application.
If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.
Error Code | Description |
---|---|
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully. |
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation. |
SNMPAPI_HWND_INVALID | The pfnCallBack parameter is NULL, but the hWnd parameter is not a valid window handle. |
SNMPAPI_MSG_INVALID | The pfnCallBack parameter is NULL, but the wMsg parameter is not a valid message value. |
SNMPAPI_MODE_INVALID | The pfnCallBack parameter is NULL and the hWnd and wMsg parameters are valid individually. However, the values are mutually incompatible on the Windows platform. |
SNMPAPI_OPERATION_INVALID | The combination of parameter values does not specify callback notifications or Windows notification messages. |
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred. |
If the WinSNMP manager application calls the SnmpCreateSession function with a NULL pfnCallBack parameter, SnmpCreateSession provides the same functionality as the SnmpOpen function.
The SnmpCreateSession function returns a unique handle to each open WinSNMP session within the calling WinSNMP manager application. The application must use the session handle that SnmpCreateSession returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation.
It is recommended that a WinSNMP manager application call the SnmpClose function once for each session that the implementation opens as a result of a call to the SnmpCreateSession function. If a WinSNMP manager application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources.
Callback Notifications
If the pfnCallBack parameter is not NULL on a successful call to the SnmpCreateSession function, the implementation alerts the session to notifications using the callback function specified by the pfnCallBack parameter.
Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using callback notifications.
hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);
Windows Notification Messages
The SnmpCreateSession function passes to the implementation the handle to an application window and a notification message identifier. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP manager application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpCreateSession.
One WinSNMP manager application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP manager application specify a unique wMsg parameter for each session.
Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using Windows notification messages.
hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);
Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.
WinSNMP Manager API Overview, WinSNMP Functions, SNMPAPI_CALLBACK, SnmpOpen, SnmpClose, SnmpCleanup, SnmpRecvMsg