An AgentX represents an AgentX sub-agent. More...

#include <agentx.hpp>

Classes
class	OidRegistrationEntry
	An OidRegistrationEntry represents an OID that has been registered. More...

class	ValueEntry
	A ValueEntry represents an OID's value. More...

Public Member Functions
	AgentX (const Context &context)
	Constructor. More...

virtual	~AgentX ()
	Destructor. More...

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

void	identifier (const NumericOid &oid)
	This sets the identifier OID for the agent. More...

NumericOid	identifier () const
	This returns the identifier OID for the agent. More...

void	description (const std::string &text)
	This sets the description for the agent. More...

std::string	description () const
	This returns the description for the agent. More...

void	raw_addAgentCapabilities (const NumericOid &oid, const std::string &description)
	This sends an "AddAgentCaps" PDU to the master agent. More...

void	raw_removeAgentCapabilities (const NumericOid &oid)
	This sends a "RemoveAgentCaps" PDU to the master agent. More...

void	raw_registerTree (const NumericOid &oid, uint8_t priority=DEFAULT_PRIORITY)
	This sends a "Register" PDU to the master agent. More...

void	raw_registerOid (const NumericOid &oid, uint8_t priority=DEFAULT_PRIORITY)
	This sends a "Register" PDU to the master agent with a flag signifying "instance" registration. More...

void	addAgentCapabilities (const NumericOid &oid, const std::string &description) throw ( Exception )
	This adds a new capability for the agent. More...

void	removeAgentCapabilities (const NumericOid &oid) throw ( Exception )
	This removes a previously registered capability. More...

void	registerOid (const NumericOid &oid, const OidRegistrationEntry &entry) throw ( Exception )
	This registers a new OID. More...

Static Public Attributes
static const uint8_t	DEFAULT_PRIORITY
	This is the default value for the "priority" of an OID registered with the "Register" PDU. More...

Protected Types
typedef std::map< NumericOid, std::string >	CapabilityMap
	A CapabilityMap maps an OID to a string.

typedef std::map< NumericOid, OidRegistrationEntry >	OidRegistrationMap
	An OidRegistrationMap maps an OID to its registration entry.

Protected Member Functions
OidRegistrationMap::const_iterator	registrationThatCovers (const NumericOid &oid)
	This returns the "oidRegistrationMap" iterator whose entry would be responsible for the OID given. More...

void	rawRead (AgentxPacket &packet)
	This reads an AgentxPacket from the transport. More...

void	rawWrite (AgentxPacket &packet)
	This writes an AgentxPacket to the transport. More...

void	open ()
	This connects the agent to the master agent. More...

void	close ()
	This disconnects the agent from the master agent.

void	startMailboxThread ()
	This starts the mailbox thread, if it has not already been started.

void	stopMailboxThread ()
	This stops the mailbox thread, if it has not already been stopped.

void	mailboxRead (AgentxPacket &packet, uint32_t packetId) throw ( Exception )
	This attempts to obtain the packet, with the specified ID, from the mailbox. More...

void	mailboxMain ()
	This is the main loop for the mailbox thread.

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

NumericOid	_identifier
	This is the OID that identifies the Agent; each Agent should have a unique identifying OID. More...

std::string	_description
	This is the description of the Agent.

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

uint32_t	packetNumber
	This is a counter that is incremented for each packet sent by this agent. More...

uint32_t	sessionId
	This is the session ID, as given by the master agent.

std::mutex	readMutex
	This is the read mutex used for guaranteeing that only a single thread is working with the inbox for this agent at any one time. More...

std::condition_variable	readConditionVariable
	This is used to notify any waiting threads when a new packet is available from the inbox. More...

std::mutex	writeMutex
	This is the write mutex used for guaranteeing that only a single thread is speaking for this agent at any one time. More...

std::map< uint32_t, std::unique_ptr< AgentxPacket > >	inbox
	This represents an "inbox" of packets received from the master agent. More...

bool	isStopped
	This is whether or not the mailbox thread is "stopped"; if the thread has not been started, then it is stopped. More...

std::thread	mailboxThread
	This is the thread that runs the main loop for handling the mailbox.

CapabilityMap	capabilityMap
	This is the mapping of capability OID to its description; these are created by adding a new "capability" to the agent. More...

OidRegistrationMap	oidRegistrationMap
	This is the mapping of an OID to its registration entry. More...

Detailed Description

An AgentX represents an AgentX sub-agent.

Such a sub-agent is loosely identified by two things:

An OID; and
A description.

Neither is particularly necessary, but these help to distinguish (on the master side) one agent from another.

Each instance will have its own thread for handling asynchronous operations (such as those received from the master agent). This is called the "mailbox" thread. This agent will be periodically receiving requests from the master agent; those requests will be stored in the "inbox"; they will be answered appropriately by the agent.

Sometimes, these will call user-specified callbacks, sometimes they won't.

Constructor & Destructor Documentation

AgentX ( const Context & context )

Constructor.

Parameters

context The Dangerous SNMP Context to use.

virtual ~AgentX ( )

virtual

Destructor.

If the "mailbox" thread is running, then it is stopped.

Member Function Documentation

void addAgentCapabilities	(	const NumericOid &	oid,
		const std::string &	description
	)
throw	(	Exception
	)

This adds a new capability for the agent.

If this capability has already been registered, then an exception will be thrown.

Parameters

oid	The OID that represents the capability.
description	The description of the capability.

void description ( const std::string & text )

inline

This sets the description for the agent.

