6    Extensible SNMP Application Programming Interface

The Simple Network Management Protocol (SNMP) is an application layer protocol that allows remote management and data collection from networked devices. A networked device can be anything that is connected to the network, such as a router, a bridge, or a host.

A managed networked device contains software that acts as the SNMP agent for the device. It handles the application layer protocol for SNMP and carries out the management commands. These commands consist of getting information and setting of operational parameters.

There are also network management application programs (usually running on a host somewhere on the network) that send SNMP commands to the various managed devices on the network to perform the management tasks. These tasks can consist of configuration management, network traffic monitoring and network trouble shooting.

The Extensible Simple Network Management Protocol (eSNMP) is the SNMP agent architecture for a host machine on the network running Tru64 UNIX or earlier versions of DIGITAL UNIX. It includes a master-agent process and multiple related processes containing eSNMP subagents. The master-agent performs the SNMP protocol handling and the subagents perform the requested management commands. This section assumes you are familiar with the following:

This chapter provides the following information:

6.1    Overview of eSNMP

This section describes the components and architecture of the eSNMP agent. It contains information on the following:

6.1.1    Components of eSNMP

The eSNMP components are as follows:

The Management Information Base (MIB) defines a set of data elements that relate to network management. Many of these are standardized in the RFCs which are produced as a result of the Internet Engineering Task Force (IETF) working group standardization effort of the Internet Society.

The data elements defined in the RFCs are identified using a naming scheme with a hierarchical structure. Each name at each level of the hierarchy has a number associated with it. You can refer to the data elements in the MIB definitions by name or by its corresponding sequence of numbers. This is called the Object Identifier (OID). You can extend an OID for an specific data element further by adding more numbers to identify a specific instance of the data element. The entire collection of managed data elements is called the MIB tree.

Each SNMP agent implements those MIB elements that pertain to the device being managed, plus a few common MIB elements. These are the supported MIB tree elements. An extensible SNMP agent is one that permits its supported MIB tree to be distributed among various processes and change dynamically.

For eSNMP there is a single master-agent and there may be any number of subagents. The master-agent itself does not support (implement) any MIBs, it handles the SNMP protocol and maintains a registry of subagents and the MIBs they support. The master-agent for eSNMP is the daemon process /usr/sbin/snmpd.

The eSNMP protocol contains one standard subagent that implements the common MIB elements contained under the mib-2 OID name. This is the daemon process /usr/sbin/os_mibs. Another eSNMP subagent is built into the gated daemon process (/usr/sbin/gated). Additional subagents will be added by Digital and third parties. These subagents communicate with the master-agent and work together to appear to the management application programs as a single SNMP agent for the host.

6.1.2    Architecture

The master-agent listens on the preassigned User Datagram Protocol (UDP) port for an incoming SNMP request. When the master-agent receives an SNMP request, it authenticates it against the local security database and handles any authentication or protocol errors. If the request is valid, the snmpd daemon consults its MIB registry. (See the snmpd(8) reference page for more information.) For each MIB object contained in the request it determines which registered MIB could contain that object and which subagent has registered that MIB. The master-agent then builds a series of messages; one for each subagent that will be involved in this SNMP request. These messages do not carry SNMP, but use the more efficient eSNMP protocol [Footnote 15] for communication between the master-agent and the subagents.

Each subagent program is linked with the shareable library libesnmp.so. This library contains the protocol implementation that enables communication between the master-agent and the subagent. This code parses the master-agent's message and consults its local object table.

The object table is a data structure that is defined and initialized in code emitted by the MIB compiler tools. It contains an entry for each MIB object that is contained in the MIBs implemented in that subagent. One part of an object table entry is the address of a function which services requests for this MIB object. These functions are called method routines.

The eSNMP library code calls into the indicated method routine for each of the MIB variables in the master-agent's message. The eSNMP library code creates a response packet based on the function return values and sends it back to the master-agent.

The master-agent starts a timer and marshals the response packets from all involved subagents. The master-agent may rebuild and resend a new set of subagent messages, depending on the specific request; for example, a GetNext request. When the master-agent has all required data or error responses or has timed out waiting for a response from a subagent, it builds an SNMP response message and sends it to the originating SNMP application. The interaction between the master-agent and subagent is invisible to the requesting SNMP management application.

Subagent programs are linked against libesnmp.so shareable library, which performs all the protocol handling and dispatching. Subagent developers need to code the method routines for their MIB objects.

6.1.3    SNMP Versions

Extensible SNMP support for SNMPv2 exists in the following areas. This is based on RFCs RFC 1901 through RFC 1908, inclusive:

6.2    Overview of the Extensible SNMP Application Programming Interface

The subagent's function is to establish communications with the master-agent, register the MIBs that it is going to handle, and process requests from the master-agent. It must also be able to send SNMP traps on behalf of the host application.

The subagent consist of the following:

The subagent is usually embedded within a host application, such as a router daemon. Here the subagent processing is only a small part of the work performed by the process. The main routine of the host application contains the calls to the eSNMP library to perform the eSNMP protocol. In other cases, the subagent is a standalone daemon process that has its own main routine.

The eSNMP library calls the method routines while processing a packet from the master-agent. Each MIB variable in the object table has a pointer to the method routine that is to handle that variable. Since the object tables are generated by the mosy and snmpi programs, the method routine names are static.

The eSNMP developer's kit provided with the operating system consists of the following:

The eSNMP library (libesnmp.so) contains the following:

The esnmp.h header file is associated with the eSNMP library. This file defines all data structures, constants, and function prototyes required to implement subagents to this API.

6.2.1    Subtrees

Understanding subtrees is crucial to understanding the eSNMP API and how your subagent will work.

Note

This section assumes that you understand the OID naming structure used in SNMP. If not, refer to RFC 1902: Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2).

The information in SNMP is structured hierarchically like an inverted tree. Data can be associated with any leaf node in this hierarchy. Each node has a name and a number. Each node can also be identified by an OID, which is an accumulation of the numbers that make up a path from the root down to that node in the tree.

For example, the chess MIB used in the sample code has an element with the name chess. The OID for the element chess is 1.3.6.1.4.1.36.2.15.2.99, which is derived from its position in the hierarchy: (The chess MIB appears in the /usr/examples/esnmp directory.) 

iso(1)
 org(3)
  dod(6)
   internet(1)
    private(4)
     enterprise(1)
      digital(36)
       ema(2)
        sysobjects(15)
         decosf(2)
          chess(99)

Any node in the MIB hierarchy can define a subtree. All elements within the subtree have an OID that starts with OID of the subtree base. For example, if we define chess to be a subtree base, the elements with the same prefix as the chess OID are all within the subtree: 

chess                  1.3.6.1.4.1.36.2.15.2.99
 chessProductID        1.3.6.1.4.1.36.2.15.2.99.1     ObjectID
 chessMaxGames         1.3.6.1.4.1.36.2.15.2.99.2     Integer32
 chessNumGames         1.3.6.1.4.1.36.2.15.2.99.3     Integer32
 gameTable             1.3.6.1.4.1.36.2.15.2.99.4
  gameEntry            1.3.6.1.4.1.36.2.15.2.99.4.1
   gameIndex           1.3.6.1.4.1.36.2.15.2.99.4.1.1 Integer32
   gameDescr           1.3.6.1.4.1.36.2.15.2.99.4.1.2 DisplayString
gameNumMoves           1.3.6.1.4.1.36.2.15.2.99.4.1.3 Integer32
   gameStatus          1.3.6.1.4.1.36.2.15.2.99.4.1.4 INTEGER
 moveTable             1.3.6.1.4.1.36.2.15.2.99.5
  moveEntry            1.3.6.1.4.1.36.2.15.2.99.5.1
   moveIndex           1.3.6.1.4.1.36.2.15.2.99.5.1.1
   moveByWhite         1.3.6.1.4.1.36.2.15.2.99.5.1.2 DisplayString
   moveByBlack         1.3.6.1.4.1.36.2.15.2.99.5.1.3 DisplayString
   moveStatus          1.3.6.1.4.1.36.2.15.2.99.5.1.4 INTEGER
 chessTraps            1.3.6.1.4.1.36.2.15.2.99.6
  moveTrap             1.3.6.1.4.1.36.2.15.2.99.6.1

It is this subtree base that is registered with the master-agent to tell it that this subagent handles all requests related to the elements within the subtree.

The master-agent expects a subagent to handle all objects subordinate to the registered subtree. This principle guides your choice of subtrees.

For example, registering a subtree of chess is reasonable because it is realistic to assume that the subagent could handle all requests for elements in this subtree. Registering an entire application-specific MIB usually makes sense because the particular application expects to handle all objects defined in the MIB.

