net-snmp 5.7
session_api.h
00001 #ifndef NET_SNMP_SESSION_API_H
00002 #define NET_SNMP_SESSION_API_H
00003 
00009 #include <net-snmp/types.h>
00010 
00011 #ifdef __cplusplus
00012 extern          "C" {
00013 #endif
00014 
00015     NETSNMP_IMPORT
00016     void            snmp_sess_init(netsnmp_session *);
00017 
00018     /*
00019      * netsnmp_session *snmp_open(session)
00020      *      netsnmp_session *session;
00021      *
00022      * Sets up the session with the snmp_session information provided
00023      * by the user.  Then opens and binds the necessary UDP port.
00024      * A handle to the created session is returned (this is different than
00025      * the pointer passed to snmp_open()).  On any error, NULL is returned
00026      * and snmp_errno is set to the appropriate error code.
00027      */
00028     NETSNMP_IMPORT
00029     netsnmp_session *snmp_open(netsnmp_session *);
00030 
00031     /*
00032      * int snmp_close(session)
00033      *     netsnmp_session *session;
00034      *
00035      * Close the input session.  Frees all data allocated for the session,
00036      * dequeues any pending requests, and closes any sockets allocated for
00037      * the session.  Returns 0 on error, 1 otherwise.
00038      *
00039      * snmp_close_sessions() does the same thing for all open sessions
00040      */
00041     NETSNMP_IMPORT
00042     int             snmp_close(netsnmp_session *);
00043     NETSNMP_IMPORT
00044     int             snmp_close_sessions(void);
00045 
00046 
00047     /*
00048      * int snmp_send(session, pdu)
00049      *     netsnmp_session *session;
00050      *     netsnmp_pdu      *pdu;
00051      *
00052      * Sends the input pdu on the session after calling snmp_build to create
00053      * a serialized packet.  If necessary, set some of the pdu data from the
00054      * session defaults.  Add a request corresponding to this pdu to the list
00055      * of outstanding requests on this session, then send the pdu.
00056      * Returns the request id of the generated packet if applicable, otherwise 1.
00057      * On any error, 0 is returned.
00058      * The pdu is freed by snmp_send() unless a failure occured.
00059      */
00060     NETSNMP_IMPORT
00061     int             snmp_send(netsnmp_session *, netsnmp_pdu *);
00062 
00063     /*
00064      * int snmp_async_send(session, pdu, callback, cb_data)
00065      *     netsnmp_session *session;
00066      *     netsnmp_pdu      *pdu;
00067      *     netsnmp_callback callback;
00068      *     void   *cb_data;
00069      *
00070      * Sends the input pdu on the session after calling snmp_build to create
00071      * a serialized packet.  If necessary, set some of the pdu data from the
00072      * session defaults.  Add a request corresponding to this pdu to the list
00073      * of outstanding requests on this session and store callback and data,
00074      * then send the pdu.
00075      * Returns the request id of the generated packet if applicable, otherwise 1.
00076      * On any error, 0 is returned.
00077      * The pdu is freed by snmp_send() unless a failure occured.
00078      */
00079     NETSNMP_IMPORT
00080     int             snmp_async_send(netsnmp_session *, netsnmp_pdu *,
00081                                     netsnmp_callback, void *);
00082 
00083 
00084     /*
00085      * void snmp_read(fdset)
00086      *     fd_set  *fdset;
00087      *
00088      * Checks to see if any of the fd's set in the fdset belong to
00089      * snmp.  Each socket with it's fd set has a packet read from it
00090      * and snmp_parse is called on the packet received.  The resulting pdu
00091      * is passed to the callback routine for that session.  If the callback
00092      * routine returns successfully, the pdu and it's request are deleted.
00093      */
00094     NETSNMP_IMPORT
00095     void            snmp_read(fd_set *);
00096 
00097     /*
00098      * snmp_read2() is similar to snmp_read(), but accepts a pointer to a
00099      * large file descriptor set instead of a pointer to a regular file
00100      * descriptor set.
00101      */
00102     NETSNMP_IMPORT
00103     void            snmp_read2(netsnmp_large_fd_set *);
00104 
00105 
00106     NETSNMP_IMPORT
00107     int             snmp_synch_response(netsnmp_session *, netsnmp_pdu *,
00108                                         netsnmp_pdu **);
00109 
00110     /*
00111      * int snmp_select_info(numfds, fdset, timeout, block)
00112      * int *numfds;
00113      * fd_set   *fdset;
00114      * struct timeval *timeout;
00115      * int *block;
00116      *
00117      * Returns info about what snmp requires from a select statement.
00118      * numfds is the number of fds in the list that are significant.
00119      * All file descriptors opened for SNMP are OR'd into the fdset.
00120      * If activity occurs on any of these file descriptors, snmp_read
00121      * should be called with that file descriptor set.
00122      *
00123      * The timeout is the latest time that SNMP can wait for a timeout.  The
00124      * select should be done with the minimum time between timeout and any other
00125      * timeouts necessary.  This should be checked upon each invocation of select.
00126      * If a timeout is received, snmp_timeout should be called to check if the
00127      * timeout was for SNMP.  (snmp_timeout is idempotent)
00128      *
00129      * Block is 1 if the select is requested to block indefinitely, rather than
00130      * time out.  If block is input as 1, the timeout value will be treated as
00131      * undefined, but it must be available for setting in snmp_select_info.  On
00132      * return, if block is true, the value of timeout will be undefined.
00133      *
00134      * snmp_select_info returns the number of open sockets.  (i.e. The number
00135      * of sessions open)
00136      */
00137     NETSNMP_IMPORT
00138     int             snmp_select_info(int *, fd_set *, struct timeval *,
00139                                      int *);
00140 
00141     /*
00142      * snmp_select_info2() is similar to snmp_select_info(), but accepts a
00143      * pointer to a large file descriptor set instead of a pointer to a
00144      * regular file descriptor set.
00145      */
00146     NETSNMP_IMPORT
00147     int             snmp_select_info2(int *, netsnmp_large_fd_set *,
00148                                       struct timeval *, int *);
00149 
00150     /*
00151      * snmp_sess_select_info_flags() and
00152      * snmp_sess_select_info2_flags() is similar to
00153      * snmp_sess_select_info() and snmp_sess_select_info2(), but
00154      * accepts a list of flags to control aspects of its behavior.
00155      */
00156 #define NETSNMP_SELECT_NOFLAGS  0x00
00157 #define NETSNMP_SELECT_NOALARMS 0x01
00158     NETSNMP_IMPORT
00159     int             snmp_sess_select_info_flags(void *, int *, fd_set *,
00160                                                 struct timeval *, int *, int);
00161     int             snmp_sess_select_info2_flags(void *, int *,
00162                                                  netsnmp_large_fd_set *,
00163                                                  struct timeval *, int *, int);
00164 
00165     /*
00166      * void snmp_timeout();
00167      *
00168      * snmp_timeout should be called whenever the timeout from snmp_select_info
00169      * expires, but it is idempotent, so snmp_timeout can be polled (probably a
00170      * cpu expensive proposition).  snmp_timeout checks to see if any of the
00171      * sessions have an outstanding request that has timed out.  If it finds one
00172      * (or more), and that pdu has more retries available, a new packet is formed
00173      * from the pdu and is resent.  If there are no more retries available, the
00174      * callback for the session is used to alert the user of the timeout.
00175      */
00176 
00177     NETSNMP_IMPORT
00178     void            snmp_timeout(void);
00179 
00180     /*
00181      * single session API.
00182      *
00183      * These functions perform similar actions as snmp_XX functions,
00184      * but operate on a single session only.
00185      *
00186      * Synopsis:
00187      
00188      void * sessp;
00189      netsnmp_session session, *ss;
00190      netsnmp_pdu *pdu, *response;
00191      
00192      snmp_sess_init(&session);
00193      session.retries = ...
00194      session.remote_port = ...
00195      sessp = snmp_sess_open(&session);
00196      ss = snmp_sess_session(sessp);
00197      if (ss == NULL)
00198      exit(1);
00199      ...
00200      if (ss->community) free(ss->community);
00201      ss->community = strdup(gateway);
00202      ss->community_len = strlen(gateway);
00203      ...
00204      snmp_sess_synch_response(sessp, pdu, &response);
00205      ...
00206      snmp_sess_close(sessp);
00207      
00208      * See also:
00209      * snmp_sess_synch_response, in snmp_client.h.
00210      
00211      * Notes:
00212      *  1. Invoke snmp_sess_session after snmp_sess_open.
00213      *  2. snmp_sess_session return value is an opaque pointer.
00214      *  3. Do NOT free memory returned by snmp_sess_session.
00215      *  4. Replace snmp_send(ss,pdu) with snmp_sess_send(sessp,pdu)
00216      */
00217 
00218     NETSNMP_IMPORT
00219     void           *snmp_sess_open(netsnmp_session *);
00220     NETSNMP_IMPORT
00221     void           *snmp_sess_pointer(netsnmp_session *);
00222     NETSNMP_IMPORT
00223     netsnmp_session *snmp_sess_session(void *);
00224     NETSNMP_IMPORT
00225     netsnmp_session *snmp_sess_session_lookup(void *);
00226 
00227 
00228     /*
00229      * use return value from snmp_sess_open as void * parameter 
00230      */
00231 
00232     NETSNMP_IMPORT
00233     int             snmp_sess_send(void *, netsnmp_pdu *);
00234     NETSNMP_IMPORT
00235     int             snmp_sess_async_send(void *, netsnmp_pdu *,
00236                                          netsnmp_callback, void *);
00237     NETSNMP_IMPORT
00238     int             snmp_sess_select_info(void *, int *, fd_set *,
00239                                           struct timeval *, int *);
00240     NETSNMP_IMPORT
00241     int             snmp_sess_select_info2(void *, int *,
00242                                            netsnmp_large_fd_set *,
00243                                            struct timeval *, int *);
00244     /*
00245      * Returns 0 if success, -1 if fail.
00246      */
00247     NETSNMP_IMPORT
00248     int             snmp_sess_read(void *, fd_set *);
00249     /*
00250      * Similar to snmp_sess_read(), but accepts a pointer to a large file
00251      * descriptor set instead of a pointer to a file descriptor set.
00252      */
00253     NETSNMP_IMPORT
00254     int             snmp_sess_read2(void *,
00255                                     netsnmp_large_fd_set *);
00256     NETSNMP_IMPORT
00257     void            snmp_sess_timeout(void *);
00258     NETSNMP_IMPORT
00259     int             snmp_sess_close(void *);
00260 
00261     NETSNMP_IMPORT
00262     int             snmp_sess_synch_response(void *, netsnmp_pdu *,
00263                                              netsnmp_pdu **);
00264 
00265 #ifdef __cplusplus
00266 }
00267 #endif
00268 
00269 
00270     /*
00271      *    Having extracted the main ("public API") calls relevant
00272      *  to this area of the Net-SNMP project, the next step is to
00273      *  identify the related "public internal API" routines.
00274      *
00275      *    In due course, these should probably be gathered
00276      *  together into a companion 'library/session_api.h' header file.
00277      *  [Or some suitable name]
00278      *
00279      *    But for the time being, the expectation is that the
00280      *  traditional headers that provided the above definitions
00281      *  will probably also cover the relevant internal API calls.
00282      *  Hence they are listed here:
00283      */
00284 
00285 #include <net-snmp/library/snmp_api.h>
00286 #include <net-snmp/library/snmp_client.h>
00287 #include <net-snmp/library/asn1.h>
00288 #include <net-snmp/library/callback.h>
00289 
00290 #include <net-snmp/library/snmp_transport.h>
00291 #include <net-snmp/library/snmp_service.h>
00292 #include <net-snmp/library/snmpCallbackDomain.h>
00293 #ifdef NETSNMP_TRANSPORT_UNIX_DOMAIN
00294 #include <net-snmp/library/snmpUnixDomain.h>
00295 #endif
00296 #ifdef NETSNMP_TRANSPORT_UDP_DOMAIN
00297 #include <net-snmp/library/snmpUDPDomain.h>
00298 #endif
00299 #ifdef NETSNMP_TRANSPORT_TCP_DOMAIN
00300 #include <net-snmp/library/snmpTCPDomain.h>
00301 #endif
00302 #ifdef NETSNMP_TRANSPORT_UDPIPV6_DOMAIN
00303 #include <net-snmp/library/snmpUDPIPv6Domain.h>
00304 #endif
00305 #ifdef NETSNMP_TRANSPORT_TCPIPV6_DOMAIN
00306 #include <net-snmp/library/snmpTCPIPv6Domain.h>
00307 #endif
00308 #ifdef NETSNMP_TRANSPORT_IPX_DOMAIN
00309 #include <net-snmp/library/snmpIPXDomain.h>
00310 #endif
00311 #ifdef NETSNMP_TRANSPORT_AAL5PVC_DOMAIN
00312 #include <net-snmp/library/snmpAAL5PVCDomain.h>
00313 #endif
00314 
00315 #include <net-snmp/library/ucd_compat.h>
00316 
00317 #endif                          /* NET_SNMP_SESSION_API_H */