SnmpCreateSession

[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
);

Parameters

hWnd
Handle to a window of the WinSNMP manager application to notify when an asynchronous request completes, or when trap notification occurs. This parameter is required for Windows notification messages for the session.
wMsg
Specifies an unsigned integer that identifies the notification message to send to the WinSNMP manager application window. This parameter is required for Windows notification messages for the session.
pfnCallBack
Specifies the address of an application-defined, session-specific SNMPAPI_CALLBACK function. The implementation will call this function to inform the WinSNMP session when notifications are available.

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.

lpClientData
Pointer to application-defined data to pass to the callback function specified by the pfnCallBack parameter. This parameter is optional and can be NULL. If the pfnCallBack parameter is NULL, the implementation ignores this parameter.

Return Values

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.

Remarks

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);

QuickInfo

  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.

See Also

WinSNMP Manager API Overview, WinSNMP Functions, SNMPAPI_CALLBACK, SnmpOpen, SnmpClose, SnmpCleanup, SnmpRecvMsg