SnmpRecvMsg 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 WinSNMP SnmpRecvMsg function retrieves the results of a completed asynchronous request submitted by a call to the SnmpSendMsg function, in the form of an SNMP message. The SnmpRecvMsg function also returns outstanding trap data and notifications registered for a WinSNMP session.

Syntax

SNMPAPI_STATUS SNMPAPI_CALL SnmpRecvMsg(
  [in]  HSNMP_SESSION   session,
  [out] LPHSNMP_ENTITY  srcEntity,
  [out] LPHSNMP_ENTITY  dstEntity,
  [out] LPHSNMP_CONTEXT context,
  [out] LPHSNMP_PDU     PDU
);

Parameters

[in] session

Handle to the WinSNMP session.

[out] srcEntity

Pointer to a variable that receives a handle to the entity that sends the message. Note that the srcEntity parameter to the SnmpRegister function specifies a handle to the management entity that registers for trap notification.

[out] dstEntity

Pointer to a variable that receives a handle to the entity that receives the message. Note that the dstEntity parameter to the SnmpRegister function specifies a handle to the management entity that sends traps.

[out] context

Pointer to a variable that receives a handle to the context, which is a set of managed object resources. The entity specified by the srcEntity parameter issues the message from this context.

[out] PDU

Pointer to a variable that receives a handle to the protocol data unit (PDU) component of the message.

Return value

If the function succeeds, the return value is SNMPAPI_SUCCESS, and the output parameters contain the values indicated in the preceding parameter descriptions.

If the function fails, the return value is SNMPAPI_FAILURE. If the function fails with an extended error code that indicates a network transport layer error, that is, one that begins with SNMPAPI_TL_, the output parameters also contain the values indicated preceding to enable the WinSNMP application to recover gracefully.

To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Return code	Description
SNMPAPI_NOT_INITIALIZED	The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR	An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID	The session parameter is invalid.
SNMPAPI_NOOP	The specified session has no messages in its queue at this time.
SNMPAPI_TL_NOT_INITIALIZED	The network transport layer was not initialized.
SNMPAPI_TL_NOT_SUPPORTED	The network transport layer does not support the SNMP protocol.
SNMPAPI_TL_NOT_AVAILABLE	The network subsystem failed.
SNMPAPI_TL_RESOURCE_ERROR	A resource error occurred in the network transport layer.
SNMPAPI_TL_UNDELIVERABLE	The entity specified by the dstEntity parameter is unavailable.
SNMPAPI_TL_SRC_INVALID	The entity specified by the srcEntity parameter was not initialized.
SNMPAPI_TL_INVALID_PARAM	A network transport layer function call received an invalid input parameter.
SNMPAPI_TL_PDU_TOO_BIG	The PDU is too large for the network transport layer to send or receive.
SNMPAPI_TL_OTHER	An undefined network transport layer error occurred.
SNMPAPI_OTHER_ERROR	An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

The SnmpCreateSession function passes an application window handle and notification message identifier to the Microsoft WinSNMP implementation. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP application must call the SnmpRecvMsg function with the session handle returned by SnmpCreateSession to retrieve an incoming protocol data unit (PDU). For additional information, see About SNMP Messages.

The SnmpRecvMsg function instantiates four objects and allocates their resources: two entity handles, a context handle, and a PDU handle. The handle to the variable bindings list component of the returned PDU is not instantiated until the WinSNMP application calls the SnmpGetPduData function. When it no longer needs the resources SnmpRecvMsg returns, the WinSNMP application must free the individual resources using the WinSNMP function that corresponds to the resource. For additional information, see SnmpFreePdu, SnmpFreeEntity, and SnmpFreeContext.

When the implementation receives traps from an entity operating under the SNMP version 1 framework (SNMPv1), it translates the traps to the SNMP version 2C (SNMPv2C) format. Therefore, when SnmpRecvMsg delivers a trap it is always in the SNMPv2C format. For additional information, see Translating Traps from SNMPv1 to SNMPv2C and WinSNMP Programming Tasks.

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