A Client instance is used to communicate with an SNMP agent. More...

#include <client.hpp>

Public Member Functions
	Client (const Context &context)
	This constructs a new Client. More...

virtual	~Client ()
	Destructor.

std::string	uri () const
	This returns the URI for the connection. More...

void	uri (const std::string &uri) throw ( ParseErrorException, UnknownTransportException, Exception )
	This sets the URI for the client. More...

std::chrono::milliseconds	timeout () const
	This returns the timeout for the connection. More...

void	timeout (const std::chrono::milliseconds &timeout)
	This sets the timeout for the connection. More...

void	useVersion1 (const std::string &communityString)
	This configures the client for SNMPv1. More...

void	useVersion2c (const std::string &communityString)
	This configures the client for SNMPv2c. More...

void	useVersion3 (const securitymodel::USM &securityModel)
	This configures the client for SNMPv3/USM. More...

bool	isAuthenticated ()
	TODO: ????????? More...

void	authenticate ()
	TODO: ?????????

std::unique_ptr< RawResponse >	raw_get (PDU &requestPdu) throw ( Exception )
	This issues a "get" request. More...

std::unique_ptr< RawResponse >	raw_getnext (PDU &requestPdu) throw ( Exception )
	This issues a "getnext" request. More...

std::unique_ptr< RawResponse >	raw_getbulk (PDU &requestPdu) throw ( Exception )
	This issues a "getbulk" request. More...

std::unique_ptr< RawResponse >	raw_set (PDU &requestPdu) throw ( Exception )
	This issues a "set" request. More...

std::unique_ptr< Response >	get (const std::list< NumericOid > &oidList) throw ( Exception )
	This issues a simple "get" request. More...

std::unique_ptr< Response >	getNext (const std::list< NumericOid > &oidList)
	This issues a simple "getnext" request. More...

std::unique_ptr< Response >	getBulk (const std::list< NumericOid > &singleRequestOids, unsigned int multipleRequestLimit, const std::list< NumericOid > &multipleRequestOids)
	This issues a "getbulk" request. More...

std::unique_ptr< Response >	set (const VarBindList &varbinds) throw ( Exception )
	This issues a "set" request. More...

std::unique_ptr< Response >	walk (const NumericOid &oid, unsigned int limit=0, const NumericOid &startingOid=NumericOid())
	This performs a "walk" operation. More...

Protected Member Functions
template<typename PduEncoder >
void	lowLevelSend (SecurityModel *outgoingSecurityModel, PDU &request) throw ( Exception )
	Internal use only. More...

std::unique_ptr< ByteStream >	lowLevelReceive (std::unique_ptr< SecurityModel > &incomingSecurityModel) throw ( Exception )
	Internal use only. More...

template<typename PduEncoder >
std::unique_ptr< RawResponse >	basicRequest (PDU &request, SecurityModel *desiredSecurityModel=nullptr) throw ( Exception )
	Internal use only. More...

Protected Attributes
std::weak_ptr < Context::PrivateData >	context
	This is a weak pointer to the Context.

std::unique_ptr< Transport >	transport
	This is a pointer to the "Transport" instance that will be used to communicate with the SNMP agent. More...

std::unique_ptr< MessageProcessor >	messageProcessor
	This is a pointer to the "MessageProcessor" instance that will be handling the SNMP version envelope. More...

std::unique_ptr< SecurityModel >	securityModel
	This is the kind of security model that is being used. More...

int32_t	requestId
	This is the current request ID. More...

std::chrono::milliseconds	_timeout
	This is the timeout for the connection.

std::string	_uri
	This is the URI that was given for the connection.

Detailed Description

A Client instance is used to communicate with an SNMP agent.

In order to use a Client, you must first provide it with a URI for the connection. This URI will be used to determine the transport for the connection, as well as the address of the agent.

For example, you can connect to the local machine over UDP by using "udp://127.0.0.1".

The following transports are currently supported:

tcp
udp

In addition to the transport, you must specify the version of SNMP to use. There are currently three available versions of SNMP; each have benefits and drawbacks, and their use (in the case of a Client) will depend entirely on the version used by the agent in question.

