This class represents the master agent in a subagent program. More...

#include <MasterProxy.hpp>

Inherits QObject.

Public Slots
void	send_notification (const Oid &snmpTrapOID, const TimeTicksVariable *sysUpTime, const std::vector< Varbind > &varbinds=vector< Varbind >())
	Send a notification or trap. More...

void	send_notification (const Oid &snmpTrapOID, const std::vector< Varbind > &varbinds=vector< Varbind >())
	Writing aid: Send notification without sysUpTime.0. More...

Public Member Functions
	MasterProxy (std::string description="", quint8 default_timeout=0, Oid ID=Oid(), std::string unix_domain_socket="/var/agentx/master")
	Create a session object connected via unix domain socket. More...

void	register_subtree (Oid subtree, quint8 priority=127, quint8 timeout=0)
	Register a subtree with the master agent. More...

void	unregister_subtree (Oid subtree, quint8 priority=127)
	Unregister a subtree with the master agent. More...

bool	is_connected ()
	Check whether the session is in state connected. More...

void	connect ()
	Connect to the master agent. More...

void	disconnect (ClosePDU::reason_t reason=ClosePDU::reasonShutdown)
	Shutdown the session. More...

void	reconnect ()
	Reconnect to the master agent. More...

quint32	get_sessionID ()
	Get the sessionID of the session. More...

	~MasterProxy ()
	Destructor. More...

void	add_variable (const Oid &id, QSharedPointer< AbstractVariable > v)
	Add an SNMP variable for serving. More...

void	addVariables (QVector< QPair< Oid, QSharedPointer< AbstractVariable > > > vars)
	Add several SNMP variables for serving. More...

void	remove_variable (const Oid &id)
	Remove an SNMP variable so that is not longer accessible. More...

void	removeVariables (const QVector< Oid > &ids)
	Remove several SNMP variables so that they are not longer accessible. More...

bool	isRegistered (Oid id)
	Check whether an OID is within the registered ranges. More...

Detailed Description

This class represents the master agent in a subagent program.

Introduction

This class is used on the subagent's side of a connection between subagent and master agent. It serves as a proxy which represents the master agent. It is possible for a subagent to hold connections to more than one master agents. For each connection one MasterProxy object is created. Multiple connections to the same master agent are possible, too, in which case one MasterProxy per connection is needed.

Connection State

The MasterProxy is always in one of the following states:

connected
disconnected

The session to the master agent is established when creating a MasterProxy object, thus the object usually starts in connected state. If that fails, the object starts in disconnected state. A connected MasterProxy object may also loose the connection to the master agent and consequently become disconnected, without informing the user. It is possible to re-connect with the reconnect() function at any time (even if the session is currently established - it will be shut down and re-established in this case). When the object is destroyed, the session will be cleanly shut down. The connection state can be inspected with the is_connected() function. Some functions throw a disconnected exception if the session is not currently established.

The QApplication object

The agentXcpp library uses the QT library. Processing SNMP requests (such as get and set) is performed within the QApplication event loop. Therefore, a program using agentXcpp must create a QApplication object and call exec() on it to start the event loop. The agentXcpp library also creates a QThread object for the networking part. Networking is done within the event loop of that thread.

Registrations

Before the master agent sends requests to a subagent, the subagent must register a subtree. Doing so informs the master agent that the subagent wishes to handle requests for these OIDs. A subtree is an OID which denotes the root of a subtree in which the offered objects resides. For example, when two objects shall be offered with the OIDs 1.3.6.1.4.1.42.1.1 and 1.3.6.1.4.1.42.1.2, then a subtree with OID 1.3.6.1.4.1.42.1 should be registered, which includes both objects. The master agent will then forward all requests concerning objects in this subtree to this subagent. Requests to non-existing objects (e.g. 1.3.6.1.4.1.42.1.3) are also forwarded, and the agentXcpp library will take care of them and return an appropriate error to the master agent.

The function register_subtree() is used to register a subtree. It is typically called for the highest-level OID of the MIB which is implemented by the subagent. However, it is entirely possible to register multiple subtrees.

Identical subtrees are subtrees with the exact same root OID. Each registration is done with a priority value. The higher the value, the lower the priority. When identical subtrees are registered (by the same subagent or by different subagents), the priority value is used to decide which subagent gets the requests. The master refuses identical registrations with the same priority values. Note however, that in case of overlapping subtrees which are not identical (e.g. 1.3.6.1.4.1.42.1 and 1.3.6.1.4.1.42.1.33.1), the most specific subtree (i.e. the one with the longest OID) wins regardless of the priority values.

