SnmpOpen function (winsnmp.h)

Article
10/13/2021

[SNMP is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use Windows Remote Management, which is the Microsoft implementation of WS-Man.]

The SnmpOpen function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP application. This WinSNMP function enables the implementation to allocate and initialize memory, resources, data structures, and communications mechanisms. The SnmpOpen function returns a handle to the new WinSNMP session.

Note When developing new WinSNMP applications, it is recommended that you call the SnmpCreateSession function to open a WinSNMP session instead of calling the SnmpOpen function.

Syntax

HSNMP_SESSION SNMPAPI_CALL SnmpOpen(
  [in] HWND hWnd,
  [in] UINT wMsg
);

Parameters

[in] hWnd

Handle to a window of the WinSNMP application to notify when an asynchronous request completes, or when trap notification occurs.

[in] wMsg

Specifies an unsigned integer that identifies the notification message to send to the WinSNMP application window.

Return value

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 specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Return 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 hWnd parameter is not a valid window handle.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

The SnmpOpen function returns a unique handle to each open WinSNMP session within the calling WinSNMP application. The application must use the session handle that SnmpOpen returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation. When the implementation allocates resources to an individual session, it performs an orderly release of resources in response to a call to SnmpClose for the session.

The SnmpOpen function passes to the implementation the handle to an application window and a notification message identifier. If the wParam component of the notification message specified by the wMsg parameter is equal to zero, 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 SnmpOpen. If the wParam parameter of the notification message is not equal to zero, it represents a WinSNMP error code. The error code applies to the PDU identified by the request identifier in the lParam parameter of the notification message.

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.

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 SnmpOpen function. If a WinSNMP application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources. The implementation treats one SnmpCleanup call as if it were a series of SnmpClose calls, one call for each session the implementation opens as a result of a call to SnmpOpen.

For information about opening a WinSNMP session and specifying the method used to inform the session of available SNMP messages and asynchronous events, see SnmpCreateSession. When you call SnmpCreateSession you can specify a window notification message or an SNMPAPI_CALLBACK function to notify the session.

For more information, see WinSNMP Sessions.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winsnmp.h
Library	Wsnmp32.lib
DLL	Wsnmp32.dll