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

#include <master_proxy.hpp>

Inheritance diagram for agentxcpp::master_proxy:

Collaboration diagram for agentxcpp::master_proxy:

Public Member Functions
virtual void	handle_pdu (shared_ptr< PDU >, int error)
	The dispatcher for incoming PDU's.
	master_proxy (boost::asio::io_service *io_service, std::string description="", uint8_t default_timeout=0, oid ID=oid(), std::string unix_domain_socket="/var/agentx/master")
	Create a session object connected via unix domain socket.
	master_proxy (std::string description="", uint8_t default_timeout=0, oid ID=oid(), std::string unix_domain_socket="/var/agentx/master")
	Create a session object connected via unix domain socket.
void	register_subtree (oid subtree, uint8_t priority=127, uint8_t timeout=0)
	Register a subtree with the master agent.
void	unregister_subtree (oid subtree, uint8_t priority=127)
	Unregister a subtree with the master agent.
boost::asio::io_service *	get_io_service () const
	Get the io_service object used by this master_proxy.
bool	is_connected ()
	Check whether the session is in state connected.
void	connect ()
	Connect to the master agent.
void	disconnect (ClosePDU::reason_t reason=ClosePDU::reasonShutdown)
	Shutdown the session.
void	reconnect ()
	Reconnect to the master agent.
uint32_t	get_sessionID ()
	Get the sessionID of the session.
	~master_proxy ()
	Destructor.
void	add_variable (const oid &id, shared_ptr< variable > v)
	Add an SNMP variable for serving.
void	remove_variable (const oid &id)
	Remove an SNMP variable so that is not longer accessible.
Public Member Functions inherited from agentxcpp::connector::pdu_handler
virtual void	handle_pdu (boost::shared_ptr< PDU > pdu, int error)=0
	Handler method for incoming PDU's.
virtual	~pdu_handler ()
	Destructor.

Private Member Functions
void	do_registration (boost::shared_ptr< RegisterPDU > pdu)
	Send a RegisterPDU to the master agent.
void	undo_registration (boost::shared_ptr< UnregisterPDU > pdu)
	Send a UnregisterPDU to the master agent.
boost::shared_ptr< UnregisterPDU >	create_unregister_pdu (boost::shared_ptr< RegisterPDU > pdu)
	Create UnregisterPDU for undoing a registration.

Private Attributes
boost::asio::io_service *	io_service
	The mandatory io_service object.
bool	io_service_by_user
	Was the io_service object provided by the user?
std::string	socket_file
	The path to the unix domain socket.
connector *	connection
	The connector object used for networking.
uint32_t	sessionID
	The session ID of the current session.
std::string	description
	A string describing the subagent.
uint8_t	default_timeout
	Default timeout of the session (in seconds).
oid	id
	An Object Identifier that identifies the subagent. May be the null OID.
std::list< boost::shared_ptr < RegisterPDU > >	registrations
	The registrations.
std::map< oid, shared_ptr < variable > >	variables
	Storage for all SNMP variables known to the agentXcpp library.

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 master_proxy object is created. Multiple connections to the same master agent are possible, too, in which case one master_proxy per connection is needed.

Connection State

The master_proxy is always in one of the following states:

connected
disconnected

The session to the master agent is established when creating a master_proxy object, thus the object usually starts in connected state. If that fails, the object starts in disconnected state. A connected master_proxy 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 io_service object

The master_proxy class uses the boost::asio library for networking and therefore needs a boost::asio::io_service object. This object can either be provided by the user or created automatically. There are two constructors available therefore. The used object (whether auto-created or not) can be obtained using the get_io_service() function. If the io_service object was autocreated by a constructor, it will be destroyed by the destructor. If the user provided the io_service, it will NOT be destroyed by the destructor. It is possible to create multiple master_proxy objects using the same io_service object, or using different io_service objects.

Receiving data from the master agent is done asynchronously and only works if io_service::run() or io_service::run_one() is invoked. However, some operations (such as registering stuff) invoke io_service::run_one() several times while waiting for a response from the master agent. If the io_service object is not used exclusively by the master_proxy object (which is entirely possible), this may complete asynchronous events before the library operation (e.g. registering) is completed. Even the internal asynchronous reception calls io_service::run_one() while waiting for more data. If this behaviour is not desired, a separate io_service object should be used for other asynchronous I/O operations.

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 some of 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 conecerning 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.

The master_proxy object generates a RegisterPDU object each time a registration is performed. These RegisterPDU objects are stored in the registrations member.

When unregistering, the matching RegisterPDU is removed from the registration member.