It is also possible to unregister subtrees using the unregister_subtree() function. This informs the master agent that the MIB region is no longer available from this subagent.

Adding and Removing Variables

Registering a subtree does not make any SNMP variables accessible yet. To provide SNMP variables, they must be added to the MasterProxy object, e.g. using add_variable(). The MasterProxy object will then dispatch incoming requests to the variables it knows about. If a request is received for an OID for which no variable has been added, an appropriate error is returned to the master agent.

Added variables can be removed again using remove_variable(). This makes a variable inaccessible for the master agent.

Constructor & Destructor Documentation

MasterProxy::MasterProxy	(	std::string	description = `""`,
		quint8	default_timeout = `0`,
		Oid	ID = `Oid()`,
		std::string	unix_domain_socket = `"/var/agentx/master"`
	)

Create a session object connected via unix domain socket.

This constructor tries to connect to the master agent. If that fails, the object is created nevertheless and will be in state disconnected.

Parameters

description	A string describing the subagent. This description cannot be changed later.
default_timeout	The length of time, in seconds, that the master agent should allow to elapse before it regards the subagent as not responding. The value is also used when waiting synchronously for data from the master agent (e.g. when registering stuff). Allowed values are 0-255, with 0 meaning "no default for this session".
ID	An Object Identifier that identifies the subagent. Default is the null OID (no ID).
unix_domain_socket	The socket file to connect to. Defaults to /var/agentx/master, as described in RFC 2741, section 8.2.1 "Well-known Values".

MasterProxy::~MasterProxy ( )

Destructor.

The destructor cleanly shuts down the session (if it is currently established) with the reason 'Shutdown' and destroys the MasterProxy object.

Member Function Documentation

void MasterProxy::add_variable	(	const Oid &	id,
		QSharedPointer< AbstractVariable >	v
	)

Add an SNMP variable for serving.

This adds an SNMP variable which can then be read and/or written.

Variables can only be added to MIB regions which were registered in advance.

If adding a variable with an id for which another variable is already registered, it replaces the old one.

Parameters

id	The OID of the variable.
v	The variable.

Exceptions

unknown_registration If trying to add a variable with an id which does not reside within a registered MIB region.

void MasterProxy::addVariables ( QVector< QPair< Oid, QSharedPointer< AbstractVariable > > > vars )

Add several SNMP variables for serving.

This function takes multiple variables and calls agentxcpp::add_variable(const Oid&, QSharedPointer<AbstractVariable>) for each of them.

Parameters

vars	The variables to be added. Each QPair object contains an OID and the pointer to the variable; see agentxcpp::add_variable(const Oid&, QSharedPointer<AbstractVariable>) for an explanation.

Exceptions

unknown_registration If trying to add a variable with an id which does not reside within a registered MIB region.

void MasterProxy::connect ( )

Connect to the master agent.

Note: Upon creation of a MasterProxy object, the connection is automatically established. If the current state is "connected", the function does nothing.

Exceptions

disconnected If connecting fails.

void MasterProxy::disconnect ( ClosePDU::reason_t reason = ClosePDU::reasonShutdown )

Shutdown the session.

Disconnect from the master agent.

Note: Upon destruction of a MasterProxy object the session is automatically shutdown. If the session is in state "disconnected", this function does nothing.

Parameters

reason The shutdown reason is reported to the master agent during shutdown.

Exceptions

None.

quint32 agentxcpp::MasterProxy::get_sessionID ( )

inline

Get the sessionID of the session.

Get the session ID of the last established session, even if the current state is "disconnected".

Returns: The session ID of the last established session. If object was never connected to the master, 0 is returned.

bool agentxcpp::MasterProxy::is_connected ( )

inline

Check whether the session is in state connected.

Returns: true if the session is connected, false otherwise.

bool MasterProxy::isRegistered ( Oid id )

Check whether an OID is within the registered ranges.

This function checks whether the given OID is with an OID range which was registered before.

Parameters

id	The OID to check.

Returns: true if it is with an registered range, false otherwise.

Exceptions

None.

void agentxcpp::MasterProxy::reconnect ( )

inline

Reconnect to the master agent.

Disconnects from the master (only if currently connected), then connects again.

Exceptions

disconnected If connecting fails.

void MasterProxy::register_subtree	(	Oid	subtree,
		quint8	priority = `127`,
		quint8	timeout = `0`
	)