SNMPv1 and SNMPv2c both use the concept of a "community string" that will be validated by the agent. Different community strings may be given different access rights, as well.

SNMPv3 supports a modular access control method, but the standard one is the "User Security Model" (USM). Here, a user name is required, and additional aspects of the communication can be specified (such as packet authentication and encryption).

A Client may communicate via two kinds of operations:

Raw operations, which represent simple protocol-level operations; and
Logical operations, which represent logical operations that are built on the protocol-level ones.

Constructor & Destructor Documentation

Client ( const Context & context )

This constructs a new Client.

Before it can be used, "uri" must be called.

Parameters

context The Dangerous SNMP Context to use.

Member Function Documentation

std::unique_ptr<RawResponse> basicRequest	(	PDU &	request,
		SecurityModel *	desiredSecurityModel = `nullptr`
	)
throw	(	Exception
	)

protected

Internal use only.

This performs a "basic" send and receive combination. This is used by the major user-facing operations.

Template Parameters

PduEncoder The static encoder class to use to encode the PDU.

Parameters

request	The PDU to send.
desiredSecurityModel	If this is null, then the Client's security model is used. Otherwise, the one specified here will be used.

Returns: A pointer to a RawResponse. This will never be nullptr.

Exceptions

Exception

std::unique_ptr<Response> get	(	const std::list< NumericOid > &	oidList	)
throw	(	Exception
	)

This issues a simple "get" request.

Parameters

oidList A list of OIDs to get.

Returns: A Response instance.

std::unique_ptr<Response> getBulk	(	const std::list< NumericOid > &	singleRequestOids,
		unsigned int	multipleRequestLimit,
		const std::list< NumericOid > &	multipleRequestOids
	)

This issues a "getbulk" request.

Parameters

singleRequestOids	A list of OIDs (strings) to get as in "getnext".
multipleRequestLimit	The number of times that "multipleRequestOids" should be requested.
multipleRequestOids	A list of OIDs (strings) to get as in "getnext", but repeated "multipleRequestLimit" times.

Returns: A Response instance.

std::unique_ptr<Response> getNext ( const std::list< NumericOid > & oidList )

This issues a simple "getnext" request.

Parameters

oidList A list of OIDs to get.

Returns: A Response instance.

bool isAuthenticated ( )

TODO: ?????????

Returns: TODO

std::unique_ptr<ByteStream> lowLevelReceive	(	std::unique_ptr< SecurityModel > &	incomingSecurityModel	)
throw	(	Exception
	)

protected

Internal use only.

This receives a ByteStream and updates the "incomingSecurityModel" with the relevant security information.

Parameters

incomingSecurityModel The security model to update.

Returns: A ByteStream pointer that can be used to extract a PDU. This is never nullptr.

Exceptions

Exception

void lowLevelSend	(	SecurityModel *	outgoingSecurityModel,
		PDU &	request
	)
throw	(	Exception
	)

protected

Internal use only.

This encodes and sends a PDU with the appropriate security model.

Template Parameters

PduEncoder The static encoder class to use to encode the PDU.

Parameters

outgoingSecurityModel	TODO
request	The PDU to send.

Exceptions

Exception

std::unique_ptr<RawResponse> raw_get	(	PDU &	requestPdu	)
throw	(	Exception
	)

This issues a "get" request.

