The mkDPIregister() Function

Syntax

#include <snmp_dpi.h>

unsigned char  *mkDPIregister(  /* Make a DPI register packet */
  unsigned short   timeout,     /* in seconds (16-bit)        */
  long int         priority,    /* requested priority         */
  char            *group_p,     /* ptr to group ID (sub-tree) */
  char             bulk_select);/* Bulk selection (GETBULK)   */
  #define DPI_BULK_NO   0       /*  map GETBULK into GETNEXTs */
  #define DPI_BULK_YES  1       /*  pass GETBULK to subagent */

Parameters

timeout

The requested timeout in seconds. An agent often has a limit for this value and it will use that limit if this value is larger. The value zero has special meaning in the sense that it tells the agent to use the timeout value that was specified in the DPI OPEN packet.
priority
The requested priority. This field may contain any of these values:
• Requests the best available priority.

• Requests a better priority than the highest priority currently registered. Use this value to obtain the SNMP DPI Version 1 behavior.

  nnn

  Any positive value. You will receive that priority if available, otherwise the next best priority that is available.
  group_p
  A pointer to a NULL terminated character string that represents the sub-tree to be registered. This group ID must have a trailing dot.
  bulk_select
  Specifies if you want the agent to pass GETBULK on to the subagent or to map them into multiple GETNEXT requests. The choices are:

  DPI_BULK_NO

  Do not pass any GETBULK requests, but instead map a GETBULK request into multiple GETNEXT requests.
  DPI_BULK_YES
  Do pass a GETBULK request to the subagent.

  Return Values

  If successful, a pointer to a static DPI packet buffer is returned. The first two bytes of the buffer in network byte order contain the length of the remaining packet. The macro DPI_PACKET_LEN can be used to calculate the total length of the DPI packet.

  If failure, a NULL pointer is returned.

  Note: The static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a serialized DPI packet.

  Description

  The mkDPIregister() function creates a serialized DPI REGISTER packet that can then be sent to the DPI peer which is a DPI capable SNMP agent.

  The bulk_select can be used to ask the agent to map an SNMP GETBULK request into multiple GETNEXT requests. This makes it easier for the DPI subagent programmer because GETBULK processing doesn't need implementing.

  However, if one expects that a single GETBULK might improve the performance a lot, one can tell the agent to pass such requests. This might be the case if one expects a GETBULK to arrive often for a table for which one needs to do a kernel dive. Using GETBULK, one might be able to do just one dive instead of many. Although one could anticipate the dive with a GETNEXT also, and therefore obtain and cache the table upon the first GETNEXT request.

  According to the DPI 2.0 RFC, not all agents need to support DPI_BULK_YES. These agents will return an appropriate error code in the DPI RESPONSE though if such is the case.

  Normally the SNMP agent sends a DPI RESPONSE packet back. This packet identifies if the register was successful or not.

  Examples

    #include <snmp_dpi.h>  unsigned char *pack_p;
  
    pack_p = mkDPIregister(0,0L,"1.3.6.1.2.3.4.5."
                           DPI_BULK_NO);
    if (pack_p) {
       /* send packet to agent and await response */
    } /* endif */
  

  Related Information

  The snmp_dpi_resp_packet Structure

  ---

  [Back: The mkDPIopen() Function]
  [Next: The mkDPIresponse() Function]