NAME

       SNMP_structFiller - C++ object to contain data for SNMP queries

SYNOPSIS

       #include <snmpkit>

       SNMP_structFiller::SNMP_structFiller(SNMP_session &sess);

       SNMP_structFiller::~SNMP_structFiller();

       void SNMP_structFiller::append_int(const string &oidstr,void (*fp)(void*,long));

       void SNMP_structFiller::append_counter(const string &oidstr, void (*fp)(void*,long));

       void  SNMP_structFiller::append_timetick(const  string  &oidstr, void (*fp)(void*,unsigned
       long));

       void  SNMP_structFiller::append_ipaddr(const  string   &oidstr,   void   (*fp)(void*,const
       unsigned char *));

       void  SNMP_structFiller::append_string(const  string  &oidstr, void (*fp)(void*,const char
       *));

       void SNMP_structFiller::remove(const string &oidstr);

       void *SNMP_structFiller::get(void *tobefilled);

       void *SNMP_structFiller::get_next(void *tobefilled);

DESCRIPTION

       A SNMP_structFiller object takes a list of SNMP objects and  queries  the  SNMP_session(3)
       and fills in the structure based upon that information.

       The  SNMP  protocol is designed in a way where there is significant overhead in process of
       encoding and exchanging a packet. Therefore it is very inefficient and time  consuming  to
       exchange many variables in individual request packets. The way around this is to bulk up a
       bunch of SNMP requests into one  packet.  Since  it  is  most  likely  that  you  will  be
       frequently  fetching  information  which  is related, the SNMP_structFiller is designed to
       associate the SNMP objects and data types with the offsets into the  structure.  That  way
       when you do a get or a get_next you will get back a completely filled in structure.

   SNMP_structFiller::SNMP_structFiller(SNMP_session);
       You  will  need  to create a new SNMP_structFiller instance for each different set of SNMP
       objects you wish to fetch.  The SNMP data structure  is  initially  empty.   You  can  add
       request information via the SNMP_structFiller::append() method.

   ~SNMP_structFiller::~SNMP_structFiller();
       Destructor for an SNMP_structFiller object

   void SNMP_structFiller::append_int(const string &oidstr,void (*fp)(void*,long));
   void SNMP_structFiller::append_counter (const string &oidstr, void (*fp)(void*,long));
   void  SNMP_structFiller::append_timetick  (const  string  &oidstr,  void  (*fp)(void*,unsigned
       long));
   void SNMP_structFiller::append_ipaddr (const string &oidstr, void  (*fp)(void*,const  unsigned
       char *));
   void SNMP_structFilleri::append_string(const string &oidstr, void (*fp)(void*,const char *));
       All  of  the various append methods add an SNMP object to the end of the SNMP_structFiller
       instance.  Each method requires the OID of the SNMP object to add and a function that will
       insert it into the associated structure.

       This  library  does  not attempt to read MIBs. This means that youwill need to look up the
       OID string before hand and hard code the OIDstring into your program.

       The job of the function pointer is to insert whatever data it gets back into the the  data
       structure. This allows you to do any kind of munging around you want with the data you get
       and therefore you can have much more complicated receiving  structure.   See  the  example
       programs  included  with  the  SNMPkit documentation (snmptest*.C) for examples of various
       uses of this.

       Exceptions

       * BerOidBadSubOidException - One of the OIDs could not be converted to a number.

       * BerNoOidsException - No OIDs were specified.

   void SNMP_structFiller::remove(const string &oidstr);
       Delete an SNMP object from the SNMP_structFiller instance.

       Exceptions

       *  FillerRemoveEmptyException  -  An  attempt  was  made   to   remove   from   an   empty
       SNMP_structFiller object; results from a programming error.

       *  FillerRemoveNotFoundException  - An attempt was made to remove an item not currently in
       the container; results from a programming error.

       * FillerCorruptException - The SNMP table entry was successfully removed, however the  OID
       sequence was NULL; results from a programming error in the library.

       *  OidSeqRemoveNotFoundException  -  A programming error resulted in the attempt to remove
       something that was not there.

       * OidSeqBadLayoutException - The BER  sequence  did  not  follow  the  layout  of  an  OID
       sequence.

   void *SNMP_structFiller::get(void *tobefilled);
       Send  the  SNMP  get  request to the SNMP Agent and fill the structure tobefilled with the
       data returned using the previously defined inserter functions.

       Exceptions

       * SNMPNoResponseException - The SNMP_structFiller object did not receive a  response  from
       the remote SNMP Agent. This can be caused by many things, no agent running on destination,
       a firewall between you and the destination.

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

       * SNMPRespNotSequenceException - The packet received was a valid  SNMP  response  but  the
       payload of the packet wasn't a sequence type.

       *  SNMPNotResponseTagException  -  The type of the SNMP response received was invalid (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 OID 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,       BerCounterTagException,
       BerStringTagException, BerNullTagException, BerOidTagException, BerTimeTickTagException  -
       Although  this  will  result  from  a encoding error, it is caused by calling a BER object
       constructor on an invalid piece of data.

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

   void *SNMP_structFiller::get_next(void *tobefilled);
       Query the object which is next in the list of available objects from the SNMP Agent.

       Exceptions

       Same as the SNMP_structFiller::get() method

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>