The PDU will be sent as-is (with the exception of:

requestId; this will be set internally.

Note that if this returns a Report PDU, then that PDU will be in the response.

Parameters

requestPdu The PDU to send.

Returns: A unique pointer to a RawResponse.

Exceptions

Exception

std::unique_ptr<RawResponse> raw_getbulk	(	PDU &	requestPdu	)
throw	(	Exception
	)

This issues a "getbulk" request.

The PDU will be sent as-is (with the exception of:

requestId; this will be set internally.

Note that if this returns a Report PDU, then that PDU will be in the response.

Parameters

requestPdu The PDU to send.

Returns: A unique pointer to a RawResponse.

Exceptions

Exception

std::unique_ptr<RawResponse> raw_getnext	(	PDU &	requestPdu	)
throw	(	Exception
	)

This issues a "getnext" request.

The PDU will be sent as-is (with the exception of:

requestId; this will be set internally.

Note that if this returns a Report PDU, then that PDU will be in the response.

Parameters

requestPdu The PDU to send.

Returns: A unique pointer to a RawResponse.

Exceptions

Exception

std::unique_ptr<RawResponse> raw_set	(	PDU &	requestPdu	)
throw	(	Exception
	)

This issues a "set" request.

The PDU will be sent as-is (with the exception of:

requestId; this will be set internally.

Note that if this returns a Report PDU, then that PDU will be in the response.

Parameters

requestPdu The PDU to send.

Returns: A unique pointer to a RawResponse.

Exceptions

Exception

std::unique_ptr<Response> set	(	const VarBindList &	varbinds	)
throw	(	Exception
	)

This issues a "set" request.

Due to the nature of the SNMP "set" command, this will be almost trivially equivalent to the "raw_set" method. That is, a "set" command must be issued atomically, so there will be no special actions taken within this method.

Parameters

varbinds A VarBindList containing the OIDs (and their respective values) to set.

Returns: A Response instance.

std::chrono::milliseconds timeout ( ) const

inline

This returns the timeout for the connection.

Returns: The timeout.

void timeout ( const std::chrono::milliseconds & timeout )

inline

This sets the timeout for the connection.

Parameters

timeout The timeout.

std::string uri ( ) const

This returns the URI for the connection.

If the connection has no URI, then the string returned will have zero length.

Returns: The URI for the connection.

void uri	(	const std::string &	uri	)
throw	(	ParseErrorException,
		UnknownTransportException,
		Exception
	)

This sets the URI for the client.

A URI is of the form: {transport}://{address} Currently, the following transports are supported: udp The address is {ip address or hostname}[:{port number or name}] tcp The address is {ip address or hostname}[:{port number or name}]

Parameters

uri	The URI to use.

Exceptions

ParseErrorException,UnknownTransportException,Exception

void useVersion1 ( const std::string & communityString )

This configures the client for SNMPv1.

Parameters

communityString The community string.

void useVersion2c ( const std::string & communityString )

This configures the client for SNMPv2c.

Parameters

communityString The community string.

void useVersion3 ( const securitymodel::USM & securityModel )

This configures the client for SNMPv3/USM.

Parameters

securityModel The security information to use.

std::unique_ptr<Response> walk	(	const NumericOid &	oid,
		unsigned int	limit = `0`,
		const NumericOid &	startingOid = `NumericOid()`
	)

This performs a "walk" operation.

A walk is a conceptual operation that takes an OID as a starting point and returns a list of OIDs (and their values) that are "under" the starting OID. That is, the results are guaranteed to begin with exactly the same OID sequence that was given.

This operation is conceptually understood, in the simplest case, as performing "getnext" requests until the resulting OID no longer begins with the starting OID.

This operation also includes the concept of "paging"; that is, a limit can be given to limit the number of OIDs that are returned. If the limit is reached, then an additional call can be made using the last OID in the result as the "startingOid" for the new operation.

Parameters

oid	The starting OID.
limit	If set, then this will return only this many results.
startingOid	If set, then this will begin the walk starting from this OID.

Returns: A Response instance.

Member Data Documentation

std::unique_ptr<MessageProcessor> messageProcessor

protected

This is a pointer to the "MessageProcessor" instance that will be handling the SNMP version envelope.

This will be instantiated as a specific subclass of "MessageProcessor" when the version is specified.

int32_t requestId

protected

This is the current request ID.

This will be incremented for each request.

std::unique_ptr<SecurityModel> securityModel

protected

This is the kind of security model that is being used.

For SNMP versions 1 and 2c, this is fairly trivial. For version 3, things get a bit more exciting.

std::unique_ptr<Transport> transport

protected

This is a pointer to the "Transport" instance that will be used to communicate with the SNMP agent.

This will be instantiated as a specific subclass of "Transport" when the URI is handled.

The documentation for this class was generated from the following file:

include/public/dangerous/snmp/client.hpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation