SnmpListen

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.

SNMPAPI_STATUS SnmpListen(
  HSNMP_ENTITY hEntity,   // handle to the entity 
                          //   that will receive notifications
  SNMPAPI_STATUS lStatus  // flag to indicate agent role
);

Parameters

hEntity

[in] 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.

lStatus

[in] 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 Values

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.

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

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

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpRecvMsg, SnmpSendMsg, SnmpSetPort, SnmpStrToEntity, SnmpClose, SnmpCleanup