SNMP DPI: Generating a TRAP

Issue a trap any time after a DPI OPEN was successful. To do so, you must create a trap packet and send it to the agent. With the TRAP, you can pass different kinds of varBinds, if you want. In this example, three varBinds are passed; one with integer data, one with an octet string, and one with a counter. You can also pass an Enterprise ID, but with DPI 2.0, the agent will use your subagent ID as the enterprise ID if you do not pass one with the trap. In most cases, that will probably not cause problems.

You must first prepare a varBind list chain that contains the three variables that you want to pass along with the trap. To do so, prepare a chain of three snmp_dpi_set_packet structures, which looks like:

struct dpi_set_packet {
  char                   *object_p;   /* ptr to OIDstring     */
  char                   *group_p;    /* ptr to sub-tree      */
  char                   *instance_p; /* ptr to rest of OID   */
  unsigned char           value_type; /* SNMP_TYPE_xxxx       */
  unsigned short          value_len;  /* value length         */
  char                   *value_p;    /* ptr to value itself  */
  struct dpi_set_packet  *next_p;     /* ptr to next in chain */
};
typedef struct dpi_set_packet        snmp_dpi_set_packet;
#define snmp_dpi_set_packet_NULL_p   ((snmp_dpi_set_packet *)0)

You can use the mkDPIset() function to prepare such a structure. This function expects the following parameters:

A pointer to an existing snmp_dpi_set_packet structure if the new varBind must be added to an existing chain of varBinds. If this is the first or the only varBind in the chain, pass the snmp_dpi_set_packet_NULL_p pointer to indicate this.
A pointer to the desired subtree.
A pointer to the rest of the OID, in other words, the piece that follows the subtree.
The value type of the value to be bound to the variable name. This must be one of the SNMP_TYPE_xxxx values as defined in the snmp_dpi.h include file.
The length of the value. For integer type values, this must be a length of 4. Always work with 32-bit signed or unsigned integers except for the Counter64 type. For the Counter64 type, point to an snmp_dpi_u64 structure and pass the length of that structure.
A pointer to the value.

Memory for the varBind is dynamically allocated and the data itself is copied. Upon return, you can dispose of your own pointers and allocated memory as you please. If the call is successful, a pointer is returned as follows:

To a new snmp_dpi_set_packet if it is the first or only varBind.
To the existing snmp_dpi_set_packet that you passed on the call. In this case, the new packet has been chained to the end of the varBind list.

If the mkDPIset() call fails, a NULL pointer is returned.

When you have prepared the SET-varBind data, create a DPI TRAP packet. To do so, use the mkDPItrap() function, which expects these parameters:

The generic trap code. Use 6 for enterprise specific trap type.
The specific trap type. This is a type that is defined by the MIB that you are implementing. In our example you just use a 1.
A pointer to a chain of varBinds or the NULL pointer if no varBinds need to be passed with the trap.
A pointer to the enterprise OID if you want to use a different enterprise ID than the OID you used to identify yourself as a subagent at DPI-OPEN time.

The following code creates an enterprise-specific trap with specific type 1 and passes 3 varBinds. The first varBind with object 1, instance 0, Integer32 value; the second varBind with object 2, instance 0, Octet String; the third with Counter32. You pass no enterprise ID.

static int do_trap(void)
{
       unsigned char       *packet_p;
       int                  rc;
       snmp_dpi_set_packet *varBind_p, *set_p;
 
       varBind_p =                        /* init the varBind chain  */
          snmp_dpi_set_packet_NULL_p;     /* to a NULL pointer       */
 
       varBind_p = mkDPIset(              /* Make DPI set packet     */
                     varBind_p,           /* ptr to varBind chain    */
                     DPI_SIMPLE_MIB,      /* ptr to subtree          */
                     DPI_SIMPLE_INTEGER,  /* ptr to rest of OID      */
                     SNMP_TYPE_Integer32, /* value type Integer 32   */
                     sizeof(value1),      /* length of value         */
                     value1);            /* ptr to value            */
 
       if (!varBind_p) return(-1);        /* If it failed, return    */
 
       set_p     = mkDPIset(                 /* Make DPI set packet  */
                     varBind_p,              /* ptr to varBind chain */
                     DPI_SIMPLE_MIB,         /* ptr to subtree       */
                     DPI_SIMPLE_STRING,      /* ptr to rest of OID   */
                     SNMP_TYPE_DisplayString,/* value type           */
                     value2_len,             /* length of value      */
                     value2_p);              /* ptr to value         */
 
       if (!set_p) {                      /* if we failed...  then   */
          fDPIset(varBind_p);             /* free earlier varBinds   */
          return(-1);                     /* If it failed, return    */
       }
 
       set_p     = mkDPIset(                 /* Make DPI set packet  */
                     varBind_p,              /* ptr to varBind chain */
                     DPI_SIMPLE_MIB,         /* ptr to subtree       */
                     DPI_SIMPLE_COUNTER32,   /* ptr to rest of OID   */
                     SNMP_TYPE_Counter32,    /* value type           */
                     sizeof(value3),         /* length of value      */
                     value3);               /* ptr to value         */
 
       if (!set_p) {                      /* if we failed...  then   */
          fDPIset(varBind_p);             /* free earlier varBinds   */
          return(-1);                     /* If it failed, return    */
       }
 
#ifndef EXCLUDE_SNMP_SMIv2_SUPPORT
                                             /*                *Apr23*/
       set_p     = mkDPIset(                 /* Make DPI set packet  */
                     varBind_p,              /* ptr to varBind chain */
                     DPI_SIMPLE_MIB,         /* ptr to subtree       */
                     DPI_SIMPLE_COUNTER64,   /* ptr to rest of OID   */
                     SNMP_TYPE_Counter64,    /* value type           */
                     sizeof(value4),         /* length of value      */
                     value4);               /* ptr to value         */
 
       if (!set_p) {                      /* if we failed...  then   */
          fDPIset(varBind_p);             /* free earlier varBinds   */
          return(-1);                     /* If it failed, return    */
       }
 
#endif /* ndef EXCLUDE_SNMP_SMIv2_SUPPORT */
 
       packet_p = mkDPItrap(              /* Make DPItrap packet     */
                    6,                    /* enterpriseSpecific      */
                    1,                    /* specific type = 1       */
                    varBind_p,            /* varBind data, and use   */
                    (char *)0);           /* default enterpriseID    */
 
       if (!packet_p) return(-1);         /* If it failed, return    */
 
       rc  = DPIsend_packet_to_agent(     /* send TRAP packet        */
                handle,                   /* on this connection      */
                packet_p,                 /* this is the packet      */
                DPI_PACKET_LEN(packet_p));/* and this is its length  */
 
       return(rc);                        /* return retcode          */
} /* end of do_trap() */