SnmpListen function (winsnmp.h)

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

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.

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

See also

SnmpCleanup

SnmpClose

SnmpRecvMsg

SnmpSendMsg

SnmpSetPort

SnmpStrToEntity

WinSNMP Functions

WinSNMP API Overview