bionic (3) SNMP_structFiller.3.gz

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>