SNMP_session(3)

📦 version 0.9, in ubuntu jammy

💖 SNMP_session — like, the manual page, bestie 💖

okay so this is SNMP_session(3) from the Library Functions Manual and honestly? it's giving "the entire personality of SNMPkit in one class." buckle up 🎀

✨ NAME ✨

SNMP_session — a 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 ✨

so an SNMP_session instance is, like, the object that handles all the details of communicating an SNMP enabled device. think a printer, think a router, think your fave network appliance that's lowkey just vibing on the LAN. 🦋

🌸 SNMP_session::SNMP_session (const string &host,void (start_routine)(SNMP_session*), const string &community); 🌸

bestie, to create a new SNMP_session you gotta know the address of the host (or hosts, plural, we contain multitudes) you wish to communicate with. this parameter can take the form of an IP address or a hostname. easy. 💅

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 (yes, another other words, they're committed to the bit), this function actually loads up the packets with the SNMP objects and then makes the requsts. ✨

and finally — bestie, don't forget this one — 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. 🔐 so like, one of them has main character energy and the other is read-only. periodt.

💀 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"); 🌈

okay so this function is not really a part of the class, but its sole purpose is to repeatedly call the session constructor. it's literally just a quick way to create lots of sessions all at once, no cap. 👑

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. it's 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. so like, it's the same vibe but in bulk. obsessed. 💖

💀 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. it's the goodbye. it's the closing credits. it's the "and scene." 💅

🌸 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. iykyk 🫶

💀 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. the duality of man, honestly. 😭

💀 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. like, before. not after. before. bestie. 🙈

💀 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. team effort, honestly. 🫶

🌈 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. the little finishing touch. the ribbon on the present. 💖

👑 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. 🧹✨

still going, bestie — this page is long and there's more where that came from 💅

💖 RETURN VALUE 💖

okay bestie, here's the tea on what each of these hands back to you 🫶

  • OidSeq *SNMP_session::__get(); — this one gives you a pointer to an OidSeq object, and that object is holding the response to the SNMP get request. like, that's literally its whole job 💅
  • OidSeq *SNMP_session::__get_next(); — same energy, pointer to an OidSeq object, except this one's carrying the response to the SNMP get_next request ✨
  • OidSeq *SNMP_session::__set(); — yep, pointer to an OidSeq object again, and it's holding the response to the SNMP set request 👑
  • int SNMP_sessions_done(); — this returns the maximum error returned by any of the threads when they complete. so like, if one of them was being dramatic, this is where you find out 😭
  • list<SNMP_session*> &SNMP_sessions(); — returns the list that you passed into it, but with any sessions that were created appended to the end of the list. it's giving "here's your list back, plus some friends" 🎀

🌈 EXAMPLE 🌈

no cap, this is the whole thing, character for character, because I would never do you like that 🙈

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

like, look at it go 🦋 the callback do_req gets a session, prints the hostname, turns debug on with setDebug(), fills a struct with SNMP_structFiller, grabs SYSDESC, prints the hostname plus the sysDesc, and returns NULL. then main sets the socket props with set_snmpsock_props(1,3), makes a list<SNMP_session*>, builds a string hostspec from argv[1], calls SNMP_sessions(sessions,hostspec,do_req), calls SNMP_sessions_done(), and exits with 1. iconic, truly ✨

🌸 SEE ALSO 🌸

go read these next, bestie, they're the whole friend group:

🎀 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>. absolute legends, we love them, no notes 💜

and that's the whole page bestie!! this one's from GNU snmpkit 0.4, dated November 2000, and it's SNMP_session(3) — go forth and query responsibly 💅⭐

📦 where this page comes from