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 >)
	The dispatcher for incoming PDU's.
	master_proxy (boost::asio::io_service *io_service, std::string description="", byte_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="", byte_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, byte_t priority=127, byte_t timeout=0)
	Register a subtree with the master agent.
void	unregister_subtree (oid subtree, byte_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 ()
	Default 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.
byte_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.

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

This 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 (requests or responses to requests) 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.

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 171 of file master_proxy.hpp.

Constructor & Destructor Documentation

master_proxy::master_proxy	(	boost::asio::io_service *	io_service,
		std::string	description = `""`,
		byte_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. This io_service is not destroyed by the consntructor.

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 after receiving a message 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 = `""`,
		byte_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 after receiving a message 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 ( )

Default destructor.

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

Definition at line 232 of file master_proxy.cpp.

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

Member Function Documentation

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 118 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(), 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", the function does nothing.

Parameters:

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

Exceptions:

None.

Definition at line 178 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 249 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 528 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 595 of file master_proxy.hpp.

References sessionID.

virtual void agentxcpp::master_proxy::handle_pdu ( shared_ptr< PDU > ) [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.

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 538 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 578 of file master_proxy.hpp.

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

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

Register a subtree with the master agent.

This function registers a subtree (or MIB region). This function invokes run_one() one or more times on the io_service object.

This method adds the registered subtree to registrations on success.

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

Definition at line 317 of file master_proxy.cpp.

References do_registration(), and registrations.

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,
		byte_t	priority = `127`
	)

Unregister a subtree with the master agent.

This function unregisters a subtree (or MIB region) which has previously been registered. This function invokes run_one() one or more times on the io_service object.

This method removes the registered subtree from registrations.

Parameters:

subtree	The (root of the) subtree to unregister.
priority	The priority with which the registration was done. the subtree. Because register_subtree() uses 127 as default, this value is also the default for this function.

Exceptions:

disconnected	If the master_proxy 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 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.

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 200 of file master_proxy.hpp.

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

byte_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 221 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 214 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 227 of file master_proxy.hpp.

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 183 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 188 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 236 of file master_proxy.hpp.

Referenced by 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 207 of file master_proxy.hpp.

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

std::string agentxcpp::master_proxy::socket_file [private]

The path to the unix domain socket.

Definition at line 193 of file master_proxy.hpp.

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

/home/tanjeff/projekte/agentxcpp/src/master_proxy.hpp
/home/tanjeff/projekte/agentxcpp/src/master_proxy.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation