NAME

       sk_new_session - create a new SNMPSESSION

SYNOPSIS

       #include <snmpkit.h>

       SNMPSESSION  *sk_new_session(char  *host,  void *(start_routine)(SNMPSESSION*), const char
       *community);

       SNMPSESSION     **sk_new_sessions(char      *hostspec,const      char      *community,void
       *(start_routine)(SNMPSESSION*));

       SNMPSESSION   **sk_new_sessions_multi(char   **hostspecs,   const  char  *community,  void
       *(start_routine)(SNMPSESSION*));

DESCRIPTION

       An SNMP_session instance is an object that handles the details of  communicating  an  SNMP
       enabled device such as a printer or a router.

       There  are three versions of sk_new_sessions. They two of the parmeters are identical. The
       first one varies between the different versions of the function.

       A SNMP community string acts as a password.  Normally there are two  strings  set  for  an
       SNMP  enabled  device.  One will allow the user write access to settings via SNMP commands
       and the second password will only allow for read access to device settings.

       You must also provide a pointer to the start_routine function.  The start_routine() is the
       function  used  to actually do the work of communicating with the network device. In other
       words, this function is  called  when  the  thread  handling  this  particular  device  is
       activated.  In  other  words,  this  function  actually loads up the packets with the SNMP
       objects and then makes the requsts. Each SNMPSESSION has  its  own  thread  and  once  the
       thread  is  created.  When  the  start_function  function  is  called,  it  is  passed the
       SNMPSESSION pointer as a paramter.

       The first parameter varies between the functions. In the  case  of  sk_new_session  it  is
       simply   a   hostname  in  a  format  understood  by  gethostbyname(3).  In  the  case  of
       sk_new_sessions, instead of a simple hostname a hostspec is passed in. A hostspec can be a
       simple  hostname but it can also be an IP address range in the form of 192.168.0.1-5 or an
       IP address  and  a  subnet  mask  in  the  form  of  either  192.168.0.0/255.255.255.0  or
       192.168.0.0/24.  A  hostspec  may  also  include  a  community  name  by enclosing that in
       parenthesis like 192.168.0.1(public).

RETURN VALUE

       Upon  successful  completion  sk_new_session  returns  a   pointer   to   a   SNMPSESSION.
       sk_new_sessions   and  sk_new_sessions_multi  both  return  a  null  terminated  array  of
       SNMPSESSION pointers. Otherwise NULL is returned and  sk_errno  is  set  to  indicate  the
       error.

ERRORS

       SK_MEM_FAIL
              Memory allocation failed.

       SK_BAD_PROTO
              UDP protocol is not supported. See getprotobyname(3).

       SK_SOCKET_FAIL
              Can't create socket. See socket(2).

       SK_RECEIVER_FAIL
              Can't create a thread to receive packets. Sets errno. See pthread_create(3).

       SK_HOSTNOTFOUND
              Host not found. Sets h_errno. See gethostbyname(3).

       SK_REAPER_FAIL
              Can't create a thread to reap spent threads. Sets errno. See pthread_create(3).

       SK_WORKER_FAIL
              Can't create worker thread. Sets errno. See pthread_create(3).

       SK_UNTERM_HOSPEC
              Community in hostspec doesn't have ending parenthesis.

       SK_OCTET_OVERFLOW
              One of the octets in hostspec is greater than 255.

       SK_BAD_NETMASK
              Subnet mask wasn't in a understood form.

       SK_NETMASK_OVERFLOW
              Number of bits in subnet mask is too large.

       SK_DIS_NETMASK
              Subnet mask had discontinious bits.

SEE ALSO

       sk_strerror(3), sk_snmpsessions_done(3), sk_new_sfiller(3), sk_new_snmptable(3)