SnmpExtensionTrap function (snmp.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 Microsoft SNMP service calls the SnmpExtensionTrap function to retrieve information the service needs to generate traps for the SNMP extension agent. The service calls this function only after the extension agent sets the trap event handle to the signaled state during a call to the SnmpExtensionInit function. The SnmpExtensionTrap function is an element of the SNMP Extension Agent API.

Syntax

BOOL SNMP_FUNC_TYPE SnmpExtensionTrap(
  [out] AsnObjectIdentifier *pEnterpriseOid,
  [out] AsnInteger32        *pGenericTrapId,
  [out] AsnInteger32        *pSpecificTrapId,
  [out] AsnTimeticks        *pTimeStamp,
  [out] SnmpVarBindList     *pVarBindList
);

Parameters

[out] pEnterpriseOid

Pointer to an AsnObjectIdentifier structure to receive the object identifier of the enterprise that generated the trap. The SNMP service does not free the memory for this variable.

[out] pGenericTrapId

Pointer to a variable to receive an indication of the generic trap. This parameter can be one of the following values.

[out] pSpecificTrapId

Pointer to a variable to receive an indication of the specific trap generated.

[out] pTimeStamp

Pointer to a variable to receive the time stamp. It is recommended that you initialize this parameter with the value returned by a call to the SnmpSvcGetUptime function.

[out] pVarBindList

Pointer to the variable bindings list. The extension agent must allocate the memory for this parameter. The SNMP service frees the memory with a call to the SnmpUtilVarBindListFree function.

Return value

If the SnmpExtensionTrap function returns a trap, the return value is TRUE. The SNMP service repeatedly calls the function until it returns a value of FALSE. For additional information, see the following Remarks section.

Remarks

The SNMP service repeatedly calls the SnmpExtensionTrap function when the phSubagentTrapEvent event handle is set to the signaled state. This handle is passed back during the call to the SnmpExtensionInit entry point function. The SnmpExtensionTrap function must return TRUE to indicate that the parameters contain valid data for a single trap. The function must return FALSE to indicate that the parameters do not represent valid trap data, and to stop the service's repeated calls.

Note that after the SNMP service sends a trap, it frees the memory associated with the variable binding list.

It is important to note that earlier documentation stated that the extension agent should dynamically allocate memory for the enterprise object identifier because the SNMP service would attempt to release the memory after sending a trap. The service will not release the memory associated with the enterprise object identifier. It is recommended that you return a pointer to a static AsnObjectIdentifier structure instead.

Requirements

See also

SNMP Functions

SetEvent

Simple Network Management Protocol (SNMP) Overview

SnmpExtensionInit

SnmpSvcGetUptime

SnmpUtilMemAlloc

SnmpUtilVarBindListFree

SnmpVarBindList