SNMPpp  v0.0.3-20-7eeb228
Classes, methods, and functions to use net-snmp from C++
SNMPpp Namespace Reference

Classes

class  OID
 Wrapper for net-snmp's OID arrays. More...
 
class  PDU
 Wrapper for net-snmp's PDU structures. More...
 
class  Varlist
 Wrapper for net-snmp's snmp_variable_list pointer. More...
 

Typedefs

typedef std::map< SNMPpp::OID, netsnmp_variable_list * > MapOidVarList
 A std::map where the OID is the key and the value is a net-snmp variable list. This is used by SNMPpp::PDU and SNMPpp::Varlist. More...
 
typedef void * SessionHandle
 net-snmp uses a void * for the "Single API" opaque session pointer, but SNMPpp prefers to have an actual named type to make it more obvious when passing the session pointer by reference in C++. More...
 
typedef std::set< OIDSetOID
 A std::set of OIDs. More...
 
typedef std::vector< OIDVecOID
 A std::vector of OIDs. More...
 

Functions

long centisecondsNetSnmpUptime (void)
 Return the uptime in centiseconds. More...
 
long centisecondsPidStarted (pid_t pid=0)
 Return the uptime in centiseconds. More...
 
long centisecondsSince (const time_t t)
 Return the time since t. More...
 
long centisecondsUptime (void)
 Return the number of centiseconds since the last reboot. More...
 
void closeSession (SessionHandle &sessionHandle)
 Sessions must be closed when no longer needed. More...
 
SNMPpp::Varlist createV2TrapVarlist (const SNMPpp::OID &o, const long uptime=SNMPpp::centisecondsNetSnmpUptime())
 Initialize a varlist to be eventually used with one of the sendV2Trap() functions. More...
 
SNMPpp::PDU get (SNMPpp::SessionHandle &session, SNMPpp::PDU &pdu)
 Alias to SNMPpp::sync() for convenience, and to be consistent with the various other SNMPpp::get...() calls. More...
 
SNMPpp::PDU get (SNMPpp::SessionHandle &session, const SNMPpp::OID &o)
 Get a single OID. More...
 
SNMPpp::PDU get (SNMPpp::SessionHandle &session, const SetOID &oids)
 Get several specific OIDs at once. More...
 
SNMPpp::PDU getBulk (SNMPpp::SessionHandle &session, const SNMPpp::OID &o, const int maxRepetitions=50, const int nonRepeaters=0)
 Getbulk request, starting with the given OID. More...
 
SNMPpp::PDU getBulk (SNMPpp::SessionHandle &session, SNMPpp::PDU &pdu, const int maxRepetitions=50, const int nonRepeaters=0)
 Getbulk request, possibly with multiple starting points. More...
 
SNMPpp::PDU getNext (SNMPpp::SessionHandle &session, const SNMPpp::OID &o)
 Get the next OID. More...
 
SNMPpp::PDU getNext (SNMPpp::SessionHandle &session, SNMPpp::PDU &request)
 Get the next OID. More...
 
void initializeNetSnmpAgent (const std::string &name="snmppp")
 Initialize net-snmp AgentX. More...
 
void netsnmpDisableLogging (void)
 Disable net-snmp logging. More...
 
void netsnmpLogStdErr (const bool enabled=true)
 Toggle net-snmp logging to STDERR. More...
 
void netsnmpLogSyslog (const bool enabled=true)
 Toggle net-snmp logging to syslog. More...
 
void netsnmpLogToFile (const bool enabled=true, const std::string &filename="/var/log/netsnmp.log")
 Toggle net-snmp logging to an external file. More...
 
void openSession (SessionHandle &sessionHandle, const std::string &server="udp:127.0.0.1:161", const std::string &community="public", const int version=SNMP_VERSION_2c, const int retryAttempts=3)
 Open a net-snmp session and return a session handle. More...
 
void sendV2Trap (const SNMPpp::OID &o, const long uptime=SNMPpp::centisecondsNetSnmpUptime())
 Send a SNMPv2 trap to all configured trapsinks in net-snmp. More...
 
void sendV2Trap (SNMPpp::Varlist &varlist)
 Send a SNMPv2 trap to alll configured trapsinks in net-snmp. More...
 