This must be set before a call to "open" in order to take effect.

Parameters

text	The new description.

std::string description ( ) const

inline

This returns the description for the agent.

Returns: The description.

void identifier ( const NumericOid & oid )

inline

This sets the identifier OID for the agent.

This must be set before a call to "open" in order to take effect.

Parameters

oid	The new identifier OID.

NumericOid identifier ( ) const

inline

This returns the identifier OID for the agent.

Returns: The identifier OID.

void mailboxRead	(	AgentxPacket &	packet,
		uint32_t	packetId
	)
throw	(	Exception
	)

protected

This attempts to obtain the packet, with the specified ID, from the mailbox.

If there is no such packet, then this will wait for at most 5 seconds before failing.

Exception conditions:

The transport is not connected.
The packet could not be found within the time limit.

Parameters

packet	The packet to store the data from the mailbox.
packetId	The ID of the packet to retrieve.

Exceptions

Exception

void open ( )

protected

This connects the agent to the master agent.

The identifier OID and description are sent to the master agent, and the "open" command is issued.

A session ID is obtained from the master agent, and any pending communication with it is voided.

void raw_addAgentCapabilities	(	const NumericOid &	oid,
		const std::string &	description
	)

This sends an "AddAgentCaps" PDU to the master agent.

This PDU tells the master agent about a "capability" of this agent. This information will be registered under "sysORID" and "sysORDescr".

Parameters

oid	The OID that represents the capability.
description	The description.

void raw_registerOid	(	const NumericOid &	oid,
		uint8_t	priority = `DEFAULT_PRIORITY`
	)

This sends a "Register" PDU to the master agent with a flag signifying "instance" registration.

This PDU tells the master agent that this agent is responsible for this exact OID.

Parameters

oid	The OID to register.
priority	The priority of the registration. A lower value has a higher priority.

void raw_registerTree	(	const NumericOid &	oid,
		uint8_t	priority = `DEFAULT_PRIORITY`
	)

This sends a "Register" PDU to the master agent.

This PDU tells the master agent that this agent is responsible for any OIDs under the given OID, including that OID.

Parameters

oid	The OID to register.
priority	The priority of the registration. A lower value has a higher priority.

void raw_removeAgentCapabilities ( const NumericOid & oid )

This sends a "RemoveAgentCaps" PDU to the master agent.

This PDU tells the master agent that this agent no longer has the capability previously registered.

Parameters

oid	The OID that represents the capability.

void rawRead ( AgentxPacket & packet )

protected

This reads an AgentxPacket from the transport.

Parameters

packet The packet in which to store the data.

void rawWrite ( AgentxPacket & packet )

protected

This writes an AgentxPacket to the transport.

Parameters

packet The packet to write.

void registerOid	(	const NumericOid &	oid,
		const OidRegistrationEntry &	entry
	)
throw	(	Exception
	)

This registers a new OID.

Parameters

oid	The OID to register.
entry	The registration information.

Exceptions

Exception

OidRegistrationMap::const_iterator registrationThatCovers ( const NumericOid & oid )

protected

This returns the "oidRegistrationMap" iterator whose entry would be responsible for the OID given.

If the responsible entry is an OBJECT or INSTANCE registration, then its OID will match the one given exactly.

If the responsible entry is a TREE registration, then its OID will be the beginning of the one given.

Parameters

oid	The OID to search for.

Returns: The iterator to the entry in "oidRegistrationMap", or "oidRegistrationMap.end()" if it is not covered.

void removeAgentCapabilities	(	const NumericOid &	oid	)
throw	(	Exception
	)

This removes a previously registered capability.

If this capability has not already been registered, then an exception will be thrown.

Parameters

oid	The OID that represents the capability.

Exceptions

Exception

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}]

When this is called, the transport is created, and a "mailbox" is created and started for the agent.

Parameters

uri	The URI to use.

Exceptions

ParseErrorException,UnknownTransportException,Exception

Member Data Documentation

NumericOid _identifier

protected

This is the OID that identifies the Agent; each Agent should have a unique identifying OID.

This will be given to the master agent upon registration.

CapabilityMap capabilityMap

protected

This is the mapping of capability OID to its description; these are created by adding a new "capability" to the agent.

const uint8_t DEFAULT_PRIORITY

static

This is the default value for the "priority" of an OID registered with the "Register" PDU.

This is defined in RFC-2741.

std::map< uint32_t, std::unique_ptr<AgentxPacket> > inbox

protected

This represents an "inbox" of packets received from the master agent.

This maps a packet ID to its packet.

bool isStopped

protected

This is whether or not the mailbox thread is "stopped"; if the thread has not been started, then it is stopped.

OidRegistrationMap oidRegistrationMap

protected

This is the mapping of an OID to its registration entry.

When operations are requested of us (Get, GetNext, GetBulk, Set), this will be consulted to (1) find the OID, and (2) perform the necessary action.

uint32_t packetNumber

protected

This is a counter that is incremented for each packet sent by this agent.

std::condition_variable readConditionVariable

protected

This is used to notify any waiting threads when a new packet is available from the inbox.

std::mutex readMutex

protected

This is the read mutex used for guaranteeing that only a single thread is working with the inbox for this agent at any one time.

std::unique_ptr<Transport> transport

protected

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

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

std::mutex writeMutex

protected

This is the write mutex used for guaranteeing that only a single thread is speaking for this agent at any one time.

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

include/public/dangerous/snmp/agentx.hpp

Classes

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation