NAME

       snmp_sess_init,      snmp_sess_open,     snmp_sess_session,     snmp_sess_send,     snmp_sess_async_send,
       snmp_sess_select_info,  snmp_sess_read,  snmp_sess_timeout,  snmp_sess_synch_response,   snmp_sess_close,
       snmp_sess_error - session functions

SYNOPSIS

       #include <net-snmp/session_api.h>

       void snmp_sess_init(struct snmp_session *session);

       void *snmp_sess_open(struct snmp_session *session);

       struct snmp_session *snmp_sess_session(void *handle);

       int snmp_sess_send(void *handle, struct snmp_pdu *pdu);

       int snmp_sess_async_send(void *handle,
                                struct snmp_pdu *pdu,
                                snmp_callback callback,
                                void *callbackData);

       int snmp_sess_select_info(void *handle,
                                 int *numfds, fd_set *fdset,
                                 struct timeval *timeout,
                                 int *block);

       int snmp_sess_read(void *handle, fd_set *fdset);

       void snmp_sess_timeout(void *handle);

       int snmp_sess_synch_response ( void *handle,
              netsnmp_pdu *pdu,
              netsnmp_pdu **response);

       int snmp_sess_close(void *handle);

       void snmp_sess_error(void *handle, int *pcliberr,
                           int *psnmperr, char **pperrstring);

DESCRIPTION

       These  functions  define  a subset of the API that can be used to manage single SNMP sessions in a multi-
       threaded application.  Except for snmp_sess_session(), these functions are single session versions of the
       traditional SNMP library API.

       Note  that  these  functions  use an opaque pointer (handle in the above prototypes) to identify a single
       session in lieu of a session pointer (as in the traditional API).

       snmp_sess_init() prepares a  struct  snmp_session  that  sources  transport  characteristics  and  common
       information  that  will  be  used  for  a  set  of  SNMP transactions.  After this structure is passed to
       snmp_sess_open() to create an SNMP session, the structure is no longer used.  Instead the opaque  pointer
       returned by snmp_sess_open() is used to refer to that session henceforth.

       SNMP  sessions  that  are created with snmp_sess_open() are not affected by, and SHOULD NOT BE USED WITH,
       snmp_select_info(), snmp_read(), snmp_timeout() nor snmp_close().  Rather the equivalent  single  session
       functions described here should be used.

       snmp_sess_init() and snmp_sess_open() each take as input a pointer to a struct snmp_session object.  This
       structure  contains  information  for  a  set  of  transactions  that  will   share   similar   transport
       characteristics.   snmp_sess_session()  takes  the  opaque  session  handle  and returns a pointer to its
       associated struct snmp_session.

       snmp_sess_send() and snmp_sess_async_send() each take a pdu parameter, which points to a struct  snmp_pdu
       object containing information that describes a transaction that will be performed over an open session.

       Consult snmp_api.h for the definitions of these structures.

       With the snmp_sess_async_send() call, snmp_sess_read will invoke the specified callback when the response
       is received.

       snmp_sess_select_info(), snmp_sess_read() and snmp_sess_timeout() provide an interface for the use of the
       select(2) system call so that SNMP transactions for a single session can occur asynchronously.

       snmp_sess_select_info() is passed the information that would have been passed to select(2) in the absence
       of SNMP.  For example, this might include file descriptors associated with the main loop of  a  graphical
       application.  This information is modified so that SNMP will get the service it requires from the call to
       select(2).  In this case, numfds, fdset and timeout correspond to the nfds, readfds and timeout arguments
       to  select(2)  respectively.   The  only exception is that timeout must ALWAYS point to an allocated (but
       perhaps uninitialized) struct timeval (it cannot be NULL as for select(2)).  If timeout would  have  been
       passed  as  NULL,  block  is  instead  set  to true, and timeout is treated as undefined.  This same rule
       applies upon return from snmp_select_info().

       After calling snmp_sess_select_info() , select(2) should be called  with  the  returned  data.   When  it
       returns,  snmp_sess_read() should then be called with the fd_set returned from select(2).  This will read
       any input from this session's  SNMP  socket.   If  select(2)  times  out  (that  is,  it  returns  zero),
       snmp_sess_timeout() should be called to see if a timeout has occurred on the SNMP session.

       snmp_sess_synch_response  is  a convenience routine that will send the request, wait for the response and
       process it before returning.  See the descriptions of snmp_sess_send ,  snmp_sess_read etc for details.

DIAGNOSTICS

       Error return status from snmp_sess_open() is indicated by return of a NULL pointer.  Error return  status
       from  snmp_sess_close()  and  snmp_sess_send()  is indicated by a return value of 0.  A successful status
       will return 1.

       Further information can be obtained by using snmp_sess_error() to see what type of  error  has  occurred.
       This  function returns the SNMP snmp_errno variable, the value of the system errno variable, and a string
       interpretation of both variables.  The string must be freed after use by the caller.

       For errors  returned  by  snmp_sess_open(),  use  the  corresponding  function  snmp_error()  instead  of
       snmp_sess_error().

       Consult  snmp_api.h  for  the  complete  set  of SNMP library error values.  The SNMP library error value
       snmperr can be one of the following values:

         SNMPERR_GENERR           A generic error occurred.

         SNMPERR_BAD_LOCPORT      The local port was bad because it had already been allocated or permission was
                                  denied.

         SNMPERR_BAD_ADDRESS      The host name or address given was not useable.

         SNMPERR_BAD_SESSION      The specified session was not open.

         SNMPERR_TOO_LONG

         SNMPERR_NO_SOCKET

         SNMPERR_V2_IN_V1

         SNMPERR_V1_IN_V2

         SNMPERR_BAD_REPEATERS

         SNMPERR_BAD_REPETITIONS

         SNMPERR_BAD_ASN1_BUILD

         SNMPERR_BAD_SENDTO

         SNMPERR_BAD_RCVFROM

         SNMPERR_BAD_PARSE

         SNMPERR_BAD_VERSION

         SNMPERR_BAD_COMMUNITY

         SNMPERR_NOAUTH_DESPRIV

         SNMPERR_ABORT

         SNMPERR_UNKNOWN_PDU

         SNMPERR_TIMEOUT

SEE ALSO

       select(2),   netsnmp_session_api(3),   netsnmp_pdu_api(3),   netsnmp_varbind_api(3),  netsnmp_mib_api(3),
       snmp_api.h