.TH SNMP_session 3 "November 2000" "GNU snmpkit 0.4"
.SH NAME
SNMP_session \- C++ object for specifying an SNMP Agent which
can then be the managed via SNMP set, get, and get_next calls
.SH SYNOPSIS
.B #include <snmpkit>
.sp
.B SNMP_session::SNMP_session (const string &host,void *(*start_routine)\
(SNMP_session*), const string &community="public")
.sp
.B list<SNMP_session*> &SNMP_sessions(list<SNMP_session*> &dest,\
string &hostspec,void *(*start_routine)(SNMP_session*),\
const string &community="public");
.sp
.B list<SNMP_session*> &SNMP_sessions(list<SNMP_session*> &dest,\
list<string> &hostspecs,void *(*start_routine)(SNMP_session*),\
const string &community="public");
.sp
.B SNMP_session::~SNMP_session();
.sp
.B static void SNMP_session::end();
.sp
.B OidSeq *SNMP_session::get(OidSeq *oids);
.sp
.B OidSeq *SNMP_session::get_next(OidSeq *oids);
.sp
.B OidSeq *SNMP_session::set(OidSeq *oids);
.sp
.B char *SNMP_session::ConnHost();
.sp
.B const string &SNMP_session::Hostname();
.sp
.B void SNMP_session::setDebug();
.sp
.B void SNMP_session::write_debug(const string &dirstr, BerSequence *packet);
.sp
.B void SNMP_session::write_debug_bin(const basic_string<unsigned char> &str);
.sp
.B void SNMP_session::printstr(unsigned long *argflags,char need_newline,\
char *str, char ck_name_flag);
.sp
.B int SNMP_sessions_done();
.sp
.SH "DESCRIPTION"
An \fBSNMP_session\fP instance is an object that handles the details
of communicating an SNMP enabled device such as a printer or a
router.
.sp
.SS SNMP_session::SNMP_session (const string &host,void *(*start_routine)\
(SNMP_session*), const string &community);
In order to create a new SNMP_session, you should know the address 
of the host or hosts with which you wish to communicate.  This 
parameter can take the form of an IP address or a hostname.
.sp
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.
.sp
Finally, you should also provide a SNMP community string (although 
a default one will be used if you do not supply one).  This 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.
.sp
.BI Exceptions
.sp
* SocketNoUDPException \- unable to obtain a protoent (\fBSee getprotbyname(3)\fP)
structure for the "UDP" protocol.
.sp
* SocketCreateFailException \- unable to create a socket for use by 
the SNMP_session. (\fBSee socket(2)\fP).
.sp
* ReceiverCreateException \- unable to create the listening thread in order
to receive responses to issued SNMP queries.(\fBSee pthread_create(3)\fP).
.sp
* SessionHostNotFoundException \- unable to create the hostent 
struct; normally caused by a \fBgethostbyname(3)\fP call on the host
argument to the SNMP_session() constructor.
.sp
* JoinerCreateException \- new thread creation
failed. (\fBSee pthread_create(3)\fP).
.sp
* SessionWorkerCreateException \- worker thread creation
failed. (\fBSee pthread_create(3)\fP).
.sp
.SS  list<SNMP_session*> &SNMP_sessions(list<SNMP_session*> &dest,\
string &hostspec,void *(*start_routine)(SNMP_session*),\
const string &community="public");
This  function is not really a part of the class but its sole purpose
is to repeatedly call the session constructor. This function is
simply a quick way to create lots of sessions all at once. In addition 
to being able to pass a simple hostname or IP address, you can pass a
host specification. This can have several forms:
.sp
* Simple address: 192.168.0.1
.sp
* Simple hostname: foobar
.sp
* IP address range: 192.168.0.1-52
.sp
* Network and subnet mask: 192.168.0.0/255.255.255.0
.sp
* Network and bits in subnet mask: 192.168.0.0/24
.sp
In addition the a community name can be appeneded to the hostpsec by
surrounding it with parenthesis. e.g. 192.168.0.5-18(private)
.sp
.BI Exceptions
.sp
Same as SNMP_session::SNMP_session() with the addition of
.sp
* SessionCommunityException \- Can't find the closing parenthesis on
the community name.
.sp
* SessionOctetOverflowException \- One of the octets in subnet mask is 
greater than 255.
.sp
* SessionBadSubnetException \- The subnet mask doesn't make sense.
.sp
* SessionNetbitsOverflowException \- The number of bits in the netbits 
is greater than 31.
.sp
* SessionBadNetmaskException \-  The overall netmask specification
wasn't deciferable.
.sp
.SS list<SNMP_session*> &SNMP_sessions(list<SNMP_session*> &dest,\
list<string> &hostspecs,void *(*start_routine)(SNMP_session*),\
const string &community);
.sp
See SNMP_sessions(list<SNMP_session*> &dest,string &hostspec,\
void *(*start_routine)(SNMP_session*),const string &community);
.sp
This function is not really part of the class but its sole purpose is
to repeatedly call the constructor. This function is simply a quick
way to create lots of sessions all at once. It is virtually identical
to the other SNMP_sessions function with the exception that instead of 
taking one string as a hostspec it takes a list of hostspec strings.
.sp
.BI Exceptions
.sp
Same as SNMP_sessions(list<SNMP_session*> &dest,string &hostspec,\
void *(*start_routine)(SNMP_session*),const string &community).
.sp
.SS SNMP_session::~SNMP_session();
SNMP_session object destructor.
.SS "OidSeq *SNMP_session::__get(OidSeq *oids)"
Method to read information from an SNMP device. This function is
primarily called by the \fBSee SNMP_structFiller(3)\fP class. It is
designed to be called by the other functions in the library and is not
generally considered an exported interface to the SNMPkit library.
.sp
.BI Exceptions
.sp
* SNMPPacketNotSequenceException \- The response received was not 
a valid SNMP response. 
.sp
* SNMPRespNotSequenceException \- The packet received was a valid SNMP
response but the structure of the SNMP response was incorrect.
.sp
* SNMPNotResponseTagException \- The type of the SNMP response received
was incorrect (not 0xa2).
.sp
* SNMPSeqnoNotIntException \- The sequence number of the response was
not a classified as a number.
.sp
* SNMPStateNotIntException \- The SNMP device sent back an improperly
constructed response packet and the status was not classified as an
integer.
.sp
* SNMPFaultOidNotIntException \- A response was returned with an error 
but the index to the problem object identifier was not classified as
an integer.
.sp
* OidSeqBadLayoutException \-  Within a SNMP packet there is a
substructure which is an OID sequence. If the packet was supposed to
have an OID sequence in a particular locaion but for some reason one
of the elements was not of the correct type, then this exception will
be thrown.
.sp
* SNMPBadOidException \- An OID in the SNMP response packet was invalid.
.sp
* SocketSendShortExecption \- An error occurred while sending the SNMP
request resulting in an incomplete transmission of the query.
.sp
* BerSequenceTagException, BerIntTagException, BerStringTagException,
BerNullTagException, BerOidTagException, BerTimeTickTagException,
BerCounterTagException \- These exceptions are internal exceptions
which are caused by trying to interpret a piece of as one type when in 
fact it is another type. These are almost always called as a result of 
a bug in the SNMPkit library.
.sp
* BerLengthException, BerIntLengthExecption, BerTimeTickLengthgExceptioin, 
BerCounterLengthExecption, BerNullLengthExecption, 
BerIPAddrLengthExecption \- The size of the data to be encoded 
(BER) will not fit into an unsigned long data type.
.sp
.SS "OidSeq *SNMP_session::__get_next(OidSeq *oids);"
Get the next item following the one pointed to by the OID sequence
passed into the function.  This function is primarily called by the
\fBSee SNMP_structFiller(3)\fP class. It is designed to be called by the
other functions in the library and is not
generally considered an exported interface to the SNMPkit library.
.sp
.B Exceptions
.sp
Same as the \fBSNMP_session::__get()\fP method.
.sp
.SS "OidSeq *SNMP_session::__set(OidSeq *oids)"
This method will write the values inserted into the OidSeq into
the the SNMP agent. It is almost the opposite of __get which takes an
OID and gets the value from the SNMP agent. This function is
primarily called by the \fBSee SNMP_structFiller(3)\fP class. It is designed
to be called by the other functions in the library and is not
generally considered an exported interface to the SNMPkit library.
.sp
.B Exceptions
.sp
Same as the \fBSNMP_session::__get()\fP method.
.sp
.SS "void SNMP_session::setDebug()"
Enable the logging of debug information from the SNMP_session instance.
This method must be called before attempting to write any debug data using
the write_debug() method.
.sp
.BI Exceptions
.sp
* DebugFileStatException \- An unexpected error occurred when attempting
to locate the appropriate debug log ("snmplog*"); this will occur when a stat
of the debug log file returns an error other than ENOENT.
.sp
* DebugFileOpenException \- An error occurred when attempting to open
the process debug log.
.sp
.SS "void SNMP_session::__write_debug(const string &dirstr, 
BerSequence *packet);"
Write the SNMP packet information to a log file in order to
aid in debugging errors.
.sp
.SS "void SNMP_session::__write_debug_bin(const basic_string<unsigned char> 
&str);"
Write binary debugging information to the log files dumping it in hex format.
.sp
.SS "void SNMP_session::printstr(unsigned long *argflags,char need_newline,
char *str, char ck_name_flag);"
Enables the SNMP_session object to synchronize the logging of information
among its various threads.
.sp
.SS "char *SNMP_Session::ConnHost();"
Method to obtain the network address of the current 
SNMP session.  Note that the returned string is in network
byte order.
.sp
.SS "constr string &SNMP_session::Hostname();"
Method to obtain the hostname string used when creating the SNMP_session
instance
.SS "void SNMP_session::end();"
Method for appending a final newline (if necessary) to standard output.
.sp
.SS "int SNMP_sessions_done();"
There is a thread that demultiplexes the packets coming in on the
socket as well as a thread which recycles threads to keep the
utilization of the system resources reasonable. Call this function
after all the sessions are created to wait for all the threads to
complete and clean up all the misc. resources which are being used by
the library.
.SH "RETURN VALUE"
.TP
.B "OidSeq *SNMP_session::__get();"
.sp
Pointer to an OidSeq object containing the response to the SNMP get request.
.TP
.B "OidSeq *SNMP_session::__get_next();"
.sp
Pointer to an OidSeq object containing the response to the SNMP get_next request.
.TP
.B "OidSeq *SNMP_session::__set();"
.sp
Pointer to an OidSeq object containing the response to the SNMP set request
.sp
.TP
.B "int SNMP_sessions_done();"
.sp
The maximum error returned by any of the threads when they complete.
.TP
.B "list<SNMP_session*> &SNMP_sessions();"
.sp 
Returns the list passed into it with any sessions that were created
appended to the end of the list.
.SH EXAMPLE
.nf
.B #include <snmpkit>
.B #include <string.h>
.B #include <iostream.h>
.sp
static const char SYSDESC[]="1.3.6.1.2.1.1.1.0";
.sp
struct PrinterInfo{
  char *sysDesc;
};
.sp
void printer_info_insert_sysDesc(void *dest_ptr,const char *str){
  PrinterInfo *dest=reinterpret_cast<PrinterInfo*>(dest_ptr);
  dest->sysDesc=strdup(str);
}
.sp
void *do_req(SNMP_session *printer){
  PrinterInfo prinfo;
  cerr << printer->Hostname() << endl << flush;
  printer->setDebug();
  SNMP_structFiller table(*printer);
  table.append_string(SYSDESC,printer_info_insert_sysDesc);
  table.get(&prinfo);
  cout << printer->Hostname() << ' ' << prinfo.sysDesc << endl;
  return NULL;
}
.sp
int main(int argc,char **argv){
  set_snmpsock_props(1,3);
  list<SNMP_session*> sessions;
  string hostspec(argv[1]);
  SNMP_sessions(sessions,hostspec,do_req);
  SNMP_sessions_done();
  exit(1);
}  
.fi
.SH "SEE ALSO"
SNMP_structFiller(3), SNMP_table(3)
.sp
.SH AUTHOR
The SNMPkit C/C++ library was originally developed by Ben Woodard
<ben@users.sourceforge.net>. This man page was written by Gerald
Carter <gcarter@valinux.com>.