The registration member becomes invalid on connection loss. Since a connection loss is not signalled, the member cannot be cleared in such situations. Therefore, it is cleared in the connect() method if the object is currently disconnected. If connect() is called on a connected master_proxy object, the registrations member is not cleared.

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 master_proxy object, e.g. using add_variable(). The master_proxy 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.

The variables are stored in the member variables, which is a std::map<oid, shared_ptr<variable> >. The key is the OID for which the variable was added. This allows easy lookup for the request dispatcher.

When removing a variable, it is removed from the variables member.

The variables member becomes invalid on connection loss. Since a connection loss is not signalled, the member cannot be cleared in such situations. Therefore, it is cleared in the connect() method if the object is currently disconnected. If connect() is called on a connected master_proxy object, the variables member is not cleared.

Internals

The io_service_by_user variable is used to store whether the io_service object was generated automatically. It is set to true or false by the respective constructors and evaluated by the destructor.

Receiving and processing PDU's coming from the master is done using the connector class. The master_proxy class implements the connectro::pdu_handler interface to recieve PDU's from the connector. A master_proxy object registers itself with the connector object, which then invokes master_proxy::handle_pdu() for incoming PDU's. Registering is done by the constructors, while the destructor unregisters the object.

Definition at line 207 of file master_proxy.hpp.

Constructor & Destructor Documentation

