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)

GNU snmpkit 0.4                                   November 2000                                SK_NEW_SESSION(3)