net-snmp  5.4.1
snmp_api.h
00001 /* Portions of this file are subject to the following copyright(s).  See
00002  * the Net-SNMP's COPYING file for more details and other copyrights
00003  * that may apply:
00004  */
00005 /*
00006  * Portions of this file are copyrighted by:
00007  * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
00008  * Use is subject to license terms specified in the COPYING file
00009  * distributed with the Net-SNMP package.
00010  */
00011 #ifndef SNMP_API_H
00012 #define SNMP_API_H
00013 
00014 /*
00015  * @file snmp_api.h - API for access to snmp.
00016  * 
00017  * @addtogroup library
00018  *
00019  * Caution: when using this library in a multi-threaded application,
00020  * the values of global variables "snmp_errno" and "snmp_detail"
00021  * cannot be reliably determined.  Suggest using snmp_error()
00022  * to obtain the library error codes.
00023  *
00024  * @{
00025  */
00026 
00027 #ifndef DONT_SHARE_ERROR_WITH_OTHER_THREADS
00028 #define SET_SNMP_ERROR(x) snmp_errno=(x)
00029 #else
00030 #define SET_SNMP_ERROR(x)
00031 #endif
00032 
00033 
00034 #ifdef __cplusplus
00035 extern          "C" {
00036 #endif
00037 
00038 /***********************************************************
00039         Copyright 1989 by Carnegie Mellon University
00040 
00041                       All Rights Reserved
00042 
00043 Permission to use, copy, modify, and distribute this software and its
00044 documentation for any purpose and without fee is hereby granted,
00045 provided that the above copyright notice appear in all copies and that
00046 both that copyright notice and this permission notice appear in
00047 supporting documentation, and that the name of CMU not be
00048 used in advertising or publicity pertaining to distribution of the
00049 software without specific, written prior permission.
00050 
00051 CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
00052 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
00053 CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
00054 ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
00055 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
00056 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
00057 SOFTWARE.
00058 ******************************************************************/
00059 
00062 struct variable_list;
00063 typedef struct variable_list netsnmp_variable_list;
00064 struct timeval;
00065 struct netsnmp_transport_s;
00066 
00067 #define USM_AUTH_KU_LEN     32
00068 #define USM_PRIV_KU_LEN     32
00069 
00075 typedef struct snmp_pdu {
00076 
00077     /*
00078      * Protocol-version independent fields
00079      */
00081     long            version;
00083     int             command;
00085     long            reqid;  
00087     long            msgid;
00089     long            transid;
00091     long            sessid;
00093     long            errstat;
00095     long            errindex;       
00097     u_long          time;   
00098     u_long          flags;
00099 
00100     int             securityModel;
00102     int             securityLevel;  
00103     int             msgParseModel;
00104 
00110     void           *transport_data;
00111     int             transport_data_length;
00112 
00117     const oid      *tDomain;
00118     size_t          tDomainLen;
00119 
00120     netsnmp_variable_list *variables;
00121 
00122 
00123     /*
00124      * SNMPv1 & SNMPv2c fields
00125      */
00127     u_char         *community;
00129     size_t          community_len;  
00130 
00131     /*
00132      * Trap information
00133      */
00135     oid            *enterprise;     
00136     size_t          enterprise_length;
00138     long            trap_type;
00140     long            specific_type;
00142     unsigned char   agent_addr[4];  
00143 
00144     /*
00145      *  SNMPv3 fields
00146      */
00148     u_char         *contextEngineID;
00150     size_t          contextEngineIDLen;     
00152     char           *contextName;
00154     size_t          contextNameLen;
00156     u_char         *securityEngineID;
00158     size_t          securityEngineIDLen;    
00160     char           *securityName;
00162     size_t          securityNameLen;        
00163     
00164     /*
00165      * AgentX fields
00166      *      (also uses SNMPv1 community field)
00167      */
00168     int             priority;
00169     int             range_subid;
00170     
00171     void           *securityStateRef;
00172 } netsnmp_pdu;
00173 
00174 struct snmp_session;
00175 
00178 typedef struct snmp_session netsnmp_session;
00179 
00180 typedef int     (*snmp_callback) (int, netsnmp_session *, int,
00181                                       netsnmp_pdu *, void *);
00182 typedef int     (*netsnmp_callback) (int, netsnmp_session *, int,
00183                                          netsnmp_pdu *, void *);
00187 struct snmp_session {
00188     /*
00189      * Protocol-version independent fields
00190      */
00192     long            version;
00194     int             retries;
00196     long            timeout;        
00197     u_long          flags;
00198     struct snmp_session *subsession;
00199     struct snmp_session *next;
00200 
00202     char           *peername;
00204     u_short         remote_port;
00206     char           *localname;
00208     u_short         local_port;     
00212     u_char         *(*authenticator) (u_char *, size_t *, u_char *, size_t);
00214     netsnmp_callback callback;      
00218     void           *callback_magic;
00220     int             s_errno;
00222     int             s_snmp_errno;   
00224     long            sessid; 
00225 
00226     /*
00227      * SNMPv1 & SNMPv2c fields
00228      */
00230     u_char         *community;
00232     size_t          community_len;  
00234     size_t          rcvMsgMaxSize;
00236     size_t          sndMsgMaxSize;  
00237 
00238     /*
00239      * SNMPv3 fields
00240      */
00242     u_char          isAuthoritative;
00244     u_char         *contextEngineID;
00246     size_t          contextEngineIDLen;     
00248     u_int           engineBoots;
00250     u_int           engineTime;
00252     char           *contextName;
00254     size_t          contextNameLen;
00256     u_char         *securityEngineID;
00258     size_t          securityEngineIDLen;    
00260     char           *securityName;
00262     size_t          securityNameLen;
00263 
00265     oid            *securityAuthProto;
00267     size_t          securityAuthProtoLen;
00269     u_char          securityAuthKey[USM_AUTH_KU_LEN];       
00271     size_t          securityAuthKeyLen;
00273     u_char          *securityAuthLocalKey;       
00275     size_t          securityAuthLocalKeyLen;       
00276 
00278     oid            *securityPrivProto;
00280     size_t          securityPrivProtoLen;
00282     u_char          securityPrivKey[USM_PRIV_KU_LEN];       
00284     size_t          securityPrivKeyLen;
00286     u_char          *securityPrivLocalKey;       
00288     size_t          securityPrivLocalKeyLen;       
00289 
00291     int             securityModel;
00293     int             securityLevel;  
00295     char           *paramName;
00296 
00300     void           *securityInfo;
00301 
00305     void           *myvoid;
00306 };
00307 
00308 /*
00309  * A list of all the outstanding requests for a particular session.
00310  */
00311 #ifdef SNMP_NEED_REQUEST_LIST
00312 typedef struct request_list {
00313     struct request_list *next_request;
00314     long            request_id;     /* request id */
00315     long            message_id;     /* message id */
00316     netsnmp_callback callback;      /* user callback per request (NULL if unused) */
00317     void           *cb_data;        /* user callback data per request (NULL if unused) */
00318     int             retries;        /* Number of retries */
00319     u_long          timeout;        /* length to wait for timeout */
00320     struct timeval  time;   /* Time this request was made */
00321     struct timeval  expire; /* time this request is due to expire */
00322     struct snmp_session *session;
00323     netsnmp_pdu    *pdu;    /* The pdu for this request
00324                              * (saved so it can be retransmitted */
00325 } netsnmp_request_list;
00326 #endif                          /* SNMP_NEED_REQUEST_LIST */
00327 
00328     /*
00329      * Set fields in session and pdu to the following to get a default or unconfigured value.
00330      */
00331 #define SNMP_DEFAULT_COMMUNITY_LEN  0   /* to get a default community name */
00332 #define SNMP_DEFAULT_RETRIES        -1
00333 #define SNMP_DEFAULT_TIMEOUT        -1
00334 #define SNMP_DEFAULT_REMPORT        0
00335 #define SNMP_DEFAULT_REQID          -1
00336 #define SNMP_DEFAULT_MSGID          -1
00337 #define SNMP_DEFAULT_ERRSTAT        -1
00338 #define SNMP_DEFAULT_ERRINDEX       -1
00339 #define SNMP_DEFAULT_ADDRESS        0
00340 #define SNMP_DEFAULT_PEERNAME       NULL
00341 #define SNMP_DEFAULT_ENTERPRISE_LENGTH  0
00342 #define SNMP_DEFAULT_TIME           0
00343 #define SNMP_DEFAULT_VERSION        -1
00344 #define SNMP_DEFAULT_SECMODEL       -1
00345 #define SNMP_DEFAULT_CONTEXT        ""
00346 #ifndef NETSNMP_DISABLE_MD5
00347 #define SNMP_DEFAULT_AUTH_PROTO     usmHMACMD5AuthProtocol
00348 #else
00349 #define SNMP_DEFAULT_AUTH_PROTO     usmHMACSHA1AuthProtocol
00350 #endif
00351 #define SNMP_DEFAULT_AUTH_PROTOLEN  USM_LENGTH_OID_TRANSFORM
00352 #ifndef NETSNMP_DISABLE_DES
00353 #define SNMP_DEFAULT_PRIV_PROTO     usmDESPrivProtocol
00354 #else
00355 #define SNMP_DEFAULT_PRIV_PROTO     usmAESPrivProtocol
00356 #endif
00357 #define SNMP_DEFAULT_PRIV_PROTOLEN  USM_LENGTH_OID_TRANSFORM
00358 
00359     NETSNMP_IMPORT const char *snmp_api_errstring(int);
00360     NETSNMP_IMPORT void     snmp_perror(const char *);
00361     NETSNMP_IMPORT void     snmp_set_detail(const char *);
00362 
00363 #define SNMP_MAX_MSG_SIZE          1472 /* ethernet MTU minus IP/UDP header */
00364 #define SNMP_MAX_MSG_V3_HDRS       (4+3+4+7+7+3+7+16)   /* fudge factor=16 */
00365 #define SNMP_MAX_ENG_SIZE          32
00366 #define SNMP_MAX_SEC_NAME_SIZE     256
00367 #define SNMP_MAX_CONTEXT_SIZE      256
00368 #define SNMP_SEC_PARAM_BUF_SIZE    256
00369 
00370     /*
00371      * set to one to ignore unauthenticated Reports 
00372      */
00373 #define SNMPV3_IGNORE_UNAUTH_REPORTS 0
00374 
00375     /*
00376      * authoritative engine definitions 
00377      */
00378 #define SNMP_SESS_NONAUTHORITATIVE 0    /* should be 0 to default to this */
00379 #define SNMP_SESS_AUTHORITATIVE    1    /* don't learn engineIDs */
00380 #define SNMP_SESS_UNKNOWNAUTH      2    /* sometimes (like NRs) */
00381 
00382     /*
00383      * to determine type of Report from varbind_list 
00384      */
00385 #define REPORT_STATS_LEN 9
00386 #define REPORT_snmpUnknownSecurityModels_NUM 1
00387 #define REPORT_snmpInvalidMsgs_NUM 2
00388 #define REPORT_usmStatsUnsupportedSecLevels_NUM 1
00389 #define REPORT_usmStatsNotInTimeWindows_NUM 2
00390 #define REPORT_usmStatsUnknownUserNames_NUM 3
00391 #define REPORT_usmStatsUnknownEngineIDs_NUM 4
00392 #define REPORT_usmStatsWrongDigests_NUM 5
00393 #define REPORT_usmStatsDecryptionErrors_NUM 6
00394 
00395 #define SNMP_DETAIL_SIZE        512
00396 
00397 #define SNMP_FLAGS_USER_CREATED    0x200      /* USM user has been created */
00398 #define SNMP_FLAGS_DONT_PROBE      0x100      /* don't probe for an engineID */
00399 #define SNMP_FLAGS_STREAM_SOCKET   0x80
00400 #define SNMP_FLAGS_LISTENING       0x40 /* Server stream sockets only */
00401 #define SNMP_FLAGS_SUBSESSION      0x20
00402 #define SNMP_FLAGS_STRIKE2         0x02
00403 #define SNMP_FLAGS_STRIKE1         0x01
00404 
00405 #define CLEAR_SNMP_STRIKE_FLAGS(x) \
00406         x &= ~(SNMP_FLAGS_STRIKE2|SNMP_FLAGS_STRIKE1)
00407 
00408     /*
00409      * returns '1' if the session is to be regarded as dead,
00410      * otherwise set the strike flags appropriately, and return 0
00411      */
00412 #define SET_SNMP_STRIKE_FLAGS(x) \
00413         ((   x & SNMP_FLAGS_STRIKE2 ) ? 1 :                             \
00414          ((( x & SNMP_FLAGS_STRIKE1 ) ? ( x |= SNMP_FLAGS_STRIKE2 ) :   \
00415                                         ( x |= SNMP_FLAGS_STRIKE1 )),   \
00416                                         0))
00417 
00418     /*
00419      * Error return values.
00420      *
00421      * SNMPERR_SUCCESS is the non-PDU "success" code.
00422      *
00423      * XXX  These should be merged with SNMP_ERR_* defines and confined
00424      *      to values < 0.  ???
00425      */
00426 #define SNMPERR_SUCCESS                 (0)     /* XXX  Non-PDU "success" code. */
00427 #define SNMPERR_GENERR                  (-1)
00428 #define SNMPERR_BAD_LOCPORT             (-2)
00429 #define SNMPERR_BAD_ADDRESS             (-3)
00430 #define SNMPERR_BAD_SESSION             (-4)
00431 #define SNMPERR_TOO_LONG                (-5)
00432 #define SNMPERR_NO_SOCKET               (-6)
00433 #define SNMPERR_V2_IN_V1                (-7)
00434 #define SNMPERR_V1_IN_V2                (-8)
00435 #define SNMPERR_BAD_REPEATERS           (-9)
00436 #define SNMPERR_BAD_REPETITIONS         (-10)
00437 #define SNMPERR_BAD_ASN1_BUILD          (-11)
00438 #define SNMPERR_BAD_SENDTO              (-12)
00439 #define SNMPERR_BAD_PARSE               (-13)
00440 #define SNMPERR_BAD_VERSION             (-14)
00441 #define SNMPERR_BAD_SRC_PARTY           (-15)
00442 #define SNMPERR_BAD_DST_PARTY           (-16)
00443 #define SNMPERR_BAD_CONTEXT             (-17)
00444 #define SNMPERR_BAD_COMMUNITY           (-18)
00445 #define SNMPERR_NOAUTH_DESPRIV          (-19)
00446 #define SNMPERR_BAD_ACL                 (-20)
00447 #define SNMPERR_BAD_PARTY               (-21)
00448 #define SNMPERR_ABORT                   (-22)
00449 #define SNMPERR_UNKNOWN_PDU             (-23)
00450 #define SNMPERR_TIMEOUT                 (-24)
00451 #define SNMPERR_BAD_RECVFROM            (-25)
00452 #define SNMPERR_BAD_ENG_ID              (-26)
00453 #define SNMPERR_BAD_SEC_NAME            (-27)
00454 #define SNMPERR_BAD_SEC_LEVEL           (-28)
00455 #define SNMPERR_ASN_PARSE_ERR           (-29)
00456 #define SNMPERR_UNKNOWN_SEC_MODEL       (-30)
00457 #define SNMPERR_INVALID_MSG             (-31)
00458 #define SNMPERR_UNKNOWN_ENG_ID          (-32)
00459 #define SNMPERR_UNKNOWN_USER_NAME       (-33)
00460 #define SNMPERR_UNSUPPORTED_SEC_LEVEL   (-34)
00461 #define SNMPERR_AUTHENTICATION_FAILURE  (-35)
00462 #define SNMPERR_NOT_IN_TIME_WINDOW      (-36)
00463 #define SNMPERR_DECRYPTION_ERR          (-37)
00464 #define SNMPERR_SC_GENERAL_FAILURE      (-38)
00465 #define SNMPERR_SC_NOT_CONFIGURED       (-39)
00466 #define SNMPERR_KT_NOT_AVAILABLE        (-40)
00467 #define SNMPERR_UNKNOWN_REPORT          (-41)
00468 #define SNMPERR_USM_GENERICERROR                (-42)
00469 #define SNMPERR_USM_UNKNOWNSECURITYNAME         (-43)
00470 #define SNMPERR_USM_UNSUPPORTEDSECURITYLEVEL    (-44)
00471 #define SNMPERR_USM_ENCRYPTIONERROR             (-45)
00472 #define SNMPERR_USM_AUTHENTICATIONFAILURE       (-46)
00473 #define SNMPERR_USM_PARSEERROR                  (-47)
00474 #define SNMPERR_USM_UNKNOWNENGINEID             (-48)
00475 #define SNMPERR_USM_NOTINTIMEWINDOW             (-49)
00476 #define SNMPERR_USM_DECRYPTIONERROR             (-50)
00477 #define SNMPERR_NOMIB                   (-51)
00478 #define SNMPERR_RANGE                   (-52)
00479 #define SNMPERR_MAX_SUBID               (-53)
00480 #define SNMPERR_BAD_SUBID               (-54)
00481 #define SNMPERR_LONG_OID                (-55)
00482 #define SNMPERR_BAD_NAME                (-56)
00483 #define SNMPERR_VALUE                   (-57)
00484 #define SNMPERR_UNKNOWN_OBJID           (-58)
00485 #define SNMPERR_NULL_PDU                (-59)
00486 #define SNMPERR_NO_VARS                 (-60)
00487 #define SNMPERR_VAR_TYPE                (-61)
00488 #define SNMPERR_MALLOC                  (-62)
00489 #define SNMPERR_KRB5                    (-63)
00490 #define SNMPERR_PROTOCOL                (-64)
00491 #define SNMPERR_OID_NONINCREASING       (-65)
00492 
00493 #define SNMPERR_MAX                     (-65)
00494 
00495 #define non_repeaters   errstat
00496 #define max_repetitions errindex
00497 
00498 typedef union {
00499    long           *integer;
00500    u_char         *string;
00501    oid            *objid;
00502    u_char         *bitstring;
00503    struct counter64 *counter64;
00504 #ifdef NETSNMP_WITH_OPAQUE_SPECIAL_TYPES
00505    float          *floatVal;
00506    double         *doubleVal;
00507    /*
00508     * t_union *unionVal; 
00509     */
00510 #endif                          /* NETSNMP_WITH_OPAQUE_SPECIAL_TYPES */
00511 } netsnmp_vardata;
00512 
00513 
00518 struct variable_list {
00520    struct variable_list *next_variable;    
00522    oid            *name;   
00524    size_t          name_length;    
00526    u_char          type;   
00528     netsnmp_vardata val;
00530    size_t          val_len;
00532    oid             name_loc[MAX_OID_LEN];  
00534    u_char          buf[40];
00536    void           *data;
00538    void            (*dataFreeHook)(void *);    
00539    int             index;
00540 };
00541 
00542 
00543 
00544     /*
00545      * netsnmp_session *snmp_open(session)
00546      *      netsnmp_session *session;
00547      *
00548      * Sets up the session with the snmp_session information provided
00549      * by the user.  Then opens and binds the necessary UDP port.
00550      * A handle to the created session is returned (this is different than
00551      * the pointer passed to snmp_open()).  On any error, NULL is returned
00552      * and snmp_errno is set to the appropriate error code.
00553      */
00554     netsnmp_session *snmp_open(netsnmp_session *);
00555 
00556     /*
00557      * int snmp_close(session)
00558      *     netsnmp_session *session;
00559      *
00560      * Close the input session.  Frees all data allocated for the session,
00561      * dequeues any pending requests, and closes any sockets allocated for
00562      * the session.  Returns 0 on error, 1 otherwise.
00563      *
00564      * snmp_close_sessions() does the same thing for all open sessions
00565      */
00566     int             snmp_close(netsnmp_session *);
00567     int             snmp_close_sessions(void);
00568 
00569 
00570     /*
00571      * int snmp_send(session, pdu)
00572      *     netsnmp_session *session;
00573      *     netsnmp_pdu      *pdu;
00574      *
00575      * Sends the input pdu on the session after calling snmp_build to create
00576      * a serialized packet.  If necessary, set some of the pdu data from the
00577      * session defaults.  Add a request corresponding to this pdu to the list
00578      * of outstanding requests on this session, then send the pdu.
00579      * Returns the request id of the generated packet if applicable, otherwise 1.
00580      * On any error, 0 is returned.
00581      * The pdu is freed by snmp_send() unless a failure occured.
00582      */
00583     int             snmp_send(netsnmp_session *, netsnmp_pdu *);
00584 
00585     /*
00586      * int snmp_async_send(session, pdu, callback, cb_data)
00587      *     netsnmp_session *session;
00588      *     netsnmp_pdu      *pdu;
00589      *     netsnmp_callback callback;
00590      *     void   *cb_data;
00591      *
00592      * Sends the input pdu on the session after calling snmp_build to create
00593      * a serialized packet.  If necessary, set some of the pdu data from the
00594      * session defaults.  Add a request corresponding to this pdu to the list
00595      * of outstanding requests on this session and store callback and data,
00596      * then send the pdu.
00597      * Returns the request id of the generated packet if applicable, otherwise 1.
00598      * On any error, 0 is returned.
00599      * The pdu is freed by snmp_send() unless a failure occured.
00600      */
00601     int             snmp_async_send(netsnmp_session *, netsnmp_pdu *,
00602                                     netsnmp_callback, void *);
00603 
00604 
00605     /*
00606      * void snmp_read(fdset)
00607      *     fd_set  *fdset;
00608      *
00609      * Checks to see if any of the fd's set in the fdset belong to
00610      * snmp.  Each socket with it's fd set has a packet read from it
00611      * and snmp_parse is called on the packet received.  The resulting pdu
00612      * is passed to the callback routine for that session.  If the callback
00613      * routine returns successfully, the pdu and it's request are deleted.
00614      */
00615     void            snmp_read(fd_set *);
00616 
00617 
00618 
00619     /*
00620      * void
00621      * snmp_free_pdu(pdu)
00622      *     netsnmp_pdu *pdu;
00623      *
00624      * Frees the pdu and any malloc'd data associated with it.
00625      */
00626     void            snmp_free_pdu(netsnmp_pdu *);
00627 
00628     void            snmp_free_var(netsnmp_variable_list *);     /* frees just this one */
00629 
00630     void            snmp_free_varbind(netsnmp_variable_list * var);     /* frees all in list */
00631 
00632     /*
00633      * int snmp_select_info(numfds, fdset, timeout, block)
00634      * int *numfds;
00635      * fd_set   *fdset;
00636      * struct timeval *timeout;
00637      * int *block;
00638      *
00639      * Returns info about what snmp requires from a select statement.
00640      * numfds is the number of fds in the list that are significant.
00641      * All file descriptors opened for SNMP are OR'd into the fdset.
00642      * If activity occurs on any of these file descriptors, snmp_read
00643      * should be called with that file descriptor set.
00644      *
00645      * The timeout is the latest time that SNMP can wait for a timeout.  The
00646      * select should be done with the minimum time between timeout and any other
00647      * timeouts necessary.  This should be checked upon each invocation of select.
00648      * If a timeout is received, snmp_timeout should be called to check if the
00649      * timeout was for SNMP.  (snmp_timeout is idempotent)
00650      *
00651      * Block is 1 if the select is requested to block indefinitely, rather than
00652      * time out.  If block is input as 1, the timeout value will be treated as
00653      * undefined, but it must be available for setting in snmp_select_info.  On
00654      * return, if block is true, the value of timeout will be undefined.
00655      *
00656      * snmp_select_info returns the number of open sockets.  (i.e. The number
00657      * of sessions open)
00658      */
00659     int             snmp_select_info(int *, fd_set *, struct timeval *,
00660                                      int *);
00661 
00662 
00663 
00664     /*
00665      * void snmp_timeout();
00666      *
00667      * snmp_timeout should be called whenever the timeout from snmp_select_info
00668      * expires, but it is idempotent, so snmp_timeout can be polled (probably a
00669      * cpu expensive proposition).  snmp_timeout checks to see if any of the
00670      * sessions have an outstanding request that has timed out.  If it finds one
00671      * (or more), and that pdu has more retries available, a new packet is formed
00672      * from the pdu and is resent.  If there are no more retries available, the
00673      * callback for the session is used to alert the user of the timeout.
00674      */
00675 
00676     void            snmp_timeout(void);
00677 
00678 
00679     /*
00680      * This routine must be supplied by the application:
00681      *
00682      * u_char *authenticator(pdu, length, community, community_len)
00683      * u_char *pdu;         The rest of the PDU to be authenticated
00684      * int *length;         The length of the PDU (updated by the authenticator)
00685      * u_char *community;   The community name to authenticate under.
00686      * int  community_len   The length of the community name.
00687      *
00688      * Returns the authenticated pdu, or NULL if authentication failed.
00689      * If null authentication is used, the authenticator in snmp_session can be
00690      * set to NULL(0).
00691      */
00692 
00693 
00694 
00695     /*
00696      * This routine must be supplied by the application:
00697      *
00698      * int callback(operation, session, reqid, pdu, magic)
00699      * int operation;
00700      * netsnmp_session *session;    The session authenticated under.
00701      * int reqid;                       The request id of this pdu (0 for TRAP)
00702      * netsnmp_pdu *pdu;        The pdu information.
00703      * void *magic                      A link to the data for this routine.
00704      *
00705      * Returns 1 if request was successful, 0 if it should be kept pending.
00706      * Any data in the pdu must be copied because it will be freed elsewhere.
00707      * Operations are defined below:
00708      */
00709 
00710 #define NETSNMP_CALLBACK_OP_RECEIVED_MESSAGE    1
00711 #define NETSNMP_CALLBACK_OP_TIMED_OUT           2
00712 #define NETSNMP_CALLBACK_OP_SEND_FAILED         3
00713 #define NETSNMP_CALLBACK_OP_CONNECT             4
00714 #define NETSNMP_CALLBACK_OP_DISCONNECT          5
00715 
00716     long            snmp_get_next_msgid(void);
00717     long            snmp_get_next_reqid(void);
00718     long            snmp_get_next_sessid(void);
00719     long            snmp_get_next_transid(void);
00720 
00721     int             snmp_oid_compare(const oid *, size_t, const oid *,
00722                                      size_t);
00723     int             snmp_oid_ncompare(const oid *, size_t, const oid *,
00724                                       size_t, size_t);
00725     int             snmp_oidtree_compare(const oid *, size_t, const oid *,
00726                                          size_t);
00727     int             snmp_oidsubtree_compare(const oid *, size_t, const oid *,
00728                                          size_t);
00729     int             netsnmp_oid_compare_ll(const oid * in_name1,
00730                                            size_t len1, const oid * in_name2,
00731                                            size_t len2, size_t *offpt);
00732     int             netsnmp_oid_equals(const oid *, size_t, const oid *,
00733                                        size_t);
00734     int             netsnmp_oid_tree_equals(const oid *, size_t, const oid *,
00735                                             size_t);
00736     int             netsnmp_oid_is_subtree(const oid *, size_t, const oid *,
00737                                            size_t);
00738     int             netsnmp_oid_find_prefix(const oid * in_name1, size_t len1,
00739                                             const oid * in_name2, size_t len2);
00740     void            init_snmp(const char *);
00741     u_char         *snmp_pdu_build(netsnmp_pdu *, u_char *, size_t *);
00742 #ifdef NETSNMP_USE_REVERSE_ASNENCODING
00743     u_char         *snmp_pdu_rbuild(netsnmp_pdu *, u_char *, size_t *);
00744 #endif
00745     int             snmpv3_parse(netsnmp_pdu *, u_char *, size_t *,
00746                                  u_char **, netsnmp_session *);
00747     int             snmpv3_packet_build(netsnmp_session *,
00748                                         netsnmp_pdu *pdu, u_char * packet,
00749                                         size_t * out_length,
00750                                         u_char * pdu_data,
00751                                         size_t pdu_data_len);
00752     int             snmpv3_packet_rbuild(netsnmp_session *,
00753                                          netsnmp_pdu *pdu, u_char * packet,
00754                                          size_t * out_length,
00755                                          u_char * pdu_data,
00756                                          size_t pdu_data_len);
00757     int             snmpv3_make_report(netsnmp_pdu *pdu, int error);
00758     int             snmpv3_get_report_type(netsnmp_pdu *pdu);
00759     int             snmp_pdu_parse(netsnmp_pdu *pdu, u_char * data,
00760                                    size_t * length);
00761     u_char         *snmpv3_scopedPDU_parse(netsnmp_pdu *pdu, u_char * cp,
00762                                            size_t * length);
00763     void            snmp_store(const char *type);
00764     void            snmp_shutdown(const char *type);
00765     netsnmp_variable_list *snmp_pdu_add_variable(netsnmp_pdu *, const oid *,
00766                                                  size_t, u_char, const u_char *,
00767                                                  size_t);
00768     netsnmp_variable_list *snmp_varlist_add_variable(netsnmp_variable_list
00769                                                      ** varlist,
00770                                                      const oid * name,
00771                                                      size_t name_length,
00772                                                      u_char type,
00773                                                      const u_char * value,
00774                                                      size_t len);
00775     int             snmp_add_var(netsnmp_pdu *, const oid *, size_t, char,
00776                                  const char *);
00777     oid            *snmp_duplicate_objid(const oid * objToCopy, size_t);
00778     u_int           snmp_increment_statistic(int which);
00779     u_int           snmp_increment_statistic_by(int which, int count);
00780     u_int           snmp_get_statistic(int which);
00781     void            snmp_init_statistics(void);
00782     int             create_user_from_session(netsnmp_session * session);
00783     int snmp_get_fd_for_session(struct snmp_session *sessp);
00784 
00785     /*
00786      * New re-allocating reverse encoding functions.  
00787      */
00788 #ifdef NETSNMP_USE_REVERSE_ASNENCODING
00789 
00790     int        snmpv3_packet_realloc_rbuild(u_char ** pkt, size_t * pkt_len,
00791                                      size_t * offset,
00792                                      netsnmp_session * session,
00793                                      netsnmp_pdu *pdu, u_char * pdu_data,
00794                                      size_t pdu_data_len);
00795 
00796     int        snmp_pdu_realloc_rbuild(u_char ** pkt, size_t * pkt_len,
00797                                 size_t * offset, netsnmp_pdu *pdu);
00798 #endif
00799 
00800 
00801 
00802     /*
00803      * Extended open; fpre_parse has changed.  
00804      */
00805 
00806     netsnmp_session *snmp_open_ex(netsnmp_session *,
00807                                   int (*fpre_parse) (netsnmp_session *,
00808                                                      struct
00809                                                      netsnmp_transport_s *,
00810                                                      void *, int),
00811                                   int (*fparse) (netsnmp_session *,
00812                                                  netsnmp_pdu *, u_char *,
00813                                                  size_t),
00814                                   int (*fpost_parse) (netsnmp_session *,
00815                                                       netsnmp_pdu *, int),
00816                                   int (*fbuild) (netsnmp_session *,
00817                                                  netsnmp_pdu *, u_char *,
00818                                                  size_t *),
00819                                   int (*frbuild) (netsnmp_session *,
00820                                                   netsnmp_pdu *, u_char **,
00821                                                   size_t *, size_t *),
00822                                   int (*fcheck) (u_char *, size_t));
00823 
00824     /*
00825      * provided for backwards compatability.  Don't use these functions.
00826      * See snmp_debug.h and snmp_debug.c instead.
00827      */
00828 
00829     void            snmp_set_do_debugging(int);
00830     int             snmp_get_do_debugging(void);
00831 
00832 
00833     /*
00834      * snmp_error - return error data
00835      * Inputs :  address of errno, address of snmp_errno, address of string
00836      * Caller must free the string returned after use.
00837      */
00838     void            snmp_error(netsnmp_session *, int *, int *, char **);
00839     /*
00840      * single session API.
00841      *
00842      * These functions perform similar actions as snmp_XX functions,
00843      * but operate on a single session only.
00844      *
00845      * Synopsis:
00846      
00847      void * sessp;
00848      netsnmp_session session, *ss;
00849      netsnmp_pdu *pdu, *response;
00850      
00851      snmp_sess_init(&session);
00852      session.retries = ...
00853      session.remote_port = ...
00854      sessp = snmp_sess_open(&session);
00855      ss = snmp_sess_session(sessp);
00856      if (ss == NULL)
00857      exit(1);
00858      ...
00859      if (ss->community) free(ss->community);
00860      ss->community = strdup(gateway);
00861      ss->community_len = strlen(gateway);
00862      ...
00863      snmp_sess_synch_response(sessp, pdu, &response);
00864      ...
00865      snmp_sess_close(sessp);
00866      
00867      * See also:
00868      * snmp_sess_synch_response, in snmp_client.h.
00869      
00870      * Notes:
00871      *  1. Invoke snmp_sess_session after snmp_sess_open.
00872      *  2. snmp_sess_session return value is an opaque pointer.
00873      *  3. Do NOT free memory returned by snmp_sess_session.
00874      *  4. Replace snmp_send(ss,pdu) with snmp_sess_send(sessp,pdu)
00875      */
00876 
00877     void            snmp_sess_init(netsnmp_session *);
00878     void           *snmp_sess_open(netsnmp_session *);
00879     void           *snmp_sess_pointer(netsnmp_session *);
00880     netsnmp_session *snmp_sess_session(void *);
00881 
00882     /*
00883      * Return the netsnmp_transport structure associated with the given opaque
00884      * pointer.  
00885      */
00886 
00887     struct netsnmp_transport_s *snmp_sess_transport(void *);
00888     void            snmp_sess_transport_set(void *,
00889                                             struct netsnmp_transport_s *);
00890 
00891     /*
00892      * EXPERIMENTAL API EXTENSIONS ------------------------------------------ 
00893      * 
00894      * snmp_sess_add_ex, snmp_sess_add, snmp_add 
00895      * 
00896      * Analogous to snmp_open family of functions, but taking an
00897      * netsnmp_transport pointer as an extra argument.  Unlike snmp_open et
00898      * al. it doesn't attempt to interpret the in_session->peername as a
00899      * transport endpoint specifier, but instead uses the supplied transport.
00900      * JBPN
00901      * 
00902      */
00903 
00904     void           *snmp_sess_add_ex(netsnmp_session *,
00905                                      struct netsnmp_transport_s *,
00906                                      int (*fpre_parse) (netsnmp_session *,
00907                                                         struct
00908                                                         netsnmp_transport_s
00909                                                         *, void *, int),
00910                                      int (*fparse) (netsnmp_session *,
00911                                                     struct snmp_pdu *,
00912                                                     u_char *, size_t),
00913                                      int (*fpost_parse) (netsnmp_session *,
00914                                                          struct snmp_pdu *,
00915                                                          int),
00916                                      int (*fbuild) (netsnmp_session *,
00917                                                     struct snmp_pdu *,
00918                                                     u_char *, size_t *),
00919                                      int (*frbuild) (netsnmp_session *,
00920                                                      struct snmp_pdu *,
00921                                                      u_char **, size_t *,
00922                                                      size_t *),
00923                                      int (*fcheck) (u_char *, size_t),
00924                                      netsnmp_pdu *(*fcreate_pdu) (struct
00925                                                                   netsnmp_transport_s
00926                                                                   *,
00927                                                                   void *,
00928                                                                   size_t));
00929 
00930     void           *snmp_sess_add(netsnmp_session *,
00931                                   struct netsnmp_transport_s *,
00932                                   int (*fpre_parse) (netsnmp_session *,
00933                                                      struct
00934                                                      netsnmp_transport_s *,
00935                                                      void *, int),
00936                                   int (*fpost_parse) (netsnmp_session *,
00937                                                       netsnmp_pdu *, int));
00938 
00939     netsnmp_session *snmp_add(netsnmp_session *,
00940                               struct netsnmp_transport_s *,
00941                               int (*fpre_parse) (netsnmp_session *,
00942                                                  struct netsnmp_transport_s
00943                                                  *, void *, int),
00944                               int (*fpost_parse) (netsnmp_session *,
00945                                                   netsnmp_pdu *, int));
00946     netsnmp_session *snmp_add_full(netsnmp_session * in_session,
00947                                    struct netsnmp_transport_s *transport,
00948                                    int (*fpre_parse) (netsnmp_session *,
00949                                                       struct
00950                                                       netsnmp_transport_s
00951                                                       *, void *, int),
00952                                    int (*fparse) (netsnmp_session *,
00953                                                   netsnmp_pdu *, u_char *,
00954                                                   size_t),
00955                                    int (*fpost_parse) (netsnmp_session *,
00956                                                        netsnmp_pdu *, int),
00957                                    int (*fbuild) (netsnmp_session *,
00958                                                   netsnmp_pdu *, u_char *,
00959                                                   size_t *),
00960                                    int (*frbuild) (netsnmp_session *,
00961                                                    netsnmp_pdu *,
00962                                                    u_char **, size_t *,
00963                                                    size_t *),
00964                                    int (*fcheck) (u_char *, size_t),
00965                                    netsnmp_pdu *(*fcreate_pdu) (struct
00966                                                                 netsnmp_transport_s
00967                                                                 *, void *,
00968                                                                 size_t)
00969         );
00970 
00971     /*
00972      * use return value from snmp_sess_open as void * parameter 
00973      */
00974 
00975     int             snmp_sess_send(void *, netsnmp_pdu *);
00976     int             snmp_sess_async_send(void *, netsnmp_pdu *,
00977                                          netsnmp_callback, void *);
00978     int             snmp_sess_select_info(void *, int *, fd_set *,
00979                                           struct timeval *, int *);
00980     int             snmp_sess_read(void *, fd_set *);
00981     void            snmp_sess_timeout(void *);
00982     int             snmp_sess_close(void *);
00983 
00984     void            snmp_sess_error(void *, int *, int *, char **);
00985     void            netsnmp_sess_log_error(int priority,
00986                                            const char *prog_string,
00987                                            netsnmp_session * ss);
00988     void            snmp_sess_perror(const char *prog_string,
00989                                      netsnmp_session * ss);
00990     const char *    snmp_pdu_type(int type);
00991 
00992     /*
00993      * end single session API 
00994      */
00995 
00996     /*
00997      * generic statistic counters 
00998      */
00999 
01000     /*
01001      * snmpv3 statistics 
01002      */
01003 
01004     /*
01005      * mpd stats 
01006      */
01007 #define   STAT_SNMPUNKNOWNSECURITYMODELS     0
01008 #define   STAT_SNMPINVALIDMSGS               1
01009 #define   STAT_SNMPUNKNOWNPDUHANDLERS        2
01010 #define   STAT_MPD_STATS_START               STAT_SNMPUNKNOWNSECURITYMODELS
01011 #define   STAT_MPD_STATS_END                 STAT_SNMPUNKNOWNPDUHANDLERS
01012 
01013     /*
01014      * usm stats 
01015      */
01016 #define   STAT_USMSTATSUNSUPPORTEDSECLEVELS  3
01017 #define   STAT_USMSTATSNOTINTIMEWINDOWS      4
01018 #define   STAT_USMSTATSUNKNOWNUSERNAMES      5
01019 #define   STAT_USMSTATSUNKNOWNENGINEIDS      6
01020 #define   STAT_USMSTATSWRONGDIGESTS          7
01021 #define   STAT_USMSTATSDECRYPTIONERRORS      8
01022 #define   STAT_USM_STATS_START               STAT_USMSTATSUNSUPPORTEDSECLEVELS
01023 #define   STAT_USM_STATS_END                 STAT_USMSTATSDECRYPTIONERRORS
01024 
01025     /*
01026      * snmp counters 
01027      */
01028 #define  STAT_SNMPINPKTS                     9
01029 #define  STAT_SNMPOUTPKTS                    10
01030 #define  STAT_SNMPINBADVERSIONS              11
01031 #define  STAT_SNMPINBADCOMMUNITYNAMES        12
01032 #define  STAT_SNMPINBADCOMMUNITYUSES         13
01033 #define  STAT_SNMPINASNPARSEERRS             14
01034     /*
01035      * #define  STAT_SNMPINBADTYPES              15 
01036      */
01037 #define  STAT_SNMPINTOOBIGS                  16
01038 #define  STAT_SNMPINNOSUCHNAMES              17
01039 #define  STAT_SNMPINBADVALUES                18
01040 #define  STAT_SNMPINREADONLYS                19
01041 #define  STAT_SNMPINGENERRS                  20
01042 #define  STAT_SNMPINTOTALREQVARS             21
01043 #define  STAT_SNMPINTOTALSETVARS             22
01044 #define  STAT_SNMPINGETREQUESTS              23
01045 #define  STAT_SNMPINGETNEXTS                 24
01046 #define  STAT_SNMPINSETREQUESTS              25
01047 #define  STAT_SNMPINGETRESPONSES             26
01048 #define  STAT_SNMPINTRAPS                    27
01049 #define  STAT_SNMPOUTTOOBIGS                 28
01050 #define  STAT_SNMPOUTNOSUCHNAMES             29
01051 #define  STAT_SNMPOUTBADVALUES               30
01052     /*
01053      * #define  STAT_SNMPOUTREADONLYS            31 
01054      */
01055 #define  STAT_SNMPOUTGENERRS                 32
01056 #define  STAT_SNMPOUTGETREQUESTS             33
01057 #define  STAT_SNMPOUTGETNEXTS                34
01058 #define  STAT_SNMPOUTSETREQUESTS             35
01059 #define  STAT_SNMPOUTGETRESPONSES            36
01060 #define  STAT_SNMPOUTTRAPS                   37
01061     /*
01062      * AUTHTRAPENABLE                            38 
01063      */
01064 #define  STAT_SNMPSILENTDROPS                39
01065 #define  STAT_SNMPPROXYDROPS                 40
01066 #define  STAT_SNMP_STATS_START               STAT_SNMPINPKTS
01067 #define  STAT_SNMP_STATS_END                 STAT_SNMPPROXYDROPS
01068 
01069     /*
01070      * target mib counters 
01071      */
01072 #define  STAT_SNMPUNAVAILABLECONTEXTS        41
01073 #define  STAT_SNMPUNKNOWNCONTEXTS            42
01074 #define  STAT_TARGET_STATS_START             STAT_SNMPUNAVAILABLECONTEXTS
01075 #define  STAT_TARGET_STATS_END               STAT_SNMPUNKNOWNCONTEXTS
01076 
01077 #define  MAX_STATS                           43
01078 
01079 #ifdef __cplusplus
01080 }
01081 #endif
01082 #endif                          /* SNMP_API_H */