SnmpExtensionInit

The Microsoft SNMP service calls the SnmpExtensionInit function to initialize the SNMP extension agent DLL. This function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionInit(
  DWORD dwUptimeReference,                    // see NOTE below
  HANDLE *phSubagentTrapEvent,                // trap event handle
  AsnObjectIdentifier *pFirstSupportedRegion  // first MIB subtree
);
 

Parameters

dwUptimeReference

[in] Specifies a time-zero reference for the extension agent.

Note  Extension agents should ignore this parameter. The SNMP extension agent DLL should use the SnmpSvcGetUptime function to retrieve the number of centiseconds the SNMP service has been running. For more information, see the following Remarks section.

phSubagentTrapEvent

[out] Pointer to an event handle the extension agent passes back to the SNMP service. This handle is used to notify the service that the extension agent has one or more traps to send. For additional information about allocating and deallocating the event handle, see the following Remarks section.

pFirstSupportedRegion

[out] Pointer to an AsnObjectIdentifier structure to receive the first MIB subtree that the extension agent supports. For additional information about allocating and deallocating resources for this structure, see the following Remarks section.

The extension agent can register additional MIB subtrees by implementing the SnmpExtensionInitEx entry point function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Extension agents should ignore the dwUptimeReference parameter. Instead, they should call the SnmpSvcGetUptime function to retrieve the number of centiseconds that the Microsoft SNMP service has been running. Because the dwUptimeReference parameter stores the elapsed time as a DWORD value in milliseconds, the time can wrap to zero and reflect an inaccurate time interval.

The extension agent notifies the SNMP service that it needs to send one or more traps by setting the event handle passed back in the phSubagentTrapEvent parameter to the signaled state. After this event has been signaled, the SNMP service repeatedly calls the extension agent's SnmpExtensionTrap entry point until the function returns a value of FALSE. This indicates that the extension agent has no more traps to send. If the extension agent does not generate traps, the phSubagentTrapEvent parameter should return a value of NULL.

The SNMP extension agent must allocate and deallocate resources for the trap event handle. When the SNMP service calls the SnmpExtensionInit function, the extension agent must call the CreateEvent function to allocate the event handle. The extension agent passes the handle to the SNMP service in the phSubagentTrapEvent parameter. When the SNMP service calls the SnmpExtensionClose function, the extension agent must deallocate resources for the trap event handle.

The SNMP service makes a copy of the AsnObjectIdentifier structure the extension agent returns in the pFirstSupportedRegion parameter. The extension agent must allocate and deallocate the resources associated with the original structure. It can do this when the SNMP service calls the SnmpExtensionClose function.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in snmp.h.
  Import Library: User-defined.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnObjectIdentifier, CreateEvent, SnmpExtensionTrap, SnmpSvcGetUptime, SnmpExtensionClose