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

#include <master_proxy.hpp>

Inherits agentxcpp::connector::pdu_handler.

Public Member Functions
	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.

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.

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.

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

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

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).

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.

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.

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.

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

inline

Get the io_service object used by this master_proxy.

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.

bool agentxcpp::master_proxy::is_connected ( )

inline

Check whether the session is in state connected.

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

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.

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).

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

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.

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.

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation