The mkDPIopen() Function

Syntax

#include <snmp_dpi.h>

unsigned char *mkDPIopen(       /* Make a DPI open packet     */
  char          *oid_p,         /* subagent Identifier (OID) */
  char          *description_p, /* subagent descriptive name */
  unsigned long  timeout,       /* requested default timeout  */
  unsigned long  max_varBinds,  /* max varBinds per DPI ndle  */
  char           character_set, /* selected character set     */
  #define DPI_NATIVE_CSET  0    /*   0 = native character set */
  #define DPI_ASCII_CSET   1    /*   1 = ASCII  character set */

  unsigned long  password_len,  /* length of password (if any)*/
  unsigned char *password_p);   /* ptr to password (if any)   */

Parameters

oid_p

A pointer to a NULL terminated character string representing the OBJECT IDENTIFIER which uniquely identifies the subagent.
description_p
A pointer to a NULL terminated character string, which is a descriptive name for the subagent. This can be any DisplayString, which basically is an octet string containing only characters from the ASCII NVT set.
timeout
The requested timeout for this subagent. An agent often has a limit for this value and it will use that limit if this value is larger. A timeout of zero has a special meaning in the sense that the agent will use its own default timeout value.
max_varBinds
The maximum number of varBinds per DPI packet that the subagent is prepared to handle. It must be a positive number or zero. If a value greater than 1 is specified, the agent will try to combine as many varBinds which belong to the same sub-tree per DPI packet as possible up to this value.

If a value of zero is specified, the agent will try to combine up to as many varBinds as are present in the SNMP packet and belong to the same sub-tree. For example, a value of zero means no limit.

character_set
The character set that you want to use for string-based data fields in the DPI packets and structures. The choices are:

DPI_NATIVE_CSET

Specifies that you want to use the native character set of the platform on which the agent that you connect to is running.
DPI_ASCII_CSET
Specifies that you want to use the ASCII character set. The agent will translate between ASCII and the native character set as required.
See Character Set Selection for more information.
password_len
The length in octets of an optional password. It depends on the agent implementation if a password is needed. If not, a zero length may be specified.
password_p
A pointer to an octet string representing the password for this subagent. A password may include any character value, including the NULL character. If the password_len is zero, this can be a NULL pointer.

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 mkDPIopen() function creates a serialized DPI OPEN packet that can then be sent to the DPI peer which is a DPI capable SNMP agent.

Normally you will want to use the native character set, which is the easiest for the subagent programmer. However, if the agent and subagent each run on their own platform and those platforms use different native character sets, you must select the ASCII character set, so that you both know exactly how to represent string-based data that is being send back and forth.

Currently you do not need to specify a password to connect to the OS/2 SNMP agent. Therefore, you can pass a length of zero and a NULL pointer for the password.

Examples

  #include <snmp_dpi.h>  unsigned char *pack_p;

  pack_p = mkDPIopen("1.3.6.1.2.3.4.5",
                "Sample DPI subagent"
                0L,2L, DPI_NATIVE_CSET, /* max 2 varBinds */
                0,(char *)0);
  if (pack_p) {
     /* send packet to the agent */
  } /* endif */

Related Information

Character Set Selection

---

[Back: The mkDPIclose() Function]
[Next: The mkDPIregister() Function]