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)