Register a subtree with the master agent.

This function registers a subtree (or MIB region).

Parameters

subtree	The (root of the) subtree to register.
priority	The priority with which to register the subtree. Default is 127 according to RFC 2741, 6.2.3. "The agentx-Register-PDU".
timeout	The timeout value for the registered subtree, in seconds. This value overrides the timeout of the session. Default value is 0 (no override) according to RFC 2741, 6.2.3. "The agentx-Register-PDU".

Exceptions

disconnected	If the MasterProxy is currently in state 'disconnected'.
timeout_exception	If the master agent does not respond within the timeout interval.
master_is_unable	The master agent was unable to perform the desired register request. The reason for that is unknown.
duplicate_registration	If the exact same subtree was already registered, either by another subagent or by this subagent.
master_is_unwilling	If the master was unwilling for some reason to make the desired registration.
parse_error	A malformed network message was found during communication with the master. This may be a programming error in the master or in the agentXcpp library. It is possible that the master actually performed the desired registration and that a retry will result in a duplicate_registration error.

void MasterProxy::remove_variable ( const Oid & id )

Remove an SNMP variable so that is not longer accessible.

This removes a variable previously added using add_variable(). The variable will no longer receive SNMP requests.

If no variable is known for the given id, nothing happens.

Parameters

id	The OID of the variable to remove. This is the OID which was given to add_variable().

Exceptions

None.

void MasterProxy::removeVariables ( const QVector< Oid > & ids )

Remove several SNMP variables so that they are not longer accessible.

This function takes multiple variables and calls agentxcpp::remove_variable(const Oid&) for each of them.

Parameters

ids	The variables to be removed.

Exceptions

None.

void MasterProxy::send_notification	(	const Oid &	snmpTrapOID,
		const TimeTicksVariable *	sysUpTime,
		const std::vector< Varbind > &	varbinds = `vector<Varbind>()`
	)

slot

Send a notification or trap.

This function sends a notification to the master agent, which in turn sends an SNMP notification or trap, depending on its configuration.

Each notification contains the snmpTrapOID.0 object (mandatory) and the sysUpTime.0 object (optional). The values of both objects are given as parameters.

Parameters

snmpTrapOID	The value of snmpTrapOID.0 according to RFC 1907, which says: "The authoritative identification of the notification currently being sent." This is normally the Trap OID as specified in the corresponding MIB. However, if the notification shall be converted to an SNMPv1 trap (this conversion is done by the master agent), the snmpTrapOID.0 value must meet certain requirements. You can use generate_v1_snmpTrapOID() to construct a valid value in that case.
sysUpTime	The value of the sysUpTime.0 object according to RFC 1907, which says: "The time (in hundreths of a second) since the network management portion of the system was last re-initialized.". You can use agentxcpp::processUpTime() to get the uptime of the current process. If the NULL pointer is given, the sysUpTime.0 will not be included in the notification, and the master agent will insert an sysUpTime.0 value (e.g. the uptime of the OS, depending on the master agent).
varbinds	Additional varbinds which are included in the notification.

Exceptions

timeout_error	FIXME
disconnected	FIXME
master_is_unable	FIXME
unsupported_context	FIXME

void agentxcpp::MasterProxy::send_notification	(	const Oid &	snmpTrapOID,
		const std::vector< Varbind > &	varbinds = `vector<Varbind>()`
	)

inlineslot

Writing aid: Send notification without sysUpTime.0.

This calls send_notification( const Oid&, const TimeTicksVariable*, const vector<varbind>&) with a NULL pointer for the sysUpTime.0 parameter.

For the documentation of the parameters and exceptions go to send_notification(const Oid&, TimeTicksVariable>&, const vector<varbind>&)

void MasterProxy::unregister_subtree	(	Oid	subtree,
		quint8	priority = `127`
	)

Unregister a subtree with the master agent.

This function unregisters a subtree (or MIB region) which has previously been registered.

Parameters

subtree	The (root of the) subtree to unregister.
priority	The priority with which the registration was done.

Exceptions

disconnected	If the MasterProxy is currently in state 'disconnected'.
timeout_error	If the master agent does not respond within the timeout interval.
master_is_unable	The master agent was unable to perform the desired unregister request. The reason for that is unknown.
unknown_registration	The MIB region is not currently registered with this parameters.
parse_error	A malformed network message was found during communication with the master. This may be a programming error in the master or in the agentXcpp library. It is possible that the master actually unregistered the MIB region.

Public Slots

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation