Platform SDK: Network Management

SnmpCreateSession

The SnmpCreateSession function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP 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 window notification message or an SNMPAPI_CALLBACK function to notify the session.

The SnmpCreateSession function is an element of the WinSNMP API, version 2.0. When developing new WinSNMP applications, it is recommended that you call SnmpCreateSession to open a WinSNMP session instead of calling the SnmpOpen function.

HSNMP_SESSION SnmpCreateSession(
  HWND hWnd,                    // handle to the notification window
  UINT wMsg,                    // window notification message number
  SNMPAPI_CALLBACK fCallback,   // notification callback function
  LPVOID lpClientData           // pointer to callback function data
);

Parameters

hWnd: [in] Handle to a window of the WinSNMP application to notify when an asynchronous request completes, or when trap notification occurs. This parameter is required for window notification messages for the session.
wMsg: [in] Specifies an unsigned integer that identifies the notification message to send to the WinSNMP application window. This parameter is required for window notification messages for the session.
fCallback: [in] 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 window notification messages for the session. For additional information, see the following Remarks section.
lpClientData: [in] Pointer to application-defined data to pass to the callback function specified by the fCallback parameter. This parameter is optional and can be NULL. If the fCallback 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 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 fCallback parameter is NULL, but the hWnd parameter is not a valid window handle.
SNMPAPI_MSG_INVALID	The fCallback parameter is NULL, but the wMsg parameter is not a valid message value.
SNMPAPI_MODE_INVALID	The fCallback 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 window notification messages.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

The SnmpCreateSession function returns a unique handle to each open WinSNMP session within the calling WinSNMP 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 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 application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources.

Callback Notifications

If the fCallback 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 fCallback 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>);

Window 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 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 application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP 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 window notification messages.

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winsnmp.h.
  Library: Use Wsnmp32.lib.

SnmpCreateSession

Parameters

Return Values

Remarks

Requirements

See Also