SnmpRecvMsg

[This is preliminary documentation and subject to change.]

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.

SNMPAPI_STATUS SnmpRecvMsg(
  HSNMP_SESSION session,      // handle to the WinSNMP session 
  LPHSNMP_ENTITY srcEntity,   // handle to the source entity 
  LPHSNMP_ENTITY dstEntity,   // handle to the target entity 
  LPHSNMP_CONTEXT context,    // handle to the context 
  LPHSNMP_PDU PDU             // handle to the PDU 
);

Parameters

session: Handle to the WinSNMP session.
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 requests traps.
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.
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.
PDU: Pointer to a variable that receives a handle to the protocol data unit (PDU) component of the message.

Return Values

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

Error 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 SnmpOpen 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 manager application must call the SnmpRecvMsg function with the session handle returned by SnmpOpen 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 manager application calls the SnmpGetPduData function. When it no longer needs the resources SnmpRecvMsg returns, the WinSNMP manager 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.

QuickInfo

  Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winsnmp.h.
  Import Library: Use wsnmp32.lib.

SnmpRecvMsg

Parameters

Return Values

Remarks

QuickInfo

See Also