Registering a subtree of transmission (under MIB-2) would be a mistake, because it is unlikely that the subagent is prepared to handle every MIB subordinate to transmission (FDDI, Token Ring, and so on).

A subagent may register as many subtrees as it wants. It can register OIDs that overlap with other registrations by itself or other subagents; however, it cannot register the same OID more than once. The subagents can register and unregister subtrees at any time after it has established communication with the master-agent.

Normally it is the nonterminal nodes that are registered as a subtree with the master-agent. However, terminal nodes (those of one object type), or even specific instances, can be registered as a subtree.

The master-agent distributes requests to the subagent that has the subtree with the highest priority (largest priority number) or the most recent (if priority is equal), matching the OID on the variable bindings of the request.

6.2.2    Object Tables

The mosy and snmpi utilities are used to generate the C language code that defines the object tables from the MIBs. The object tables are defined in the emitted files subtree_tbl.h and subtree_tbl.c, files that are compiled into your subagent.

These modules are created by the utilities and it is recommended that they not be edited. If the MIBs change or a future version of the eSNMP development utilities require your object tables to be rebuilt, it is easy to rebuild the files and recompile them if you did not edit the files.

6.2.2.1    The subtree_tbl.h File

The subtree_tbl.h file contains the following information:

The first section is a declaration of the subtree structure. The subtree is automatically initialized by code in the subtree_tbl.c file. A pointer to this structure is passed to the esnmp_register routine to register a subtree with the master-agent. All access to the object table for this subtree is through this pointer. The declaration has the following form:

extern SUBTREE subtree_subtree;

The next section contains index definitions for each MIB variable in the SUBTREE of the form:

#define I_mib-variable nnnn

These values are unique for each MIB variable within a subtree and are the index into the object table for this MIB variable. These values are also generally used to differentiate between variables that are implemented in the same method routine so they can be used in a switch operation.

The next section contains enumeration definitions for those integer MIB variables that are defined with enumerated values, as follows:

#define D_mib-variable_enumeration-name value

These are useful since they describe the architected value that enumerated integer MIB variables may take on; for example: 

/* enumerations for gameEntry group */
   #define   D_gameStatus_complete         1
   #define   D_gameStatus_underway         2
   #define   D_gameStatus_delete           3

The next section contains the MIB group data structure definitions of the form:

typedef structxxx {
        type mib-variable;
.
.
.
        char mib-variable_mark;
.
.
.

         } mib-group_type

One of these data structures is emitted for each MIB group within the subtree. Each structure definition contains a field representing each MIB variable within the group. If the MIB variable name is not unique within the pool of MIBs presented to the snmpi program at the time the subtree_tbl.h file is built, the snmpi program does not qualify the name with the name of its parent variable (group name) to make it unique. In addition to the MIB variable fields, the structure includes a 1-byte mib-variable_mark field for each variable. You can use these for maintaining status of a MIB variable; for example, the following is the group structure for the chess MIB: 

typedef struct _chess_type {
    OID   chessProductID;
    int   chessMaxGames;
    int   chessNumGames;
 
    char chessProductID_mark;
    char chessMaxGames_mark;
    char chessNumGames_mark;
} chess_type;

These MIB group structures are provided for convenience, but are not mandatory. You can use whatever structure is easiest for you in your method routine.

The next section is the method routine function prototypes. Each MIB group within the subtree has a method routine prototype defined. A MIB group is a collection of MIB variables that are leaf nodes and share a common parent node.

There is always a function prototype for the method routine that handles the Get, GetNext, and GetBulk operations. If the group contains any writable variables, there is also a function prototype for the method routine that handles Set operations. Pointers to these routines appear in the subtree's object table which is initialized in the subtree_tbl.c module. You must write method routines for each prototype that is defined, as follows:

extern int mib-group_get((METHOD *method) );

extern int mib-group_set((METHOD *method) );

For example: 

extern int chess_get(METHOD *method);
extern int chess_set(METHOD *method);

Method routines are discussed in more detail in Section 6.3.2.3.

6.2.2.2    The subtree_tbl.c File

The subtree_tbl.c file contains the following information:

The first section is the array of integers used for the OIDs of each MIB variable in the subtree, as follows: 

