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

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

See also

SnmpFreeContext

SnmpFreeEntity

SnmpFreePdu

SnmpGetPduData

SnmpRegister

SnmpSendMsg

WinSNMP Functions

WinSNMP API Overview