UID

title

description

helpviewer_keywords

old-location

tech.root

ms.assetid

ms.date

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

req.redist

ms.custom

f1_keywords

dev_langs

topic_type

api_type

api_location

api_name

NF:winsnmp.SnmpListen

SnmpListen function (winsnmp.h)

The WinSNMP SnmpListen function registers a WinSNMP application as an SNMP agent.

SNMPAPI_OFF

SNMPAPI_ON

SnmpListen

SnmpListen function [SNMP]

_snmp_snmplisten

snmp.snmplisten

winsnmp/SnmpListen

snmp\snmplisten.htm

SNMP

e89c9315-efe4-4241-a7c4-f4475b107701

12/05/2018

SNMPAPI_OFF, SNMPAPI_ON, SnmpListen, SnmpListen function [SNMP], _snmp_snmplisten, snmp.snmplisten, winsnmp/SnmpListen

winsnmp.h

Windows

Windows 2000 Professional [desktop apps only]

Windows 2000 Server [desktop apps only]

Wsnmp32.lib

Wsnmp32.dll

Windows

19H1

SnmpListen

winsnmp/SnmpListen

c++

APIRef

kbSyntax

DllExport

Wsnmp32.dll

SnmpListen

SnmpListen function

-description

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

-parameters

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

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

-returns

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.