void sendV2Trap (SNMPpp::PDU &pdu)
 Similar to SNMPpp::sendV2Trap( SNMPpp::Varlist &vl ). More...
 
void shutdownNetSnmpAgent (const std::string &name="snmppp")
 De-initialize net-snmp AgentX. More...
 
SNMPpp::PDU sync (SNMPpp::SessionHandle &session, SNMPpp::PDU &request)
 Send a PDU using the given SNMPpp::SessionHandle, and wait for a reply. More...
 
std::string version (void)
 Return the SNMPpp version number. More...
 

Typedef Documentation

◆ MapOidVarList

typedef std::map< SNMPpp::OID, netsnmp_variable_list *> SNMPpp::MapOidVarList

A std::map where the OID is the key and the value is a net-snmp variable list. This is used by SNMPpp::PDU and SNMPpp::Varlist.

◆ SessionHandle

typedef void* SNMPpp::SessionHandle

net-snmp uses a void * for the "Single API" opaque session pointer, but SNMPpp prefers to have an actual named type to make it more obvious when passing the session pointer by reference in C++.

For example, see the return value of snmp_sess_open();.

See also
SNMPpp::openSession();
SNMPpp::closeSession();

◆ SetOID

typedef std::set<OID> SNMPpp::SetOID

A std::set of OIDs.

◆ VecOID

typedef std::vector<OID> SNMPpp::VecOID

A std::vector of OIDs.

Function Documentation

◆ centisecondsNetSnmpUptime()

long SNMPpp::centisecondsNetSnmpUptime ( void  )

Return the uptime in centiseconds.

Note
On linux, this seems to be just a few centiseconds off from the last reboot, and it is unaffected by restarting snmpd. If you don't know which one of the SNMPpp::centiseconds...() call you need to use, this is most likely the safest and best choice.

The first variable in SNMPv2 traps is 'sysUpTime', which is defined as:

 "the time ... since the network management portion of the system was re-initialized"

But in all likelihood, this value isn't easily available from code which is using SNMPpp. So several other possibly useful values have been made available for convenience. Of those, centisecondsNetSnmpUptime() is most likely the value you need to use.

Todo:
What does netsnmp_get_agent_uptime(); return? I tried both get_uptime() and netsnmp_get_agent_uptime() but as far as I can tell the one called netsnmp_get_agent_uptime() returns garbage.
Returns
net-snmp's get_uptime(), which on linux seems to be the number of centiseconds since the system was rebooted.
Here is the caller graph for this function:

◆ centisecondsPidStarted()

long SNMPpp::centisecondsPidStarted ( pid_t  pid = 0)

Return the uptime in centiseconds.

Parameters
[in]pidIf set to zero then the current process ID will be queried by calling getpid().
Todo:
Not supported in Windows; returns centisecondsUptime() instead.
Returns
If the pid uptime is unavailable or cannot be found, then SNMPpp::centisecondsNetSnmpUptime() is returned instead.
If the pid uptime was determined, return the number of centiseconds (1/100s) since the given PID was started.
Here is the call graph for this function:

◆ centisecondsSince()

long SNMPpp::centisecondsSince ( const time_t  t)

Return the time since t.

Returns
the number of centiseconds (1/100s) that have elapsed since the given time. If the specified time is in the future, then zero is returned.
Here is the caller graph for this function:

◆ centisecondsUptime()

long SNMPpp::centisecondsUptime ( void  )

Return the number of centiseconds since the last reboot.

Todo:
In Windows, GetTickCount() wraps after 7 weeks. Look into using something else, such as GetTickCount64().
Here is the caller graph for this function:

◆ closeSession()

void SNMPpp::closeSession ( SNMPpp::SessionHandle sessionHandle)

Sessions must be closed when no longer needed.

This can be done by calling snmp_sess_close() directly, or SNMPpp::closeSession().

Here is the caller graph for this function:

◆ createV2TrapVarlist()

SNMPpp::Varlist SNMPpp::createV2TrapVarlist ( const SNMPpp::OID o,
const long  uptime = SNMPpp::centisecondsNetSnmpUptime() 
)