static unsigned int elems[] = { ...

The next section is an array of OBJECT structures. There is one OBJECT for each MIB variable within the subtree. (See esnmp.h.)

An OBJECT represents a MIB variable and has the following fields:

The master-agent has no knowledge of object tables or MIB variables. It only maintains a registry of subtrees. When a request for a particular MIB variable arrives, it is processed as follows. In the following procedure, the MIB variable is mib_var and the subtree is subtree_1:

  1. The master-agent finds which subagent registered subtree_1 which contains (for Get or Set requests) or might contain (for GetNext or GetBulk requests) mib_var.

  2. It sends an eSNMP message to the subagent that registered subtree_1.

  3. The subagent consults its list of registered subtrees and locates subtree_1. It searches the object table of subtree_1 and locates the following:

  4. It calls the appropriate method routine. If the method routine completes successfully, the data is returned to the master-agent. If not, for Get or Set, an error is returned. For Next or Bulk, the libsnmp code keeps trying subsequent objects in the object table of subtree_1 until a method routine returns success or the table is exhausted; in either case a response is returned.

  5. If the master-agent detects subtree_1 could not return data on a Next or Bulk routine, it recursively tries the subtree lexicographically after subtree_1.

The next section is the SUBTREE structure itself. It is a pointer to this structure that is passed to the esnmp_register eSNMP library routine to register the subtree. It is through this pointer that the library routines find the object structures. The following is an example of the chess subtree structure: 

SUBTREE chess_subtree = { "chess", "1.3.6.1.4.1.36.2.15.2.99",
                        { 11, &elems[0] }, objects, I_moveStatus};

The SUBTREE structure has the following elements:

The final section of the subtree_tbl.c contains short routines for allocating and freeing the mib-group_type structures. These are provided as a convenience and are not a required part of the API.

6.2.3    Implementing a Subagent

As a subagent developer, you are usually presented with a UNIX application, daemon, or driver (such as the gated daemon or ATM drivers) and have to implement an SNMP interface. The following steps explain how you do this:

  1. Obtain a MIB specification.

    MIB development starts with a MIB specification, usually in the form of RFCs. For SNMPv1, the specifications are written in concise MIB format according to RFC 1212. For SNMPv2, the specifications are written in SMIv2 and the textual conventions as specified in RFC 1902 and RFC 1903, respectively. Designing and specifying a MIB is beyond the scope of this document; it is assumed you have a MIB specification.

    The standard RFCs can be obtained from the the ISI directory at the following URL: 

    
http://info.internet.isi.edu/1/in-notes/rfc

    If you have to build your own MIB specification, you can look at similar MIBs written by another vendor. One source for a listing of these is in the archives section of the Network Management page at the following URL: 

    http://smurfland.cit.buffalo.edu/NetMan/index.html

    You need MIBs for all of the elements you are implementing in the subagent and for any elements referenced by these MIBs (such that all element names resolve to the OID numbers). As a minimum you will need the SMI MIB rfc1442.my and the textual conventions v2-tc.my. These are in the /usr/examples/esnmp directory.

  2. Compile your MIBs.

    Once you obtain MIB definitions, use them to generate the object tables for your new subagent. The objective is to take the MIB specification text for each of the MIBs, remove the ASN.1 specifications, and compile them into C language modules that contain the local object tables.

    Compile your MIBs using the following tools:

  3. Code the method routines and the API calls.

    Write the code that calls the eSNMP library API to initialize communications with the master-agent (snmpd), and register your MIBs. (See Section 6.2.4.)

    Write the code for the required method routines. (See Section 6.3.) Usually you need one Get method routine and one Set method routine for each MIB group within your registered MIB subtree. The subtree_tbl.h files generated in the previous step define the names and function prototype for each method routine you need.

  4. Build the subagent.

    An example Makefile is provided in the /usr/examples/esnmp directory.

  5. Execute and test your subagent.

    Run your subagent like any other program or daemon. There are trace facilities built into the eSNMP library routines to assist in the debugging process. Use the set_debug_level routine in the main section to enable the trace.

    Once the subagent has initialized and successfully registered a MIB subtree, you can send SNMP requests using standard applications. For example, POLYCENTER Netview, HP OpenView, or any MIB browser. If you do not have access to SNMP applications, you can use the snmp_request and snmp_traprcv programs to help debug subagents.

    Note that if you interactively debug, your subagent will probably cause SNMP requests to timeout.

    Normally all error and warning messages are recorded in the system's daemon log. When running the sample chess subagent and the os_mibs subagent, you specify a trace runtime argument, as follows: 

    os_mibs -trace

    With the trace option active, the program does not daemonize and all trace output goes to stdout; it displays each message that is processed.

    You can use this feature in your own subagents by calling the set_debug_level routine and pass it the TRACE parameter.

    Anything passed in the debug macro is sent to stdout, as follows:

    ESNMP_LOG ((TRACE, ("message_text \n"));

    To send everything to the daemon log, call the set_debug_level routine and pass it the WARNING || DAEMON_LOG parameter or the set_debug_level routine and pass it the ERROR || DAEMON_LOG parameter to suppress warning messages.

6.2.4    Subagent Protocol Operations

The eSNMP API provides for autonomous subagents that are not closely tied to the master agent (snmpd). Subagents can be part of other subsystems or products and have primary functions not related to SNMP. For instance, the gated daemon is primarily concerned with Internet routing; however it also functions as a subagent.

In particular, the snmpd daemon does not start or stop any subagent daemons during its startup or shutdown procedures. It also does not maintain any on-disk configuration information about subagents. Whenever the snmpd daemon starts, it has no knowledge of previously registered subagents or subtrees.

Typically all daemons on the operating system are started or stopped together, as the system changes run levels. But subagents should correctly handle situations where they start before the snmpd daemon, or are running while the snmpd daemon is restarted to reload information from its configuration file. In these situations subagents need to restart the eSNMP protocol as described in the following sections.

6.2.4.1    Order of Operations

Subagent protocol operations follow the following sequence:

  1. Initialization (esnmp_init)

  2. Registration (esnmp_register [esnmp_register ...])

  3. Data communication

    The following loop happens continuously: 

    {
   determine sockets with data pending
 
   if the eSNMP socket has data pending
      esnmp_poll
 
   periodically call esnmp_are_you_there as required
   during periods of inactivity
}

  4. Termination (esnmp_term)

    Note that is very important that subagents call the esnmp_term function when they are stopping. This enables eSNMP to free system resources being used by the subagent.

The example subagent in the /usr/examples/esnmp directory shows how to code subagent protocol operations.

6.2.4.2    Function Return Values

The eSNMP API function return values indicate to a subagent both the success or failure of the requested operation and the state of the master agent. The following list provides a description of each return value and the indicated subagent actions:

6.3    Extensible SNMP Application Programming Interface

This section provides detailed information on the Extensible SNMP (eSNMP) Application Programming Interface, which consists of the following:

6.3.1    Calling Interface

The calling interface contains the following routines:

6.3.1.1    The esnmp_init Routine

The esnmp_init routine locally initializes the eSNMP subagent, and initiates communication with the master-agent.

This call does not block waiting for a response from the master-agent. After calling the esnmp_init routine, call the esnmp_register routine for each subtree that is to be handled by this subagent.

Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the esnmp_init routine clears all registrations so each subtree must be reregistered.

You should attempt to create a unique subagent_identifier, perhaps using the program name (argv[0]) and additional descriptive text. The master-agent does not open communications with a subagent whose subagent-identifier is already in use.

The syntax for the esnmp_init routine is as follows:

int esnmp_init(
        int socket,
        char *subagent_identifier );

The arguments are defined as follows:

socket

The address of the integer that receives the socket descriptor used by eSNMP.

subagent_identifier

The address of a null-terminated string that uniquely identifies this subagent (usually program name).

The return values are as follows:

Status ESNMP_LIB_NO_CONNECTION

Could not initialize or communicate with the master-agent. Try again after a delay.

ESNMP_LIB_OK

The esnmp_init routine has completed successfully.

The following is an example of the esnmp_init routine: 

#include <esnmp.h>
int socket;
status = esnmp_init(&socket, "gated");

6.3.1.2    The esnmp_register Routine

The esnmp_register routine requests registration of a single MIB subtree. This indicates to the master-agent that the subagent instantiates MIB variables within the registered subtree.

The initialization routine (esnmp_init) must be called prior to calling the esnmp_register routine. The esnmp_register function must be called for each subtree structure corresponding to each subtree that it will be handling. At any time subtrees can be unregistered by calling esnmp_unregister and then be reregistered by calling the esnmp_register.

When restarting the eSNMP protocol by calling esnmp_init, all registrations are cleared. All subtrees must be reregistered.

A subtree is identified by the base MIB name and its corresponding OID number of the node which is the parent of all MIB variables that are contained in the subtree; for example, the MIB-2 tcp subtree has an OID of 1.3.6.1.2.1.6. All elements subordinate to this (those that have the same first 7 digits) are included in the subtree's object table. The subtree can also be a single MIB object (a leaf node) or even a specific instance.

The master-agent requires that a subagent cannot register the same subtree more than once. Other than this one restriction, a subagent may register subtrees that overlap the OID range of subtrees that it previously registered or those of subtrees registered by other subagents.

For example, consider the os_mibs and gated daemons. The os_mibs daemon registers the ip subtree and the gated daemon registers the ipRouteTable subtree at a higher priority. Requests for operations on MIB objects within ipRouteEntry, such as ipRouteIfIndex, will go to gated because it is a higher priority. Requests for other ip objects, such as ipNetToMediaIfIndex, will be passed to os_mibs. If the gated process should terminate or unregister the ipRouteEntry subtree, subsequent requests for ipRouteIfIndex will go to os_mibs because the ip subtree, which includes the ipRouteEntry objects, will now be the highest priority in that range.

When the master-agent receives a SIGUSR1 signal, it writes its MIB registry in to the /var/tmp/snmpd_dump.log file. See the snmpd(8) reference page for more information.

The syntax for the esnmp_register routine is as follows:

int esnmp_register(
        SUBTREE *subtree,
        int timeout,
        int priority );

The arguments are defined as follows:

subtree

A pointer to a SUBTREE structure corresponding to the subtree to be handled. The SUBTREE structures are externally declared and initialized in the code emitted by the mosy and snmpi utilities (xxx_tbl.c and xxx_tbl.h, where xxx is the name of the subtree) taken directly from the MIB document.

Note

All memory pointed to by the subtree fields must have permanent storage since it is referenced by libesnmp for the duration of the program. You should use the data declarations emitted by the snmpi utility.

timeout

The number of seconds the master-agent should wait for responses when requesting data in this subtree. This value must be between zero (0) and ten (10). If the value is zero (0), the default timeout is used (3 seconds). You should use the default.

priority

The registration priority. The entry with largest number has the highest priority. The range is 0 to 65535. The subagent that has registered a subtree that has the highest priority over a range of OIDs gets all requests for that range of OIDs.

Subtrees that are registered with the same priority are ranked in order by time of registration. The most recent registration has the highest priority.

The priority argument is a mechanism for cooperating subagents to handle different configurations.

The return values are as follows:

ESNMP_LIB_OK

The esnmp_register routine has completed successfully.

ESNMP_LIB_BAD_REG

The esnmp_init routine has not been called, the timeout parameter is invalid, or this subtree has already been queued for registration.

ESNMP_LIB_LOST_CONNECTION

The subagent lost communications with the master-agent.

Note that the status indicates only the initiation of the request. The actual status returned in the master-agent's response will be returned in a subsequent call to the esnmp_poll routine.

The following is an example of the esnmp_register routine: 

#include <esnmp.h>
#define RESPONSE_TIMEOUT     0    /* use the default time set
                                     in esnmp_init message */
#define REGISTRATION_PRIORITY 10  /* priority at which subtrees
                                     will register */
 
extern SUBTREE ipRouteEntry_subtree;
 
status = esnmp_register( &ipRouteEntry_subtree,
                         RESPONSE_TIMEOUT,
                         REGISTRATION_PRIORITY );
if (status != ESNMP_LIB_OK) {"
    printf ("Could not queue the 'ipRouteEntry' \n");
    printf ("subtree for registration\n");
}

6.3.1.3    The esnmp_unregister Routine

The esnmp_unregister routine unregisters a MIB subtree with the master-agent.

This routine can be called by the application code to tell the eSNMP subagent not to process requests for variables in this subtree anymore. You can later reregister a subtree, if needed, by calling the esnmp_register routine.

The syntax for the esnmp_unregister routine is as follows:

int esnmp_unregister(
        SUBTREE *subtree );

The arguments are as follows:

*subtree

A pointer to the subtree structure for the subtree to be unregistered.

The return values are as follows:

ESNMP_LIB_OK

The routine completed successfully.

ESNMP_LIB_BAD_REG

The subtree was not registered.

ESNMP_LIB_LOST_CONNECTION

The request to unregister the subtree could not be sent. You should restart the protocol.

6.3.1.4    The esnmp_poll Routine

The esnmp_poll routine processes a pending message that has been sent by the master-agent. This routine is called after the user's select() call has indicated data is ready on the eSNMP socket. (This socket was returned from the call to the esnmp_init routine). If no message is pending on the socket, the esnmp_poll routine will block until one is received.

If a received message indicates a problem, an entry is made to the syslog file and an error status is returned.

If the received message is a request for SNMP data, the object table is consulted and the appropriate method routines are called.

The syntax for the esnmp_poll routine is as follows:

int esnmp_poll(void );

The return values are as follows:

ESNMP_LIB_OK

The esnmp_poll routine has completed successfully.

ESNMP_LIB_BAD_REG

A previous registration was failed by the master-agent. See the log file.

ESNMP_LIB_DUPLICATE

An esnmp_init error, a duplicate subagent identifier has already been received by the master-agent.

ESNMP_LIB_NO_CONNECTION

An esnmp_init request was failed by master-agent, restart after a delay. See the log file.

ESNMP_LIB_CLOSE

A CLOSE message was received.

ESNMP_LIB_NOTOK

An eSNMP protocol error occurred. The packet was discarded.

ESNMP_LIB_LOST_CONNECTION

Communication with master-agent was lost. Restart the connection.

6.3.1.5    The esnmp_are_you_there Routine

The esnmp_are_you_there routine requests the master-agent to respond immediately that it is up and functioning. This call does not block waiting for a response. It is intended to cause the master-agent to reply immediately. The response should be processed by calling the esnmp_poll routine.

If no response is received within the timeout period the application code should restart the eSNMP protocol by calling the esnmp_init routine. There are no timers maintained by the eSNMP library.

The syntax for the esnmp_are_you_there routine is as follows:

int esnmp_are_you_there(void );

The return values are as follows:

ESNMP_LIB_OK

The request was sent.

ESNMP_LIB_LOST_CONNECTION

Cannot send the request because the master-agent is down.

6.3.1.6    The esnmp_trap Routine

The esnmp_trap routine sends a trap message to the master-agent. This function can be called at anytime. If the eSNMP protocol has not initialized with the master-agent, traps are queued and sent when communication is possible.

The trap message is actually sent to the master-agent after the master-agent's response to the esnmp_init call has been processed. This processing happens within any API call, for most cases during subsequent calls to the esnmp_poll routine. The quickest way actually to send traps to the master-agent is to call the esnmp_init, esnmp_poll, and esnmp_trap routines.

The master-agent formats the trap into an SNMP trap message and sends it to management stations based on its current configuration. For information on configuring the master-agent see the snmpd(8) and snmpd.conf(4) reference pages.

There is no response returned from the master-agent for a trap.

The syntax for the esnmp_trap routine is as follows:

int esnmp_trap(
        int generic_trap,
        int specific_trap,
        char *enterprise,
        VARBIND *vb );

The arguments are as follows:

generic_trap

A generic trap code

specific_trap

A specific trap code

enterprise

An enterprise OID string in dot notation.

vb

A VARBIND list of data (a NULL pointer indicates no data)

The return values are as follows:

ESNMP_LIB_OK

The routine completed successfully.

ESNMP_LIB_LOST_CONNECTION

The routine could not send the trap message to the master-agent.

ESNMP_LIB_NOTOK

Something failed and a message could not be generated.

6.3.1.7    The esnmp_term Routine

The esnmp_term routine sends a close message to the master-agent and shuts down the eSNMP protocol. Subagents should call this routine when terminating, so that the master-agent can update its MIB registry more quickly. It is important that terminating subagents call this routine, so that system resources used by eSNMP on their behalf can be released.

The syntax for the esnmp_term routine is as follows:

void esnmp_term(void );

The return values are:

ESNMP_LIB_OK

The esnmp_term routine always returns ESNMP_LIB_OK, even if the packet could not be sent.

6.3.1.8    The esnmp_sysuptime Routine

The esnmp_sysuptime routine converts UNIX system time obtained from gettimeofday into a value with the same timebase as sysUpTime. This can be used as a TimeTicks data type (the time since the master-agent started) in units of 1/100 seconds. The time base is obtained from the master-agent in response to the esnmp_init routine, so calls to this function before that time will not be accurate.

This provides a general purpose mechanism to convert UNIX timestamps into SNMP TimeTicks. The function returns the value that sysUpTime was when the passed timestamp was now. Passing a null timestamp returns the current value of sysUpTime.

The syntax is as follows:

unsigned int esnmp_sysuptime(
        struct timeval *timestamp );

The arguments are as follows:

timestamp

Is a pointer to struct timeval containing a value obtained from the gettimeofday system call. The structure is defined in include/sys/time.h.

A NULL pointer means return the current sysUpTime.

The following is an example of the esnmp_sysuptime routine: 

#include <include/sys/time.h>
#include <esnmp.h>
struct timeval timestamp;
 
gettimeofday(&timestamp, NULL);
o_integer(vb, object, esnmp_sysuptime(&timestamp));

The return is as follows:

0

Indicates an error (gettimeofday failed); otherwise, timestamp contains the time in 1/100ths seconds since the master-agent started.

6.3.2    Method Routine Calling Interface

The method routine calling interface contains the following functions:

Section 6.3.2.3 provides additional information on method routines.

6.3.2.1    The *_get Routine

The *_get routine is a method routine for the specified MIB item, which is typically a MIB group (for example, system in MIB-2) or a table entry (for example, ifEntry in MIB-2). See the snmpi(8) reference page for more information.

The libesnmp routines call whatever routine is specified for Get operations in the object table identified by the registered subtree.

The syntax for the *_get routine is as follows:

int mib_group_get(
        METHOD *method );

The arguments are:

method

A pointer to a METHOD structure, which contains the following fields:

action

One of ESNMP_ACT_GET, ESNMP_ACT_GETNEXT, or ESNMP_ACT_GETBULK.

serial_num

An integer number that is unique to this SNMP request. Each method routine called while servicing a single SNMP request will receive the same value of serial_num. New SNMP requests are indicated by a new value of serial_num.

repeat_cnt

Used for GetBulk only. This value indicates the current iteration number of a repeating VARBIND. This number increments from 1 to max_repetitions, and is 0 for nonrepeating VARBIND structures.

max_repetitions

For GetBulk, the maximum number of repetitions to perform. This will be 0 for nonrepeating VARBIND structures. You can optimize subsequent processing by knowing the maximum number repeat calls that will be made.

varbind

A pointer to the VARBIND structure for which we must fill in the OID and data fields. Upon entry of the method routine, the method->varbind->name field is the OID that was requested.

Upon exit of the method routine, the method->varbind field contains the requested data, and the method->varbind->name field is updated to reflect the actual instance OID for the returned VARBIND.

The libsnmp routines (o_integer, o_string, o_oid, and o_octet) are generally used to load data. The libsnmp instance2oid routine is used to update the OID in method->varbind->name field.

object

A pointer to the object table entry for the MIB variable being referenced. The method->object->object_index field is this object's unique index within the object table (useful when one method routine services many objects).

The method->object->oid field is the OID defined for this object in the MIB. The instance requested is derived by comparing this OID with the OID in the request found in the method->varbind->name field. The oid2instance function is useful for this.

row

Not used on Get operations.

flags

Not used on Get operations.

security

Not currently used.

The return values for the *_get method routine are as follows:

ESNMP_MTHD_noError

The routine completed successfully.

ESNMP_MTHD_noSuchObject

The requested object cannot be returned or does not exist.

ESNMP_MTHD_noSuchInstance

The requested instance cannot be returned or does not exist.

ESNMP_MTHD_genErr

A general processing error.

6.3.2.2    The *_set Method Routine

The *_set routine is a method routine for a specified MIB item, which is typically a MIB group (for example, system in MIB-2) or a table entry (for example, ifEntry in MIB-2). See the snmpi(8) reference page for more information.

The libesnmp routines call whatever routine is specified for Set operations in the object table identified by the registered subtree.

This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The *_set method routine is called in response to a Set SNMP request.

SNMP requests may contain many VariableBindings (encoded MIB variables). The libsnmp code executing in a subagent matches each VariableBinding with an object table entry. The object table's method routine is then called.

Therefore, a method routine is called to service a single MIB variable and the same method routine may be called several times during a single SNMP request.

The syntax for the *_set method routine is as follows:

int mib_group_set(
        METHOD *method );

The arguments are as follows:

method

A pointer to a METHOD structure, which contains the following fields:

action

The action value can be one of the following: ESNMP_ACT_SET, ESNMP_ACT_COMMIT, ESNMP_ACT_UNDO, or ESNMP_ACT_CLEANUP.

serial_num

An integer number that is unique to this SNMP request. Each method routine called while servicing a single SNMP request will receive the same value of serial_num. New SNMP requests are indicated by a new value of serial_num.

repeat_cnt

Not used for Set calls.

max_repetitions

Not used for Set calls.

varbind

A pointer to the VARBIND structure which contains the MIB variable's supplied data value and name (OID). The instance information has already been extracted from the OID and placed in method->row->instance field.

object

A pointer to the object table entry for the MIB variable being referenced. The method->object->object_index field is this object's unique index within the object table (useful when one method routine services many objects).

The method->object->oid field is the OID defined for this object in the MIB.

flags

A read-only integer bitmask set by libesnmp. If set, the ESNMP_FIRST_IN_ROW bit indicates that this call is the first object to be set in the row. If set, the ESNMP_LAST_IN_ROW bit indicates that this call is the last object to be set in the row. Only METHOD structures with the ESNMP_LAST_IN_ROW bit set are passed to the method routines for commit, undo, and cleanup phases.

row

A pointer to a ROW_CONTEXT structure (defined in the esnmp.h header file). All Set calls to the method routine which refer to the same group and have the same instance number will be presented with the same row structure. The method routines can accumulate information in the row structures during Set calls for use during the omit and undo phases. The accumulated data can be released by the method routines during the cleanup phase.

instance

An address of an array containing the instance OID for this conceptual row. The libesnmp routine builds this array by subtracting the object oid from the requested variable binding oid.

instance_len

The size of the method->row->instance field.

context

A pointer to be used privately by the method routine to reference data needed to process this request.

save

A pointer to be used privately by the method routine to reference data needed to potentially undo this request.

state

An integer to be used privately by the method routine to hold any state information it requires.

security

Not currently used.

The returns for the *_set method routine are as follows:

ESNMP_MTHD_noError

The routine completed successfully.

ESNMP_MTHD_notWritable

The requested object cannot be set or was not implemented.

ESNMP_MTHD_wrongLength

The requested value is the wrong length.

ESNMP_MTHD_wrongEncoding

The requested value is represented incorrectly.

ESNMP_MTHD_wrongValue

The requested value is out of range.

ESNMP_MTHD_noCreation

The requested instance can never be created.

ESNMP_MTHD_inconsistentName

The requested instance cannot currently be created.

ESNMP_MTHD_inconsistentValue

The requested value is not consistent.

ESNMP_MTHD_resourceUnavailable

A failure due to some resource constraint.

ESNMP_MTHD_genErr

A general processing error.

ESNMP_MTHD_commitFailed

The commit phase failed.

ESNMP_MTHD_udoFailed

Indicates the undo phase failed.

Overall Processing of the *_set Routine

Every variable binding is parsed and its object is located in the object table. A METHOD structure is created for each VARBIND structure. These METHOD structures point to a ROW_CONTEXT structure, which is useful for handling these phases. Objects in the same conceptual row all point to the same ROW_CONTEXT structure. This determination is made by checking the following:

Each ROW_CONTEXT structure is loaded with the instance information for that conceptual row. The ROW_CONTEXT structure context and save fields are set to NULL, and the state field is set to ESNMP_SET_UNKNOWN structure.

The method routine for each object is called, being passed its METHOD structure with an action code of ESNMP_ACT_SET.

If all method routines return success, a single method routine (the last one called for the row) is called for each row, with method->action == ESNMP_ACT_COMMIT.

If any row reports failure, all rows that were successfully committed are told to undo the phase. This is accomplished by calling a single method routine for each row (the same one that was called for the commit phase), with a method->action == ESNMP_ACT_UNDO.

Finally, each row is released. The same single method routine for each row is called with a method->action == ESNMP_ACT_CLEANUP. This occurs for every row, regardless of the results of previous processing.

ESNMP_ACT_SET

Each object's method routine is called during the Set phase, until all objects are processed or a method routine returns an error status value. (This is the only phase during which each object's method routine is called.) For variable bindings in the same conceptual row, the method->row field points to a common ROW_CONTEXT.

The method->flags bitmask has the ESNMP_LAST_IN_ROW bit set, if this is the last object being called for this ROW_CONTEXT. This enables you to do a final consistency check, since you have seen every variable binding for this conceptual row.

The method routine's job in this phase is to determine if the SetRequest will work, return the correct SNMP error code if not, and prepare any context data it needs to perform the Set during the commit phase.

The method->row->context field is private to the method routine; libesnmp does not use it. A typical use is to store the address of an emitted foo_type structure that has been loaded with the data from the VARBIND for the conceptual row.

ESNMP_ACT_COMMIT

Even though several variable bindings may be in a conceptual row, only the last one in order of the SetRequest is processed. So, for all the method routines that point to a common row, only the last method routine is called.

This method routine must have available to it all necessary data and context to perform the operation. It must also save a snapshot of current data or whatever it needs to undo the Set if required. The method->row->save field is intended to hold a pointer to whatever data is needed to accomplish this. A typical use is to store the address of an emitted foo_type structure that has been loaded with the current data for the conceptual row.

The method->row->save field is also private to the method routine; libesnmp does not use it.

If the set operation succeeds, return ESNMP_MTHD_noError; otherwise, back out the commit as best you can and return a value of ESNMP_MTHD_commitFailed.

If any errors were returned during the commit phase, libesnmp enters the undo phase; if not, it enters the cleanup phase.

Note

The undo phase may occur even if the Set operation in your subagent is successful because the SetRequest spanned subagents and a different subagent failed.

ESNMP_ACT_UNDO

For each conceptual row that was successfully committed, the same method routine is called with method->action == ESNMP_ACT_UNDO. The ROW_CONTEXT structures that have not yet been called for the commit phase are not called for the undo phase; they are called for cleanup phase.

The method routine should attempt to restore conditions to what they were before it executed the commit phase. (This is typically done using the data pointed to by the method->row->save field.)

If successful, return ESNMP_MTHD_noError; otherwise, return ESNMP_MTHD_undoFail.

ESNMP_ACT_CLEANUP

Regardless of what else has happened, at this point each ROW_CONTEXT participates in cleanup phase. The same method routine that was called for commit phase is called with method->action == ESNMP_ACT_CLEANUP.

This indicates the end of processing for the SetRequest. The method routine should perform whatever cleanup is required; for instance, freeing dynamic memory that might have been allocated and stored in method->row->context and method->row->save fields, and so on.

The function return status value is ignored for the cleanup phase.

6.3.2.3    Method Routines

You must write the code for the method routines declared in the subtree_tbl.h file. Each method routine has one argument, which is a pointer to the METHOD structure, as follows:

int mib_group_get(
        METHOD *method int mib_group_set(
        METHOD *method );

The Get method routines are used to perform Get, GetNext, and GetBulk operations.

Get method routines perform the following tasks:

  1. Extract the instance portion of the requested OID. You can do this manually by comparing the method->object->oid field (the object's base OID) to the method->varbind->name field (the requested OID). You can use the oid2instance libesnmp routine to do this.

  2. Determine the instance validity. The instance OID may be null or any length, depending on what was requested and how your object was selected. You may be able to fail the request immediately by checking on the instance OID.

  3. Extract the data. Based on the instance OID and method->actionfield, determine what data, if any, is to be returned.

  4. Load the response OID back into the method routine's VARBIND structure. Set the method->varbind field with the OID of the actual MIB variable instance you are returning. This is usually accomplished by loading an array of integers with the instance OID you wish to return and calling the instance2OID libesnmp routine.

  5. Load the response data back into the method routine's VARBIND structure.

    Use one of the libesnmp library routine with the corresponding data type to load the method->varbind field with the data to return:

    These routines make a copy of the data you specify. The libesnmp function manages any memory associated with copied data. The method routine must manage the original data's memory.

    The routine does any necessary conversions to the type defined in the object table for the MIB variable and copies the converted data into the method->varbind field.

    See the Value Representation section for information on data value representation.

  6. Return the correct status value, as follows:

Value Representation

The values in a VARBIND structure for each data type are represented as follows. (Refer to the esnmp.h file for a definition of the OCT and OID structures.)

6.3.3    The libsnmp Support Routines

This section provides information on the libsnmp support routines, which consist of the following:

6.3.3.1    The o_integer Routine

The o_integer routine loads an integer value into the VARBIND structure with the appropriate type.

The syntax is as follows:

int o_integer(
        VARBIND *vb,
        OBJECT *obj,
        unsigned long value );

The parameters are as follows:

vb

A pointer to the VARBIND structure which is to receive the data. This function does not allocate the VARBIND structure.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The value to be inserted into the VARBIND structure.

The real type as defined in the object structure must be one of the following; otherwise, an error is returned.

If the real type is IpAddress, then it assumes that the 4-byte integer is in network byte order and will be packaged into one of the following octet strings:

ESNMP_TYPE_Integer32:32-bit INTEGER
ESNMP_TYPE_Counter32:32-bit Counter (unsigned)
ESNMP_TYPE_Gauge32:32-bit Gauge (unsigned)
ESNMP_TYPE_TimeTicks:32-bit TimeTicks (unsigned)
ESNMP_TYPE_UInteger32:32-bit INTEGER (unsigned)
ESNMP_TYPE_Counter64:64-bit Counter (unsigned)
ESNMP_TYPE_IpAddress:IMPLICIT OCTET STRING (4)

The following is an example of the o_integer routine: 

#include <esnmp.h>
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition
VARBIND     *vb       = method->varbind;
OBJECT      *object   = method->object;
ipNetToMediaEntry_type *data;
 
switch(arg) {
case I_atIfIndex:
return o_integer(vb, object, data->ipNetToMediaIfIndex);

The following are the return values:

ESNMP_MTHD_noError

The routine completed successfully.

ESNMP_MTHD_genErr

An error has occurred.

6.3.3.2    The o_octet Routine

The o_octet routine loads an octet value into the VARBIND structure with the appropriate type.

The syntax is as follows:

int o_octet(
        VARBIND *vb,
        OBJECT *obj,
        OCT *oct );

The parameters are as follows:

vb

A pointer to the VARBIND structure which is to receive the data. This function does not allocate the VARBIND structure.

Note

If the original value in the vb field is not NULL, this routine attempts to free it. So if you issue the malloc command to allocate your own vb structure, be sure to fill it with zeros before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The value to be inserted into the VARBIND structure.

The real type as defined in the object structure must be one of the following; otherwise, an error is returned:

ESNMP_TYPE_OCTET_STRINGOCTET STRING (ASN.1)
ESNMP_TYPE_IpAddressIMPLICIT OCTET STRING (4) -- in octet form,network byte order
ESNMP_TYPE_DisplayStringDisplayString (Textual Con)
ESNMP_TYPE_NsapAddressIMPLICIT OCTET STRING
ESNMP_TYPE_OpaqueIMPLICIT OCTET STRING
ESNMP_TYPE_BIT_STRINGBIT STRING (ASN.1) -- The first byte is the numberof unused bits in the last byte.

The following is an example of the o_octet routine: 

#include <esnmp.h>
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition
VARBIND     *vb       = method->varbind;
OBJECT      *object   = method->object;
ipNetToMediaEntry_type *data;
 
switch(arg) {
 case I_atPhysAddress:
 return o_octet(vb, object, &data->ipNetToMediaPhysAddress);

The returns are as follows:

ESNMP_MTHD_noError

The routine completed successfully.

ESNMP_MTHD_genErr

An error condition has occurred.

6.3.3.3    The o_oid Routine

The o_oid routine loads an OID value into the VARBIND structure with the appropriate type.

The syntax is as follows:

int o_oid(
        VARBIND *vb,
        OBJECT *obj,
        OID *oid );

The parameters are as follows:

vb

A pointer to the VARBIND structure that is to receive the data. This function does not allocate the VARBIND structure.

Note

If the original value in the vb field is not NULL, this routine attempts to free it; therefore, if you issue the malloc command to allocate your own vb structure, fill it with zeros (0s) before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The value to be inserted into the VARBIND structure as data.

The real type as defined in the object structure must be the following; otherwise, an error is returned:

ESNMP_TYPE_OBJECT_IDENTIFIEROBJECT IDENTIFIER (ASN.1)

The following is an example of the o_oid routine: 

#include <esnmp.h>
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition
VARBIND     *vb       = method->varbind;
OBJECT      *object   = method->object;
ipNetToMediaEntry_type *data;
 
switch(arg) {
 case I_atObjectID:
  return o_oid(vb, object, &data->ipNetToMediaObjectID);

The returns are as follows:

ESNMP_MTHD_noError

The routine ended successfully.

ESNMP_MTHD_genErr

An error condition has occurred.

6.3.3.4    The o_string Routine

The o_string routine loads a string value into the VARBIND structure with the appropriate type.

The syntax is as follows:

int o_string(
        VARBIND *vb,
        OBJECT *obj,
        unsigned char *ptr,
        int len );

The parameters are as follows:

vb

A pointer to the VARBIND structure which is to receive the data. This function does not allocate the VARBIND structure.

Note

If the original value in the vb field is not NULL, this routine attempts to free it; therefore, if you issue the malloc command to allocatie your own vb structure, fill it with zeros (0s) before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the oid in the VARBIND structure.

ptr

A pointer to the buffer containing data to be inserted into the VARBIND structure as data.

len

The length of the data in buffer to which ptr points.

The real type as defined in the object structure must be one of the following; otherwise, an error is returned:

ESNMP_TYPE_OCTET_STRINGOCTET STRING (ASN.1)
ESNMP_TYPE_IpAddressIMPLICIT OCTET STRING (4) -- in octet form,network byte order
ESNMP_TYPE_DisplayStringDisplayString (Textual Con)
ESNMP_TYPE_NsapAddressIMPLICIT OCTET STRING
ESNMP_TYPE_OpaqueIMPLICIT OCTET STRING
ESNMP_TYPE_BIT_STRINGBIT STRING (ASN.1) -- The binary value of first byte is thenumber of unused bits in the last byte.
ESNMP_TYPE_OBJECT_IDENTIFIEROBJECT IDENTIFIER (ASN.1) -- in dot notation, 1.3.4.6.3

The following is an example of the o_string routine: 

#include <esnmp.h>
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition
VARBIND     *vb       = method->varbind;
OBJECT      *object   = method->object;
ipNetToMediaEntry_type *data;
 
switch(arg) {
 case I_atPhysAddress:
  return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr,
                              data->ipNetToMediaPhysAddress.len);

The return values are as follows:

ESNMP_MTHD_noError

The routine completed successfully.

ESNMP_MTHD_genErr

An error condition has occurred.

6.3.3.5    The str2oid Routine

The str2oid routine converts a null-terminated OID string (in dot notation) to an OID structure.

It dynamically allocates the elements buffer and inserts its pointer into the OID structure passed in. It is the responsibility of the caller to free this buffer. The OID can have a maximum of 128 elements.

Note that the str20id routine does not allocate an OID structure.

The syntax is as follows:

OID * str2oid(
        OID *oid,
        char *s );

The following is an example of the str20id routine: 

#include <esnmp.h>
OID abc;
if (str2oid(&abc, "1.2.5.4.3.6") == NULL)
    DPRINTF((WARNING,"It did not work...\n"));

The returns are as follows:

NULL

An error has occurred; otherwise, the pointer to the OID structure (its first argument) is returned.

6.3.3.6    The sprintoid Routine

The sprintoid routine converts an OID structure into a null-terminated string in dot notation. An OID can have up to 128 elements. A full sized OID can require a large buffer.

The syntax is as follows:

char * ssprintoid(
        char *buffer,
        OID *oid );

The following is an example of the sprintoid routine: 

#include <esnmp.h>
#define SOMETHING_BIG 1024
OID abc;
char buffer[SOMETHING_BIG];
:
: assume abc gets initialized with some value
:
printf("dots=%s\n", sprintoid(buffer, &abc));

The return values are its first argument.

6.3.3.7    The instance2oid Routine

The instance2oid routine makes a copy of the object's base OID and appends a copy of the instance array to make a complete OID for a value. The instance is an array of integers and len is the number of elements. The instance array may be created by oid2instance or constructed from key values as a result of a get_next search.

It dynamically allocates the elements buffer and inserts its pointer into the OID structure passed in. The caller is responsible for freeing this buffer.

Point to the OID structure that is to receive the new OID values and call this routine. Any previous value in the OID structure is freed (it calls free_oid first) and the new values are dynamically allocated and inserted. Be sure the initial value of the new OID structure is all zeros, if you do not want it to be freed.

Note that the instance2oid routine does not allocate an OID structure, only the array containing the elements.

The syntax is as follows:

OID * instance2oid(
        OID *new,
        OBJECT *obj,
        unsigned int *instance,
        int len );

The parameters are as follows:

new

A pointer to the OID structure that is to receive the new OID value.

obj

A pointer to the object table entry for the MIB variable being obtained. The first part of the new OID is the OID from this MIB object table entry.

instance

A pointer to an array of instance values. These values are appended to the base OID obtained from the MIB object table entry to construct the new OID.

len

The number of elements in the instance array.

The following is an example of the instance2oid routine: 

#include <esnmp.h>
VARBIND *vb;      <-- filled in
OBJECT  *object;  <-- filled in
unsigned int instance[6];
 
-- Construct the outgoing OID in a GETNEXT          --
-- Instance is N.1.A.A.A.A where A's are IP address --
instance[0] = data->ipNetToMediaIfIndex;
instance[1] = 1;
for (i = 0; i < 4; i++) {
instance[i+2]=((unsigned char *)(&data->ipNetToMediaNetAddress))[i];
}
instance2oid(&vb->name, object, instance, 6);

The returns are as follows:

NULL

An error has occurred; otherwise, the pointer to the OID structure (its first argument) is returned.

6.3.3.8    The oid2instance Routine

The oid2instance routine extracts the instance values from an OID structure and copies them to the specified array of integers. It then returns the number of elements in the array. The instance is the elements of an OID beyond those elements that identify the MIB variable. They are used as indexes to identify a specific instance of a MIB value.

If there are more elements in the OID structure than expected (more than specified by the max_len parameter), the function copies the number of elements specified by max_len only and returns the total number of elements that would have been copied had there been space.

The syntax is as follows:

int oid2instance(
        OID *oid,
        OBJECT *obj,
        unsigned int *instance,
        int max_len );

The parameters are as follows:

oid

An incoming OID structure containing an instance or part of an instance.

obj

A pointer to the object table entry for the MIB variable.

instance

A pointer to an array of unsigned integers where the index will be placed.

max_len

A number of elements available in the instance array. 

#include <esnmp.h>
OID         *incoming = &method->varbind->name;
OBJECT      *object   = method->object;
int         instLength;
unsigned int instance[6];
 
-- in a GET operation --
-- Expected Instance is N.1.A.A.A.A where A's are IP address --
instLength = oid2instance(incoming, object, instance, 6);
if (instLength != 6)
    return ESNMP_MTHD_noSuchInstance;

The value of N will be in instance[0] and the IP address will be in instance[2], instance[3], instance[4], and instance[5].

The returns are as follows:

6.3.3.9    The inst2ip Routine

The inst2ip routine returns an IP address derived from an OID instance. For evaluation of an instance for Get and Set operations use the EXACT mode. For GetNext and GetBulk operations use the NEXT mode. When using the NEXT mode, this routine's logic assumes that the search for data will be performed using greater than or equal to matches.

The syntax is as follows:

int int2ip(
        int *inst,
        int *length,
        unsigned int *ipAddr,
        int exact,
        int carry );

The parameters are as follows:

inst

A pointer to an array of unsigned int containing the instance numbers returned by the oid2instance routine to be converted to an IP address.

Each element is in the range 0 to 255. Using the EXACT mode, the routine returns 1 if an element is out of range. Using NEXT mode, a value greater than 255 causes that element to overflow. It is set to 0 and the next most significant element is incremented, so it returns a lexically equivalent value of the next possible ipAddress.

length

The number of elements in the instance array. Instances beyond the fourth are ignored. If the length is less than 4, the missing values are assumed to be 0. A negative length results in an ipaddr value of 0. For an exact match (such as Get) there must be at exactly four elements.

ipAddr

A pointer to where to return the IP address value. It is in network byte order; that is, the most significant element is first.

exact

Either TRUE or FALSE.

TRUE means do an EXACT match. If any element is greater than 255 or if there are not exactly 4 elements, return 1. The carry argument is ignored.

FALSE means do a NEXT match. That is, return the lexically next IP address if the carry is set and the length is at least 4 elements. If there are fewer than 4 elements, assume the missing values are 0. If any one element contains a value greater than 255, then zero the value and increment the next most significant element. Return 1 only in the case where there is a carry from the most significant (the first) value.

carry

The carry to add to the IP address on a NEXT match. If you are trying to determine the next possible IP address, pass in a 1; otherwise, pass in a 0. A length of less than 4 cancels the carry.

The following are examples of the inst2ip routine.

The following example converts an instance to an IP address for a Get operation, which is an EXACT match. 

#include <esnmp.h>
OID         *incoming = &method->varbind->name;
OBJECT      *object   = method->object;
int instLength;
unsigned int instance[6];
unsigned int ip_addr;
int          iface;
 
-- The instance is N.1.A.A.A.A where the A's are the IP address--
instLength = oid2instance(incoming, object, instance, 6);
if (instLength == 6 && !inst2ip(&instance[2], 4, &ip_addr, TRUE,0)) {
    iface = (int) instance[0];
}
else
   return ESNMP_MTHD_noSuchInstance;

The following example shows a GetNext operation where there is only one key or that the ipAddr value is the least significant part of the key. This is a NEXT match; therefore, a 1 is passed in for carry value. 

#include <esnmp.h>
OID         *incoming = &method->varbind->name;
OBJECT      *object   = method->object;
int instLength;
unsigned int instance[6];
unsigned int ip_addr;
int          iface;
 
-- The instance is N.1.A.A.A.A where the A's are the IP address--
instLength = oid2instance(incoming, object, instance, 6);
iface = (instLength < 1) ? 0 :(int) instance[0];
 
iface += inst2ip(&instance[2], instLength - 2, &ip_addr, FALSE, 1);

In the following example, if there is more than one part to a search key and you are doing a GetNext operation, you want to find the next possible value for the search key so you can do a cascaded greater-than or equal-to search.

If you have a search key of a number and two ipAddr values that are represented in the instance part of the OID as N.A.A.A.A.B.B.B.B with N as single valued integer and A.A.A.A portion making up one IP address and the B.B.B.B portion making up a second IP address and a total length of 9 if all elements are given, you start by converting the least significant part of the key, (that would be the B.B.B.B portion). You do that by calling the inst2ip routine passing in a 1 for the carry and 5 for the length. If the conversion of the B.B.B.B portion generated a carry (returned 1), you will pass it on to the next most significant part of the key. Therefore, convert the A.A.A.A portion by calling the inst2ip routine, passing in 1 for the length and the carry returned from the conversion of the B.B.B.B portion. The most significant element N is a number; therefore, add the carry from the A conversion to the number. If that also overflows, then this is not a valid search key. 

#include <esnmp.h>
OID         *incoming = &method->varbind->name;
OBJECT      *object   = method->object;
int instLength;
unsigned int instance[9];
unsigned int ip_addrA;
unsigned int ip_addrB;
int          iface;
int 	     carry;
 
-- The instance is N.A.A.A.A.B.B.B.B --
instLength = oid2instance(incoming, object, instance, 9);
iface = (instLength < 1) ? 0 :(int) instance[0];
carry = inst2ip(&instance[1],instLength - 1,&ip_addr,FALSE,1);
carry = inst2ip(&instance[5],instLength - 5,&ip_addr,FALSE,carry);
iface += carry;
if (iface > 0xFFFFFFFF)
-- a carry caused an overflow in the most significant element
return ESNMP_MTHD_noSuchInstance;

The returns are as follows:

6.3.3.10    The cmp_oid Routine

The cmp_oid routine compares two OID structures. This routine does an element-by-element comparison starting with the most significant element (element 0) and working toward the least significant element. If all other elements are equal, the OID structure with the fewest elements is considered less.

The syntax is as follows:

int cmp_oid(
        OID *q,
        OID *p );

The returns are as follows:

6.3.3.11    The cmp_oid_prefix Routine

The cmp_oid_prefix routine compares an OID structure against a prefix. A prefix could be the OID on an object in the object table. The elements beyond the prefix are the instance information.

This routine does an element-by-element comparison, starting with the most significant element (element 0) and working toward the least significant element. If all elements of the prefix OID match exactly with corresponding elements of OID q structure, it is considered an even match if OID q structure contains additional elements. The OID q structure is considered greater than the prefix if the first nonmatching element is larger. It is considered smaller if the first nonmatching element is less.

The syntax is as follows:

int cmp_oid_prefix(
        OID *q,
        OID *prefix );

The following is and example of the cmp_oid_prefix routine: 

#include <esnmp.h>
OID *q;
OBJECT *object;
if (cmp_oid_prefix(q, &object->oid) == 0)
   printf("matches prefix\n");

The returns are as follows:

6.3.3.12    The clone_oid Routine

The clone_oid routine makes a copy of the OID structure.

Pass in a pointer to the source OID structure to be cloned and a pointer to the new OID structure that is to receive the duplicated OID values.

It dynamically allocates the element's buffer and inserts its pointer into the OID structure that is passed in.

It is the responsibility of the caller to free this buffer.

Note that any previous elements buffer pointed to by the new OID structure will be freed and pointers to the new, dynamically allocated, buffer will be inserted. Be sure to initialize the new OID structure with zeroes (0), unless it contains an element buffer that can be freed.

Also note that this routine does not allocate an OID structure.

The syntax is as follows:

OID *clone_oid(
        OID *new,
        OID *oid );

The parameters are as follows:

new

A pointer to the OID structure that is to receive the copy.

old

A pointer to the OID structure where the data is to be obtained.

The following is an example of the clone_oid routine: 

#include <esnmp.h>
OID oid1;
OID oid2;
:
: assume oid1 gets assigned a value
:
memset(&oid2, 0, sizeof(OCT));
if (clone_oid(&oid2, &oid1) == NULL)
    DPRINTF((WARNING, "It did not work\n"));

The returns are as follows:

NULL

An error occurred; otherwise, the pointer to the OID (its first argument) is returned.

6.3.3.13    The free_oid Routine

The free_oid routine frees an OID structure's elements buffer.

It frees the buffer pointed to by the oid->elements field then zeros that field and the oid->nelem field.

Note that this routine does not deallocate the OID structure itself, only the elements buffer attached to it.

The syntax is as follows:

void free_oid(
        OID *oid );

The following is an example of the free_oid routine: 

#include <esnmp.h>
OID oid;
:
: assume oid was assigned a value (perhaps with clone_oid()
: and we are now finished with it.
:
free_oid(&oid);

6.3.3.14    The clone_buf Routine

The clone_buf routine duplicates a buffer in a dynamically allocated space. One extra byte is always allocated on end and filled with \0. If the length is less than 0, its length is set to 0. There is always a buffer pointer, unless there is a malloc error.

It is the callers responsibility to free the allocated buffer.

The syntax is as follows:

char *clone_buf(
        char *str,
        int len );

The parameters are as follows:

str

A pointer to the buffer to be duplicated.

len

A number of bytes to copy.

The following is an example of the clone_buf routine: 

#include <esnmp.h>
char *str = "something nice";
char *copy;
copy = clone_buf(str, strlen(str));

The returns are as follows:

NULL

A malloc error occurred; otherwise, the pointer to allocated buffer containing a copy of the original buffer is returned.

6.3.3.15    The mem2oct Routine

The mem2oct routine converts a string (a buffer and length), to an OCT structure.

It dynamically allocates a new buffer, copies the indicated data into it, and updates the OCT structure with the new buffer's address and length.

It is the responsibility of the caller to free the allocated buffer.

Note this routine does not allocate an OCT structure and that it does not free data previously pointed to in the OCT structure before making the assignment.

The syntax is as follows:

OCT * mem2oct(
        OCT *new,
        char *buffer,
        int len );

The following is an example of the mem2oct routine: 

#include <esnmp.h>
char buffer;
int len;
OCT abc;
 
memset(&abc, 0, sizeof(OCT));
if (mem2oct(&abc, buffer, len) == NULL)
    DPRINTF((WARNING,"It did not work...\n"));

The following are the return values:

NULL

An error occurred; otherwise, the pointer to the OCT structure (its first argument) is returned.

6.3.3.16    The cmp_oct Routine

The cmp_oct routine compares two octets. The two octets are compared byte-by-byte for the length of the shortest octet. If all bytes are equal, the lengths are compared. An octet with a null pointer is considered the same as a zero-length octet.

The syntax is as follows:

int cmp_oct(
        OCT *oct1,
        OCT *oct2 );

The following is an example of the cmp_oct routine: 

#include <esnmp.h>
OCT abc, efg;
 
if (cmp_oct(&abc, &efg) > 0)
    DPRINTF((WARNING,"octet abc is larger than efg...\n"));

The returns are as follows:

6.3.3.17    The clone_oct Routine

The clone_oct routine makes a copy of the OCT structure.

It passes in a pointer to the source OCT structure to be cloned and a pointer to the new OCT structure that is to receive the duplicated OCT structure's values.

It dynamically allocates the buffer, copies the data, and updates the new OCT structure with the buffer's address and length.

It is the responsibility of the caller to free this buffer.

Note that any previous buffer to which the new OCT structure points is freed and pointers to the new, dynamically allocated buffer are inserted. Be sure to initialize the new OCT structure with zeros (0), unless it contains a buffer that can be freed.

Also note that this routine does not allocate an OCT structure, only the elements buffer pointed to by the OCT structure.

The syntax is as follows:

OCT *clone_oct(
        OCT *new,
        OCT *old );

The parameters are as follows:

new

A pointer to the OCT structure that is to receive the copy.

old

A pointer to the OCT structure where the data is to be obtained.

The following is an example of the routine: 

#include <esnmp.h>
OCT octet1;
OCT octet2;
:
: assume octet1 gets assigned a value
:
memset(&octet2, 0, sizeof(OCT));
if (clone_oct(&octet2, &octet1) == NULL)
    DPRINTF((WARNING, "It did not work\n"));

The returms are as follows:

NULL

An error occurred; otherwise, the pointer to the OCT structure (its first argument) is returned.

6.3.3.18    The free_oct Routine

The free_oct routine frees the buffer attached to the OCT structure.

It frees a dynamically allocated buffer to which the OCT structure points, then zeros (0) the pointer and length fields in the OCT structure. If the buffer is already NULL this routine does nothing.

Note that this routine does not deallocate the OCT structure, only the buffer to which it points.

The syntax is as follows:

void free_oct(
        OCT *oct );

The following is an example of the free_oct routine: 

#include <esnmp.h>
OCT octet;
:
: assume octet was assigned a value (perhaps with mem2oct()
: and we are now finished with it.
:
free_oct(&octet);

6.3.3.19    The free_varbind_data Routine

The free_varbind_data routine frees the dynamically allocated fields within the VARBIND structure.

The routine performs a free_oid (vb -> name) operation. If the vb->type field indicates, it then frees the vb->value data using either the free_oct or the free_oid routine.

It does not deallocate the VARBIND structure itself; only the name and data buffers to which it points.

The syntax is as follows:

void free_varbind_data(
        VARBIND *vb );

The following is an example of the free_varbind_data routine: 

#include <esnmp.h>
VARBIND *vb;
 
vb = (VARBIND*)malloc(sizeof(VARBIND));
clone_oid(&vb->name, oid);
clone_oct(&vb->value.oct, data);

.
.
.
free_varbind_data(vb);
free(vb);

6.3.3.20    The set_debug_level Routine

The set_debug_level routine sets the logging level, which dictates what log messages are generated. You should call the routine during program initialization in response to runtime options. If not called, the level is set to generate WARNING and ERROR messages to stdout as the default.

The following values can be set:

The syntax is as follows:

void set_debug_level(
        int stat,
        LOG_CALLBACK_ROUTINE callback_routine );

The following is an example of the set_debug_level routine: 

#include <esnmp.h>
extern void log_handler(int level, char *message);
 
if (daemonize)
    set_debug_level(EXTERN_LOG | WARNING, log_handler);
else
    set_debug_level(TRACE, NULL);

6.3.3.21    The is_debug_level Routine

The is_debug_level routine tests the log level to see if the specified level is set. You can set the levels as follows:

The syntax is as follows:

int is_debug_level(
        int type );

The return values are as follows:

TRUE

The requested level is set and the ESNMP_LOG will generate output, or output will go to the specified destination.

FALSE

The is_debug_level routine is not set.

The following is an example of the is_debug_level routine: 

#include <esnmp.h>
 
if (is_debug_level(TRACE))
    dump_packet();

6.3.3.22    The ESNMP_LOG Routine

The ESNMP_LOG routine is an error declaration C macro defined in the <esnmp.h> header file. It gathers the information that it can obtain and sends it to the log. If DAEMON_LOG is set, log messages are sent to the daemon log. If EXTERN_LOG is set, log messages are sent to the callback function; otherwise, log messages go to standard output.

Note

The esnmp_log routine is called using the ESNMP_LOG macro, which uses the helper routine esnmp_logs to format part of the text. Do not use these functions without the ESNMP_LOG macro.

The ESNMP_LOG declaration is as follows: 

#define ESNMP_LOG(level, x) if (is_debug_level(level)) { \
         esnmp_log(level, esnmp_logs x, __LINE__, __FILE__);}

Where x is (text):

text - format, arguments, ....

For example a printf statement.

level

Can be one of the following:

ERROR

Declares an error condition.

WARNING

Declares a warning.

TRACE

Put in log file if trace is active.

The syntax is as follows:

ESNMP_LOG( level, ( format, ...))

The following is an example of the ESNMP_LOG routine: 

#include <esnmp.h>
ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));