SnmpListen function (winsnmp.h)

Article
02/22/2024

[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 WinSNMP SnmpListen function registers a WinSNMP application as an SNMP agent. An agent application calls this function to inform the Microsoft WinSNMP implementation that an entity will be acting in the role of an SNMP agent. An application also calls this function to inform the implementation when an entity will no longer be acting in this role. The SnmpListen function is an element of the WinSNMP API, version 2.0.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpListen(
  [in] HSNMP_ENTITY   hEntity,
  [in] SNMPAPI_STATUS lStatus
);

Parameters

[in] hEntity

Handle to the WinSNMP entity to notify when the Microsoft WinSNMP implementation receives an incoming SNMP request message (PDU). This parameter identifies the agent application. For more information, see the following Remarks and Return Values sections.

When you call the SnmpCreateSession function, you can specify whether the implementation should use a window notification message or an SNMPAPI_CALLBACK function to notify the application when an SNMP message or asynchronous event is available.

[in] lStatus

Specifies an unsigned long integer variable that indicates whether the WinSNMP entity identified by the hEntity parameter is acting in an SNMP agent role, or if it is no longer acting in this role. This parameter can be one of the following values.

Value	Meaning
SNMPAPI_ON	The specified WinSNMP entity is functioning in an agent role.
SNMPAPI_OFF	The specified WinSNMP entity is not functioning in an agent role.

Passing a value of SNMPAPI_OFF releases both the resources allocated to the entity and the port assigned it. For more information, see the following Remarks section.

Return value

If the function succeeds, the return value is SNMPAPI_SUCCESS.

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.

Return code	Description
SNMPAPI_NOT_INITIALIZED	The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR	An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID	The hEntity parameter is invalid. This parameter must be a handle returned by a previous call to the SnmpStrToEntity function.
SNMPAPI_MODE_INVALID	The lStatus parameter is invalid.
SNMPAPI_NOOP	The entity specified by the hEntity parameter is already functioning in the role of an SNMP agent.
SNMPAPI_TL_RESOURCE_ERROR	There is a network transport layer error. A socket could not be created for the entity specified by the hEntity parameter.
SNMPAPI_TL_OTHER	An error occurred in the network transport layer while trying to bind a socket for the entity specified by the hEntity parameter.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

Remarks

When you specify an entity, you explicitly specify the address family, interface address, and port for the entity. This is because WinSNMP assigns these attributes to each WinSNMP entity as a result of a call to the SnmpStrToEntity function. The implementation uses the address and port settings currently assigned to the entity specified by the hEntity parameter when it sends notifications to the agent application. For more information, see SnmpSetPort.

When you call the SnmpClose function for a WinSNMP session and the SnmpCleanup function for a WinSNMP application, you must release all ports associated with WinSNMP agent applications.

For more information about SNMP management applications and agent applications, see Registering an SNMP Agent Application and About SNMP.

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