SNMPSESSAPI(3) Net-SNMP SNMPSESSAPI(3)

NAME
       snmpsessinit,   snmpsessopen,   snmpsesssession,  snmpsesssend,
       snmpsessasyncsend,      snmpsessselectinfo,       snmpsessread,
       snmpsesstimeout, snmpsessclose, snmpsesserror - session functions

SYNOPSIS
       ##iinncclluuddee <>

       vvooiidd ssnnmmppsseessssiinniitt((ssttrruucctt ssnnmmppsseessssiioonn **session));;

       vvooiidd **ssnnmmppsseessssooppeenn((ssttrruucctt ssnnmmppsseessssiioonn **session));;

       ssttrruucctt ssnnmmppsseessssiioonn **ssnnmmppsseesssssseessssiioonn((vvooiidd **handle));;

       iinntt ssnnmmppsseesssssseenndd((vvooiidd **handle,, ssttrruucctt ssnnmmppppdduu **pdu));;

       iinntt ssnnmmppsseessssaassyynnccsseenndd((vvooiidd **handle,,
                                ssttrruucctt ssnnmmppppdduu **pdu,,
                                ssnnmmppccaallllbbaacckk callback,,
                                vvooiidd **callbackData));;

       iinntt ssnnmmppsseesssssseelleeccttiinnffoo((vvooiidd **handle,,
                                 iinntt **numfds,, ffddsseett **fdset,,
                                 ssttrruucctt ttiimmeevvaall **timeout,,
                                 iinntt **block));;

       vvooiidd ssnnmmppsseessssrreeaadd((vvooiidd **handle,, ffddsseett **fdset));;

       vvooiidd ssnnmmppsseessssttiimmeeoouutt((vvooiidd **handle));;

       iinntt ssnnmmppsseesssscclloossee((vvooiidd **handle));;

       vvooiidd ssnnmmppsseesssseerrrroorr((vvooiidd **handle,, iinntt **pcliberr,,
                           iinntt **psnmperr,, cchhaarr ****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
       ssnnmmppsseesssssseessssiioonn(()), 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).

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

       SNMP sessions that are created with ssnnmmppsseessssooppeenn(()) are  not  affected
       by,  and  SHOULD  NOT  BE  USED  WITH, ssnnmmppsseelleeccttiinnffoo(()), ssnnmmpprreeaadd(()),
       ssnnmmppttiimmeeoouutt(()) nor ssnnmmppcclloossee(()).  Rather the equivalent single  session
       functions described here should be used.

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

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

       Consult snmpapi.h for the definitions of these structures.

       ssnnmmppsseesssssseelleeccttiinnffoo(()),  ssnnmmppsseessssrreeaadd(()) and ssnnmmppsseessssttiimmeeoouutt(()) pro-
       vide an interface for the use of the sseelleecctt(2) system call so that SNMP
       transactions for a single session can occur asynchronously.

       ssnnmmppsseesssssseelleeccttiinnffoo(())  is passed the information that would have been
       passed to sseelleecctt(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 sseelleecctt(2).  In this case, numfds,
       fdset and timeout correspond to the nfds, readfds and timeout arguments
       to  sseelleecctt(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  sseelleecctt(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 ssnnmmppsseelleeccttiinnffoo(()).

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

DIAGNOSTICS       Error  return  status from ssnnmmppsseessssooppeenn(()) is indicated by return of a
       NULL  pointer.   Error  return  status   from   ssnnmmppsseesssscclloossee(())   and
       ssnnmmppsseesssssseenndd(())  is  indicated  by  a return value of 0.  A successful
       status will return 1.

       Further information can be obtained by using ssnnmmppsseesssseerrrroorr(())  to  see
       what  type  of  error  has  occurred.   This  function returns the SNMP
       snmperrno 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 ssnnmmppsseessssooppeenn(()), use the corresponding function
       ssnnmmppeerrrroorr(()) instead of ssnnmmppsseesssseerrrroorr(()).

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

         SNMPERRGENERR           A generic error occurred.

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

         SNMPERRBADADDRESS      The  host name or address given was not use-
                                  able.

         SNMPERRBADSESSION      The specified session was not open.

         SNMPERRTOOLONG

         SNMPERRNOSOCKET

         SNMPERRV2INV1

         SNMPERRV1INV2

         SNMPERRBADREPEATERS

         SNMPERRBADREPETITIONS

         SNMPERRBADASN1BUILD

         SNMPERRBADSENDTO

         SNMPERRBADRCVFROM

         SNMPERRBADPARSE

         SNMPERRBADVERSION

         SNMPERRBADCOMMUNITY

         SNMPERRNOAUTHDESPRIV

         SNMPERRABORT

         SNMPERRUNKNOWNPDU

         SNMPERRTIMEOUT


SEE ALSO
       sseelleecctt(2), ssnnmmppaappii(3), ssnnmmppaappii..hh



4.2 Berkeley Distribution         07 Mar 2002                 SNMPSESSAPI(3)