master_proxy::master_proxy	(	boost::asio::io_service *	io_service,
		std::string	description = `""`,
		uint8_t	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.

This constructor takes an io_service object as parameter. The io_service is not destroyed by the constructor.

Parameters:

io_service	The io_service object.
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 desribed in RFC 2741, section 8.2.1 "Well-known Values".

Definition at line 42 of file master_proxy.cpp.

References connect(), connection, default_timeout, io_service, and agentxcpp::connector::register_handler().

master_proxy::master_proxy	(	std::string	description = `""`,
		uint8_t	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.

This constructor creates an io_service object which is destroyed by the desctructor.

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 desribed in RFC 2741, section 8.2.1 "Well-known Values".

Definition at line 78 of file master_proxy.cpp.

References connect(), connection, default_timeout, io_service, and agentxcpp::connector::register_handler().

master_proxy::~master_proxy ( )

Destructor.

The destructor cleanly shuts down the session with the reason 'Shutdown' (if it is currently established) and destroys the master_proxy object. It also destroys the io_service object if it was created automatically (i.e. not provided by the user).

Definition at line 231 of file master_proxy.cpp.

References connection, disconnect(), io_service, io_service_by_user, and agentxcpp::ClosePDU::reasonShutdown.

Member Function Documentation

void master_proxy::add_variable	(	const oid &	id,
		shared_ptr< variable >	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 odl 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.

Definition at line 635 of file master_proxy.cpp.

References id, registrations, and variables.

void master_proxy::connect ( )

Connect to the master agent.

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

Exceptions:

disconnected If connecting fails.

Definition at line 116 of file master_proxy.cpp.

References agentxcpp::connector::connect(), connection, default_timeout, agentxcpp::connector::disconnect(), agentxcpp::PDU::get_packetID(), agentxcpp::connector::is_connected(), agentxcpp::ResponsePDU::noAgentXError, registrations, agentxcpp::connector::send(), sessionID, agentxcpp::OpenPDU::set_id(), agentxcpp::OpenPDU::set_timeout(), variables, and agentxcpp::connector::wait_for_response().

Referenced by master_proxy().

boost::shared_ptr< UnregisterPDU > master_proxy::create_unregister_pdu ( boost::shared_ptr< RegisterPDU > pdu )

private

Create UnregisterPDU for undoing a registration.

This function creates an UnregisterPDU which unregisters the MIB region which is registered by a given RegisterPDU.

Parameters:

pdu	The RegisterPDU which creates a registration.

Returns:: The created UnregisterPDU.

Exceptions:

None.

Definition at line 465 of file master_proxy.cpp.

Referenced by disconnect(), and unregister_subtree().

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

Shutdown the session.

Disconnect from the master agent.

Note:: Upon destruction of a session 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.

Definition at line 177 of file master_proxy.cpp.

References connection, create_unregister_pdu(), agentxcpp::connector::disconnect(), agentxcpp::PDU::get_packetID(), agentxcpp::connector::is_connected(), agentxcpp::ResponsePDU::noAgentXError, registrations, agentxcpp::connector::send(), sessionID, undo_registration(), and agentxcpp::connector::wait_for_response().

Referenced by ~master_proxy().

void master_proxy::do_registration ( boost::shared_ptr< RegisterPDU > pdu )

private

Send a RegisterPDU to the master agent.

This function sends a RegisterPDU to the master agent, waites for the response and evaluates it. This means that run_one() is called one or more times on the io_service object.

Parameters:

pdu	The RegisterPDU to send.

Exceptions:

disconnected	If the master_proxy is currently in state 'disconnected'.
timeout_error	If the master agent does not respond within the timeout interval.
internal_error	If the master received a malformed PDU. This is probably a programming error within the agentXcpp library.
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 alread 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	If an unexpected response was received from the master. This is probably a programming error within the master agent. It is possible that the master actually performed the desired registration and that a retry will result in a duplicate_registration error.

Definition at line 248 of file master_proxy.cpp.

References connection, agentxcpp::ResponsePDU::duplicateRegistration, is_connected(), agentxcpp::ResponsePDU::noAgentXError, agentxcpp::ResponsePDU::notOpen, agentxcpp::ResponsePDU::parseError, agentxcpp::ResponsePDU::processingError, agentxcpp::ResponsePDU::requestDenied, agentxcpp::connector::send(), agentxcpp::ResponsePDU::unsupportedContext, and agentxcpp::connector::wait_for_response().

Referenced by register_subtree().

boost::asio::io_service* agentxcpp::master_proxy::get_io_service ( ) const

inline

Get the io_service object used by this master_proxy.

Definition at line 573 of file master_proxy.hpp.

References io_service.

uint32_t agentxcpp::master_proxy::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.

Definition at line 640 of file master_proxy.hpp.

References sessionID.

void master_proxy::handle_pdu	(	shared_ptr< PDU >	pdu,
		int	error
	)

virtual

The dispatcher for incoming PDU's.

This method implements pdu_handler::handle_pdu() and is invoked by the connector object when PDU's are received.

Definition at line 480 of file master_proxy.cpp.

References connection, agentxcpp::ResponsePDU::genErr, agentxcpp::ResponsePDU::noAgentXError, agentxcpp::varbind::noSuchInstance, agentxcpp::varbind::noSuchObject, agentxcpp::ResponsePDU::notOpen, agentxcpp::ResponsePDU::parseError, agentxcpp::connector::send(), sessionID, agentxcpp::ResponsePDU::set_error(), agentxcpp::ResponsePDU::set_index(), agentxcpp::PDU::set_packetID(), agentxcpp::PDU::set_sessionID(), agentxcpp::PDU::set_transactionID(), agentxcpp::ResponsePDU::varbindlist, and variables.

bool agentxcpp::master_proxy::is_connected ( )

inline

Check whether the session is in state connected.

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

Definition at line 583 of file master_proxy.hpp.

References connection, and agentxcpp::connector::is_connected().

Referenced by do_registration(), and undo_registration().

void agentxcpp::master_proxy::reconnect ( )

inline

Reconnect to the master agent.

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

Exceptions:

disconnected If connecting fails.

Definition at line 623 of file master_proxy.hpp.

References agentxcpp::connector::connect(), connection, and agentxcpp::connector::disconnect().

void master_proxy::register_subtree	(	oid	subtree,
		uint8_t	priority = `127`,
		uint8_t	timeout = `0`
	)

Register a subtree with the master agent.

This function registers a subtree (or MIB region).

This method adds the registered subtree to registrations on success.

           \param subtree The (root of the) subtree to register.

           \param priority The priority with which to register the subtree.
                           Default is 127 according to RFC 2741, 6.2.3.  
                           "The agentx-Register-PDU".

           \param 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".

           \exception disconnected If the master_proxy is currently in
                                   state 'disconnected'.

           \exception timeout_exception If the master agent does not
                                        respond within the timeout 
                                        interval.

           \exception master_is_unable The master agent was unable to
                                       perform the desired register 
                                       request.  The reason for that is 
                                       unknown.

           \exception duplicate_registration If the exact same subtree was
                                             alread registered, either by 
                                             another subagent or by this 
                                             subagent.

           \exception master_is_unwilling If the master was unwilling for
                                          some reason to make the desired 
                                          registration.

           \exception parse_error A malformed network message was found
                                  during communcation 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.

           \note This function invokes run_one() one or more times on the
                 io_service object.

Definition at line 316 of file master_proxy.cpp.

References do_registration(), registrations, and sessionID.

void master_proxy::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.

Definition at line 666 of file master_proxy.cpp.

References variables.

void master_proxy::undo_registration ( boost::shared_ptr< UnregisterPDU > pdu )

private

Send a UnregisterPDU to the master agent.

This function sends an UnregisterPDU to the master agent which revokes the registration done by a RegisterPDU. Then it waites for the response and evaluates it. This means that run_one() is called one or more times on the io_service object.

Parameters:

pdu	The RegisterPDU whose registration is to be revoked.

Exceptions:

disconnected	If the master_proxy is currently in state 'disconnected'.
timeout_error	If the master agent does not respond within the timeout interval.
internal_error	If the master received a malformed PDU. This is probably a programming error within the agentXcpp library.
master_is_unable	The master agent was unable to perform the desired register request. The reason for that is unknown.
unknown_registration	The MIB region is not currently registered with this parameters.
parse_error	If an unexpected response was received from the master. This is probably a programming error within the master agent. It is possible that the master actually performed the desired registration and that a retry will result in a duplicate_registration error.

Definition at line 402 of file master_proxy.cpp.

References connection, is_connected(), agentxcpp::ResponsePDU::noAgentXError, agentxcpp::ResponsePDU::notOpen, agentxcpp::ResponsePDU::parseError, agentxcpp::ResponsePDU::processingError, agentxcpp::connector::send(), agentxcpp::ResponsePDU::unknownRegistration, agentxcpp::ResponsePDU::unsupportedContext, and agentxcpp::connector::wait_for_response().

Referenced by disconnect(), and unregister_subtree().

void master_proxy::unregister_subtree	(	oid	subtree,
		uint8_t	priority = `127`
	)

Unregister a subtree with the master agent.

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

This method removes the registered subtree from registrations.

           \param subtree The (root of the) subtree to unregister.

           \param priority The priority with which the registration was
                           done.

           \exception disconnected If the master_proxy is currently in
                                   state 'disconnected'.

           \exception timeout_error If the master agent does not
                                    respond within the timeout interval.

           \exception master_is_unable The master agent was unable to
                                       perform the desired unregister 
                                       request.  The reason for that is 
                                       unknown.

           \exception unknown_registration The MIB region is not currently
                                           registered with this parameters.

           \exception parse_error A malformed network message was found
                                  during communcation 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.

           \note This function invokes run_one() one or more times on the
                 io_service object.

Definition at line 351 of file master_proxy.cpp.

References create_unregister_pdu(), registrations, and undo_registration().

Member Data Documentation

connector* agentxcpp::master_proxy::connection

private

The connector object used for networking.

Created by constructors, destroyed by destructor.

Definition at line 235 of file master_proxy.hpp.

Referenced by connect(), disconnect(), do_registration(), handle_pdu(), is_connected(), master_proxy(), reconnect(), undo_registration(), and ~master_proxy().

uint8_t agentxcpp::master_proxy::default_timeout

private

Default timeout of the session (in seconds).

A value of 0 indicates that there is no session-wide default.

Definition at line 256 of file master_proxy.hpp.

Referenced by connect(), and master_proxy().

std::string agentxcpp::master_proxy::description

private

A string describing the subagent.

Set upon object creation. It is allowed to be emtpy.

Definition at line 249 of file master_proxy.hpp.

oid agentxcpp::master_proxy::id

private

An Object Identifier that identifies the subagent. May be the null OID.

Definition at line 262 of file master_proxy.hpp.

Referenced by add_variable().

boost::asio::io_service* agentxcpp::master_proxy::io_service

private

The mandatory io_service object.

This object is needed for boost::asio operation. Depending on the constructor used, the object is either provided by the user or generated automatically.

Definition at line 218 of file master_proxy.hpp.

Referenced by get_io_service(), master_proxy(), and ~master_proxy().

bool agentxcpp::master_proxy::io_service_by_user

private

Was the io_service object provided by the user?

Definition at line 223 of file master_proxy.hpp.

Referenced by ~master_proxy().

std::list< boost::shared_ptr<RegisterPDU> > agentxcpp::master_proxy::registrations

private

The registrations.

Every time an registration is performed, the RegisterPDUs is stored in this list. This allows to automatically re-register these subtrees on reconnect (e.g. after a connection loss).

Definition at line 271 of file master_proxy.hpp.

Referenced by add_variable(), connect(), disconnect(), register_subtree(), and unregister_subtree().

uint32_t agentxcpp::master_proxy::sessionID

private

The session ID of the current session.

If disconnected, the value is undefined.

Definition at line 242 of file master_proxy.hpp.

Referenced by connect(), disconnect(), get_sessionID(), handle_pdu(), and register_subtree().

std::string agentxcpp::master_proxy::socket_file

private

The path to the unix domain socket.

Definition at line 228 of file master_proxy.hpp.

std::map< oid, shared_ptr<variable> > agentxcpp::master_proxy::variables

private

Storage for all SNMP variables known to the agentXcpp library.

Definition at line 277 of file master_proxy.hpp.

Referenced by add_variable(), connect(), handle_pdu(), and remove_variable().

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

/home/tanjeff/projekte/agentxcpp/agentXcpp-0.1.1/src/master_proxy.hpp
/home/tanjeff/projekte/agentxcpp/agentXcpp-0.1.1/src/master_proxy.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation