HOWTO: Programmatically Trigger a SNMP Trap

ID: Q189131

The information in this article applies to:

• Microsoft Win32 Software Development Kit (SDK) on the following platforms:

      - Microsoft Windows, versions 95, 98
      - Microsoft Windows NT, versions 3.51, 4.0
  

SUMMARY

A monitoring device (extension agent) uses a Simple Network Management Protocol (SNMP) trap to notify management station of some important event that has occurred.

During the start up of the SNMP service (extendible agent), it invokes the SnmpExtensionInit entry point of all the registered extension agents. Within the SnmpExtensionInit entry point, the extension agent will create a Win32 event object and pass this event back to the extendible agent. When the extension agent wants to send a trap, it will signal this event. Then, the extendible agent is able to invoke the SnmpExtensionTrap entry point implemented by the extension agent that has just signaled the event and sends the SNMP trap to configured destinations via the extendible agent. This technique is demonstrated by the Testdll.dll SNMP extension agent sample located in \Mssdk\Samples\Netds\Snmp\Testdll of the Platform SDK.

In some situations, the monitoring agent might be another process running in a different context other than the SNMP service. To allow this process to signal a trap event, the corresponding extension agent needs to create a named event with null DACL. Then, this monitoring process is able to trigger a SNMP trap by opening the named event and signaling it with Win32 OpenEvent and SetEvent APIs respectively.

MORE INFORMATION

To allow another process trigger a trap event, follow these steps:

1. Modify Testdll.dll SNMP extension agent sample located in

   \Mssdk\Samples\Netds\Snmp\Testdll of the Platform SDK by
   replacing SnmpExtensionInit() entry point in file Testdll.c with
   the following code:

      BOOL WINAPI SnmpExtensionInit(
          IN  DWORD               dwTimeZeroReference,
          OUT HANDLE              *hPollForTrapEvent,
          OUT AsnObjectIdentifier *supportedView)
      {
          SECURITY_ATTRIBUTES sa;
          SECURITY_DESCRIPTOR sd;

          sa.nLength = sizeof(SECURITY_ATTRIBUTES);
          sa.bInheritHandle = TRUE;
          sa.lpSecurityDescriptor = &sd;

          if(!InitializeSecurityDescriptor(&sd,
                                           SECURITY_DESCRIPTOR_REVISION))
              return FALSE;   // Handle errors.

          // Add a NULL DACL to the security descriptor.
          if(!SetSecurityDescriptorDacl(&sd, TRUE, (PACL)NULL, FALSE))
              return FALSE;   // Handle errors.

          // Record the time reference provided by the Extendible Agent.

          dwTimeZero = dwTimeZeroReference;

          // Create a named Event that will be used to communicate the
          // occurrence of traps to the Extendible Agent. The Extension
          // Agent will assert this Event when a trap has occurred. This
          // is explained later.

          // A named event is created with a null DACL such that other
          // processes are able to signal this Event as this Extension
          // agent does.

        if ((*hPollForTrapEvent =
             CreateEvent(&sa, FALSE, FALSE, TEXT("_MyTrapEvent"))) == NULL)
          {
              // Indicate error?, be sure that NULL is returned to
              // Extendible Agent.
          }

          // Indicate the MIB view supported by this Extension Agent, an
          // object identifier representing the sub root of the MIB that
          // is supported.

          *supportedView = MIB_OidPrefix; // NOTE!  structure copy

          // Record the trap Event. This example Extension Agent
          // simulates traps by generating a trap after every given number
          // of processed requests.

          hSimulateTrap = *hPollForTrapEvent;

          // Indicate that Extension Agent initialization was successful.

          return TRUE;

      } // end SnmpExtensionInit().

   event:

      #include <windows.h>
      #include <stdio.h>

      void main(void)
      {
          HANDLE hTrapEvent;
          char c;

          hTrapEvent = OpenEvent(EVENT_MODIFY_STATE, FALSE,
                                 TEXT("_MyTrapEvent"));
          if (hTrapEvent == NULL)
          {
              printf(TEXT("Can't open the event _MyTrapEvent\n"));
              return;
          }
          printf(TEXT("Hit t [enter] to trigger the sending of trap: \n"));
          while (1)
          {
              scanf("%c", &c);
              if (c == 't' || c == 'T')
                  SetEvent(hTrapEvent);
          }
      }

REFERENCES

For additional information, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q106387
   TITLE     : HOWTO: Share Objects with a Service

   ARTICLE-ID: Q128729
   TITLE     : HOWTO: Add an SNMP Extension Agent to the NT Registry

Additional query words: SNMP trap event

Keywords          : kbnetwork kbAPI kbNTOS350 kbNTOS351 kbNTOS400 kbSDKPlatform kbSNMP kbWinOS95 kbWinOS98 kbGrpNet 
Issue type        : kbhowto

Last Reviewed: July 31, 1998