Initialize a varlist to be eventually used with one of the sendV2Trap() functions.

If you'd like to send a trap with multiple variables, you can use this method as a starting point to easily create a varlist with the first two OIDs filled in correctly. Once you finish adding variables to the varlist, call SNMPpp::sendV2Trap( SNMPpp::Varlist &vl ) to have the trap sent out.

Exceptions
std::invalid_argumentif the OID is empty.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ get() [1/3]

SNMPpp::PDU SNMPpp::get ( SNMPpp::SessionHandle session,
SNMPpp::PDU pdu 
)

Alias to SNMPpp::sync() for convenience, and to be consistent with the various other SNMPpp::get...() calls.

See also
SNMPpp::sync() to see additional exceptions this may throw.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ get() [2/3]

SNMPpp::PDU SNMPpp::get ( SNMPpp::SessionHandle session,
const SNMPpp::OID o 
)

Get a single OID.

Note
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Exceptions
std::invalid_argumentif the OID is empty.
Here is the call graph for this function:

◆ get() [3/3]

SNMPpp::PDU SNMPpp::get ( SNMPpp::SessionHandle session,
const SetOID oids 
)

Get several specific OIDs at once.

Note
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Exceptions
std::invalid_argumentif the SetOID is empty.
Here is the call graph for this function:

◆ getBulk() [1/2]

SNMPpp::PDU SNMPpp::getBulk ( SNMPpp::SessionHandle session,
const SNMPpp::OID o,
const int  maxRepetitions = 50,
const int  nonRepeaters = 0 
)

Getbulk request, starting with the given OID.

Note
  • Getbulk requests require SNMPv2 or higher on the server.
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getBulk() [2/2]

SNMPpp::PDU SNMPpp::getBulk ( SNMPpp::SessionHandle session,
SNMPpp::PDU pdu,
const int  maxRepetitions = 50,
const int  nonRepeaters = 0 
)

Getbulk request, possibly with multiple starting points.

Note
  • Getbulk requests require SNMPv2 or higher on the server.
  • The request PDU is automatically freed before returning to the caller, even when an exception is thrown.
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Exceptions
std::invalid_argumentif the PDU is empty.
Here is the call graph for this function:

◆ getNext() [1/2]

SNMPpp::PDU SNMPpp::getNext ( SNMPpp::SessionHandle session,
const SNMPpp::OID o 
)

Get the next OID.

Note
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Exceptions
std::invalid_argumentif the OID is empty.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ getNext() [2/2]

SNMPpp::PDU SNMPpp::getNext ( SNMPpp::SessionHandle session,
SNMPpp::PDU request 
)

Get the next OID.

Note
  • The request PDU is automatically freed before returning to the caller, even when an exception is thrown.
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
See also
SNMPpp::sync() to see additional exceptions this may throw.
Exceptions
std::invalid_argumentif the PDU is empty.

If the PDU is already of type SNMPpp::PDU::kGetNext then it is sent unchanged to the server described in SNMPpp::SessionHandle. But if the PDU is of any other type – such as a response PDU – then we'll look through the varlist and take the last OID listed. Using this, a response PDU can quickly be re-used to get the next OID from a SNMP server.

For example, note how the output PDU is then re-used as input in this simple while loop:

pdu.clear();
pdu.addNullVar( ".1" );
while ( true )
{
pdu = SNMPpp::getNext( sessionHandle, pdu );
if ( ... )
}
Here is the call graph for this function:

◆ initializeNetSnmpAgent()

void SNMPpp::initializeNetSnmpAgent ( const std::string &  name = "snmppp")

Initialize net-snmp AgentX.

Exceptions
std::runtime_errorif net-snmp init_agent(name) returned an error.
Here is the caller graph for this function:

◆ netsnmpDisableLogging()

void SNMPpp::netsnmpDisableLogging ( void  )

Disable net-snmp logging.

See also
net-snmp/library/snmp_logging.h for several more options.

◆ netsnmpLogStdErr()

void SNMPpp::netsnmpLogStdErr ( const bool  enabled = true)

Toggle net-snmp logging to STDERR.

Todo:
Why is init_snmp_logging() an unresolved external in Windows?

