rfc1228.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

Carpenter & Wijnen                                             [Page 18]

RFC 1228                        SNMP-DPI                        May 1991


VARIABLE TYPE VALUES

   The variable type field can have the following values:

+----------------------------------------------------------------------+
| Table 12. Valid values for the Value Type field                      |
+-------+--------------------------------------------------------------+
| VALUE | VALUE TYPE                                                   |
+-------+--------------------------------------------------------------+
| 0     | text representation                                          |
+-------+--------------------------------------------------------------+
| 129   | number (integer)                                             |
+-------+--------------------------------------------------------------+
| 2     | octet string                                                 |
+-------+--------------------------------------------------------------+
| 3     | object identifier                                            |
+-------+--------------------------------------------------------------+
| 4     | empty (no value)                                             |
+-------+--------------------------------------------------------------+
| 133   | internet address                                             |
+-------+--------------------------------------------------------------+
| 134   | counter (unsigned)                                           |
+-------+--------------------------------------------------------------+
| 135   | gauge (unsigned)                                             |
+-------+--------------------------------------------------------------+
| 136   | time ticks (1/100ths seconds)                                |
+-------+--------------------------------------------------------------+
| 9     | display string                                               |
+-------+--------------------------------------------------------------+
+----------------------------------------------------------------------+

   NOTE:  Fields which represent values that are stored as a 4-byte
   integer are indicated by ORing their base type value with 128.

Error Code Values for SNMP Agent Detected Errors

   The error code can have one of the following values:














Carpenter & Wijnen                                             [Page 19]

RFC 1228                        SNMP-DPI                        May 1991


+----------------------------------------------------------------------+
| Table 13. Valid values for the SNMP Agent Minor Error Code field     |
+-------+--------------------------------------------------------------+
| VALUE | SNMP AGENT ERROR CODE                                        |
+-------+--------------------------------------------------------------+
| 0     | no error                                                     |
+-------+--------------------------------------------------------------+
| 1     | too big                                                      |
+-------+--------------------------------------------------------------+
| 2     | no such name                                                 |
+-------+--------------------------------------------------------------+
| 3     | bad value                                                    |
+-------+--------------------------------------------------------------+
| 4     | read only                                                    |
+-------+--------------------------------------------------------------+
| 5     | general error                                                |
+-------+--------------------------------------------------------------+
+----------------------------------------------------------------------+

SNMP DPI APPLICATION PROGRAM INTERFACE

   This section documents an API that implements the SNMP DPI.  This
   information has been previously published [6, 8], but the information
   provided below is more current as of May 14, 1991.

OVERVIEW OF REQUEST PROCESSING

GET PROCESSING

   A GET request is the easiest to process.  When the DPI packet is
   parsed, the parse tree holds the object ID of the variable being
   requested.

   If the specified object is not supported by the sub-agent, it would
   return an error indication of "no such name".  No name/type/value
   information would be returned.

        unsigned char *cp;

        cp = mkDPIresponse(SNMP_NO_SUCH_NAME,0);

   If the object is recognized, then the sub-agent creates a parse tree
   representing the name/type/value of the object in question (using the
   DPI API routine mkDPIset()), and returns no error indication.  This
   is demonstrated below (a string is being returned).






Carpenter & Wijnen                                             [Page 20]

RFC 1228                        SNMP-DPI                        May 1991


        char *obj_id;

        unsigned char *cp;
        struct dpi_set_packet *ret_value;
        char *data;

        /* obj_id = object ID of variable, like 1.3.6.1.2.1.1.1 */
        /* should be identical to object ID sent in get request */
        data = "a string to be returned";
        ret_value = mkDPIset(obj_id,SNMP_TYPE_STRING,
                        strlen(data)+1,data);
        cp = mkDPIresponse(0,ret_value);

SET PROCESSING

   Processing a SET request is only slightly more difficult than a GET
   request.  In this case, additional information is made available in
   the parse tree, namely the type, length and value to be set.

   The sub-agent may return an error indication of "no such name" if the
   variable is unrecognized, just as in a GET request.  If the variable
   is recognized, but cannot be set, an error indication of "no such
   name" should be also be returned, although it is tempting to return a
   "read only" error.

GET NEXT PROCESSING

   GET-NEXT requests are the most complicated requests to process.
   After parsing a GET-NEXT request, the parse tree will contain two
   parameters.  One is the object ID on which the GET-NEXT operation is
   being performed.  The semantics of the operation are that the sub-
   agent is to return the name/type/value of the next variable it
   supports whose name lexicographically follows the passed object ID.

   It is important to realize that a given sub-agent may support several
   discontiguous sections of the MIB tree.  In such a situation it would
   be incorrect to jump from one section to another.  This problem is
   correctly handled by examining the second parameter which is passed.
   This parameter represents the "reason" why the sub-agent is being
   called.  It holds the prefix of the tree that the sub-agent had
   indicated it supported.

   If the next variable supported by the sub-agent does not begin with
   that prefix, the sub-agent must return an error indication of "no
   such name".  If required, the SNMP agent will call upon the sub-agent
   again, but pass it a different group prefix.  This is illustrated in
   the discussion below:




Carpenter & Wijnen                                             [Page 21]

RFC 1228                        SNMP-DPI                        May 1991


   Assume there are two sub-agents.  The first sub-agent registers two
   distinct sections of the tree, A and C.  In reality, the sub-agent
   supports variables A.1 and A.2, but it correctly registers the
   minimal prefix required to uniquely identify the variable class it
   supports.

   The second sub-agent registers a different section, B, which appears
   between the two sections registered by the first agent.

   If a remote management station begins dumping the MIB, starting from
   A, the following sequence of queries would be performed:

     Sub-agent 1 gets called:
            get-next(A,A) == A.1
            get-next(A.1,A) = A.2
            get-next(A.2,A) = error(no such name)

     Sub-agent 2 is then called:
            get-next(A.2,B) = B.1
            get-next(B.1,B) = error(no such name)

     Sub-agent 1 gets called again:
            get-next(B.1,C) = C.1

REGISTER REQUESTS

   A sub-agent must register the variables it supports with the SNMP
   agent.  The appropriate packets may be created using the DPI API
   library routine mkDPIregister().

         unsigned char *cp;

         cp = mkDPIregister("1.3.6.1.2.1.1.2.");

NOTE:  object IDs are registered with a trailing dot (".").

TRAP REQUESTS

   A sub-agent can request that the SNMP agent generate a trap for it.
   The sub-agent must provide the desired values for the generic and
   specific parameters of the trap.  It may optionally provide a
   name/type/value parameter that will be included in the trap packet.
   The DPI API library routine mkDPItrap() can be used to generate the
   required packet.







Carpenter & Wijnen                                             [Page 22]

RFC 1228                        SNMP-DPI                        May 1991


DPI API LIBRARY ROUTINES

   This section documents Application Program Interfaces to the DPI.

   QUERY_DPI_PORT()

     int port;
     char *hostname, *community_name;

     port = query_DPI_port(hostname, community_name);

   The query_DPI_port() function is used by a DPI client to determine
   what TCP port number is associated with the DPI.  This port number is
   needed to connect() to the SNMP agent.  If the port cannot be
   determined, -1 is returned.

   The function is passed two arguments:  a string representing the
   host's name or IP address and the community name to be used when
   making the request.

   This function enables a DPI client to "bootstrap" itself.  The port
   number is obtained via an SNMP GET request, but the DPI client does
   not have to be able to create and parse SNMP packets--this is all
   done by the query_DPI_port() function.

   NOTE:  the query_DPI_port() function assumes that the community name
   does not contain any null characters.  If this is not the case, use
   the _query_DPI_port() function which takes a third parameter, the
   length of the community name.

MKDPIREGISTER

     #include "snmp_dpi.h"

     unsigned char *packet;
     int len;

     /* register sysDescr variable */
     packet = mkDPIregister("1.3.6.1.2.1.1.1.");

     len = *packet * 256 + *(packet + 1);
     len += 2;  /* include length bytes */

   The mkDPIregister() function creates the necessary register-request
   packet and returns a pointer to a static buffer holding the packet
   contents.  The null pointer (0) is returned if there is an error
   detected during the creation of the packet.




Carpenter & Wijnen                                             [Page 23]

RFC 1228                        SNMP-DPI                        May 1991


   The length of the remainder packet is stored in the first two bytes
   of the packet, as demonstrated in the example above.

   NOTE:  object identifiers are registered with a trailing dot (".").

MKDPISET

     #include "snmp_dpi.h"

     struct dpi_set_packet *set_value;

     char *obj_id;
     int type, length;
     char *value;

     set_value = mkDPIset(obj_id, type, length, value);

   The mkDPIset() function can be used to create the portion of a parse
   tree that represents a name/value pair (as would be normally be
   returned in a response packet).  It returns a pointer to a
   dynamically allocated parse tree representing the name/type/value
   information.  If there is an error detected while creating the parse
   tree, the null pointer (0) is returned.

   The value of type can be one of the following (which are defined in
   the include file "snmp_dpi.h"):

      o   SNMP_TYPE_NUMBER
      o   SNMP_TYPE_STRING
      o   SNMP_TYPE_OBJECT
      o   SNMP_TYPE_INTERNET
      o   SNMP_TYPE_COUNTER
      o   SNMP_TYPE_GAUGE
      o   SNMP_TYPE_TICKS

   The value parameter is always a pointer to the first byte of the
   object's value.

   NOTE:  the parse tree is dynamically allocated and copies are made of
   the passed parameters.  After a successful call to mkDPIset(), they
   can be disposed of in any manner the application chooses without
   affecting the parse tree contents.

MKDPIRESPONSE

     #include "snmp_dpi.h"

     unsigned char *packet;