Provided by: libsnmpkit-dev_0.9-16build1_amd64 bug

NAME

       SNMP_session  -  C++ object for specifying an SNMP Agent which can then be the managed via
       SNMP set, get, and get_next calls

SYNOPSIS

       #include <snmpkit>

       SNMP_session::SNMP_session  (const  string  &host,void   *(*start_routine)(SNMP_session*),
       const string &community="public")

       list<SNMP_session*>    &SNMP_sessions(list<SNMP_session*>    &dest,string   &hostspec,void
       *(*start_routine)(SNMP_session*),const string &community="public");

       list<SNMP_session*> &SNMP_sessions(list<SNMP_session*> &dest,list<string>  &hostspecs,void
       *(*start_routine)(SNMP_session*),const string &community="public");

       SNMP_session::~SNMP_session();

       static void SNMP_session::end();

       OidSeq *SNMP_session::get(OidSeq *oids);

       OidSeq *SNMP_session::get_next(OidSeq *oids);

       OidSeq *SNMP_session::set(OidSeq *oids);

       char *SNMP_session::ConnHost();

       const string &SNMP_session::Hostname();

       void SNMP_session::setDebug();

       void SNMP_session::write_debug(const string &dirstr, BerSequence *packet);

       void SNMP_session::write_debug_bin(const basic_string<unsigned char> &str);

       void  SNMP_session::printstr(unsigned  long  *argflags,char  need_newline,char  *str, char
       ck_name_flag);

       int SNMP_sessions_done();

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.

   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.

       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.

       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.

       Exceptions

       * SocketNoUDPException - unable to obtain a protoent (See getprotbyname(3)) structure  for
       the "UDP" protocol.

       *  SocketCreateFailException - unable to create a socket for use by the SNMP_session. (See
       socket(2)).

       * ReceiverCreateException - unable to create the listening  thread  in  order  to  receive
       responses to issued SNMP queries.(See pthread_create(3)).

       * SessionHostNotFoundException - unable to create the hostent struct; normally caused by a
       gethostbyname(3) call on the host argument to the SNMP_session() constructor.

       * JoinerCreateException - new thread creation failed. (See pthread_create(3)).

       * SessionWorkerCreateException - worker thread creation failed. (See pthread_create(3)).

   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:

       * Simple address: 192.168.0.1

       * Simple hostname: foobar

       * IP address range: 192.168.0.1-52

       * Network and subnet mask: 192.168.0.0/255.255.255.0

       * Network and bits in subnet mask: 192.168.0.0/24

       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)

       Exceptions

       Same as SNMP_session::SNMP_session() with the addition of

       * SessionCommunityException - Can't find the closing parenthesis on the community name.

       * SessionOctetOverflowException - One of the octets in subnet mask is greater than 255.

       * SessionBadSubnetException - The subnet mask doesn't make sense.

       * SessionNetbitsOverflowException - The number of bits in the netbits is greater than 31.

       * SessionBadNetmaskException -  The overall netmask specification wasn't deciferable.

   list<SNMP_session*>   &SNMP_sessions(list<SNMP_session*>   &dest,list<string>  &hostspecs,void
       *(*start_routine)(SNMP_session*),const string &community);
       See         SNMP_sessions(list<SNMP_session*>         &dest,string          &hostspec,void
       *(*start_routine)(SNMP_session*),const string &community);

       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.

       Exceptions

       Same      as      SNMP_sessions(list<SNMP_session*>      &dest,string       &hostspec,void
       *(*start_routine)(SNMP_session*),const string &community).

   SNMP_session::~SNMP_session();
       SNMP_session object destructor.

   OidSeq *SNMP_session::__get(OidSeq *oids)
       Method  to  read information from an SNMP device. This function is primarily called by the
       See SNMP_structFiller(3) 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.

       Exceptions

       * SNMPPacketNotSequenceException - The response received was not a valid SNMP response.

       *  SNMPRespNotSequenceException  -  The  packet received was a valid SNMP response but the
       structure of the SNMP response was incorrect.

       * SNMPNotResponseTagException - The type of the SNMP response received was incorrect  (not
       0xa2).

       * SNMPSeqnoNotIntException - The sequence number of the response was not a classified as a
       number.

       * SNMPStateNotIntException - The SNMP device sent back an improperly constructed  response
       packet and the status was not classified as an integer.

       * SNMPFaultOidNotIntException - A response was returned with an error but the index to the
       problem object identifier was not classified as an integer.

       * 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.

       * SNMPBadOidException - An OID in the SNMP response packet was invalid.

       * SocketSendShortExecption - An error occurred while sending the SNMP request resulting in
       an incomplete transmission of the query.

       * 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.

       *      BerLengthException,      BerIntLengthExecption,       BerTimeTickLengthgExceptioin,
       BerCounterLengthExecption,  BerNullLengthExecption, BerIPAddrLengthExecption - The size of
       the data to be encoded (BER) will not fit into an unsigned long data type.

   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 See SNMP_structFiller(3) 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.

       Exceptions

       Same as the SNMP_session::__get() method.

   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 See SNMP_structFiller(3) 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.

       Exceptions

       Same as the SNMP_session::__get() method.

   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.

       Exceptions

       * 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.

       * DebugFileOpenException - An error occurred when attempting to  open  the  process  debug
       log.

   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.

   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.

   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.

   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.

   constr string &SNMP_session::Hostname();
       Method to obtain the hostname string used when creating the SNMP_session instance

   void SNMP_session::end();
       Method for appending a final newline (if necessary) to standard output.

   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.

RETURN VALUE

       OidSeq *SNMP_session::__get();

              Pointer to an OidSeq object containing the response to the SNMP get request.

       OidSeq *SNMP_session::__get_next();

              Pointer to an OidSeq object containing the response to the SNMP get_next request.

       OidSeq *SNMP_session::__set();

              Pointer to an OidSeq object containing the response to the SNMP set request

       int SNMP_sessions_done();

              The maximum error returned by any of the threads when they complete.

       list<SNMP_session*> &SNMP_sessions();

              Returns the list passed into it with any sessions that were created appended to the
              end of the list.

EXAMPLE

       #include <snmpkit>
       #include <string.h>
       #include <iostream.h>

       static const char SYSDESC[]="1.3.6.1.2.1.1.1.0";

       struct PrinterInfo{
         char *sysDesc;
       };

       void printer_info_insert_sysDesc(void *dest_ptr,const char *str){
         PrinterInfo *dest=reinterpret_cast<PrinterInfo*>(dest_ptr);
         dest->sysDesc=strdup(str);
       }

       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;
       }

       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);
       }

SEE ALSO

       SNMP_structFiller(3), SNMP_table(3)

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>.