◆ netsnmpLogSyslog()

void SNMPpp::netsnmpLogSyslog ( const bool  enabled = true)

Toggle net-snmp logging to syslog.

Todo:
Why is init_snmp_logging() an unresolved external in Windows?
Here is the caller graph for this function:

◆ netsnmpLogToFile()

void SNMPpp::netsnmpLogToFile ( const bool  enabled = true,
const std::string &  filename = "/var/log/netsnmp.log" 
)

Toggle net-snmp logging to an external file.

Note
net-snmp may not be running as "root", and may not have access to the file it is being told to use to log. Check your directory and file write permissions if the log file you expect wasn't created.
Todo:
Why is init_snmp_logging() an unresolved external in Windows?
Todo:
Why is snmp_disable_filelog() an unresolved external in Windows?

◆ openSession()

void SNMPpp::openSession ( SNMPpp::SessionHandle sessionHandle,
const std::string &  server = "udp:127.0.0.1:161",
const std::string &  community = "public",
const int  version = SNMP_VERSION_2c,
const int  retryAttempts = 3 
)

Open a net-snmp session and return a session handle.

The session handle will be needed for all other net-snmp calls. Any previous value in "handle" will be blindly overwritten, so don't re-use handles unless you've remembered to call either snmp_sess_close() or SNMPpp::closeSession().

Note
  • Handles must be freed when no longer needed.
  • Handles are not the same as struct snmp_session!
  • This will throw if something goes wrong when setting up the session.
Exceptions
std::runtime_errorif snmp_sess_open() fails to return a valid new session.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ sendV2Trap() [1/3]

void SNMPpp::sendV2Trap ( const SNMPpp::OID o,
const long  uptime = SNMPpp::centisecondsNetSnmpUptime() 
)

Send a SNMPv2 trap to all configured trapsinks in net-snmp.

Note
To send a trap, it seems an application must have made the right calls to be considered a net-snmp agent. If you want to generate traps from an application which isn't running as an agent, remember to call SNMPpp::initializeNetSnmpAgent() otherwise no trap will be sent.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ sendV2Trap() [2/3]

void SNMPpp::sendV2Trap ( SNMPpp::Varlist varlist)

Send a SNMPv2 trap to alll configured trapsinks in net-snmp.

If you have a variable list already made up with at least 2 entries describing the uptime and the trap, call this function. Note you can use this to send as many additional OIDs as you want with the trap. The variable list is freed prior to returning to the caller.

See also
SNMPpp::createV2TrapVarlist();
Exceptions
std::invalid_argumentif varlist is empty.
std::invalid_argumentif the varlist contains less than 2 OIDs.
std::runtime_errorif netsnmp_send_traps(...) returned an error.
Here is the call graph for this function:

◆ sendV2Trap() [3/3]

void SNMPpp::sendV2Trap ( SNMPpp::PDU pdu)

Similar to SNMPpp::sendV2Trap( SNMPpp::Varlist &vl ).

The PDU is freed prior to returning to the caller.

Exceptions
std::invalid_argumentif the PDU is empty.
Here is the call graph for this function:

◆ shutdownNetSnmpAgent()

void SNMPpp::shutdownNetSnmpAgent ( const std::string &  name = "snmppp")

De-initialize net-snmp AgentX.

Here is the caller graph for this function:

◆ sync()

SNMPpp::PDU SNMPpp::sync ( SNMPpp::SessionHandle session,
SNMPpp::PDU request 
)

Send a PDU using the given SNMPpp::SessionHandle, and wait for a reply.

This is the method all other "get" functions call to perform the underlying request->response sync with the SNMP server.

Note
  • The request PDU is automatically freed before returning to the caller, even when an exception is thrown.
  • The response PDU needs to be freed using SNMPpp::PDU::free().
  • This will throw if an unexpected problem occurs.
Exceptions
std::invalid_argumentif the PDU is empty.
std::invalid_argumentif the session handle is NULL.
std::runtime_errorif snmp_sess_synch_response() returned an error.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ version()

std::string SNMPpp::version ( void  )

Return the SNMPpp version number.

See also
LIBSNMPPPVER.
Here is the caller graph for this function: