AgentX++  2.0.5
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Friends | List of all members
SubAgentXMib Class Reference

#include <agentx_subagent.h>

Inheritance diagram for SubAgentXMib:

Public Member Functions

 SubAgentXMib ()
 Default Constructor.
 
 SubAgentXMib (const NS_SNMP OctetStr &)
 Constructor with path where persistent MIB objects should be stored to and loaded from.
 
virtual ~SubAgentXMib ()
 Destructor.
 
virtual bool init ()
 Initialize the sub-agent by opening a session with the master agent and registering all MIB objects already added to the receiver.
 
virtual MibEntryPtr add (MibEntryPtr)
 Register a MIB object for the agent's MIB.
 
virtual MibEntryPtr add_no_reg (MibEntryPtr)
 Register a MIB object for the agent's MIB.
 
virtual MibEntry * add (const NS_SNMP OctetStr &, MibEntry *)
 Register a MIB object within a given context.
 
virtual MibEntry * register_entry (const NS_SNMP OctetStr &, MibEntry *, u_int)
 Register a MIB object within a given context at the master.
 
virtual MibEntry * add_no_reg (const NS_SNMP OctetStr &, MibEntry *)
 Register a MIB object within a given context.
 
virtual bool remove (const Oidx &)
 Unregister a MIB object from the agent's MIB.
 
virtual bool remove_no_unreg (const Oidx &)
 Unregister a MIB object from the agent's MIB, but do not unregister it with the master.
 
virtual bool remove (const NS_SNMP OctetStr &, const Oidx &)
 Unregister a MIB object from the agent≥s MIB.
 
virtual bool remove_no_unreg (const NS_SNMP OctetStr &, const Oidx &)
 Unregister a MIB object from the given context, but do not unregister it with the master.
 
virtual int open_session ()
 Open session.
 
virtual void reconnect ()
 (Re)Connect with the master.
 
void set_default_priority (const u_char p)
 Set the default priority for registrations by this sub-agent.
 
void set_request_list (AgentXRequestList *)
 Set the RequestList to be used for answering request.
 
virtual int notify (const NS_SNMP OctetStr &, const Oidx &, Vbx *, int, unsigned int=0)
 Send a notification.
 
virtual unsigned long ping_master ()
 Send a ping PDU to the master agent to monitor the master agent's ability to receive and send AgentX PDUs over their AgentX session.
 
virtual void ping_received (const AgentXPdu &)
 This method is called when this subagent received a PING response from its master.
 
virtual bool register_region (const NS_SNMP OctetStr &, const AgentXRegion &, u_int timeout, bool, AgentXSharedTable *t=0)
 Register a region at the master agent.
 
virtual void registration_failed (const AgentXRegion &, int, AgentXSharedTable *)
 Registration failed.
 
virtual void registration_success (const AgentXRegion &, AgentXSharedTable *)
 Registration success.
 
virtual u_int allocate_index (const NS_SNMP OctetStr &, Vbx *, int, AgentXSharedTable *t=0, u_char indexType=0, Oidx *rowIndex=0)
 Allocate a set of index values.
 
virtual u_int deallocate_index (const NS_SNMP OctetStr &, Vbx *, int, AgentXSharedTable *table=0, Oidx *rowIndex=0)
 Deallocate a set of index values.
 
virtual void index_allocated (u_int, u_int, Vbx *, int, AgentXSharedTable *, u_int, Oidx *)
 This method is being called, whenever an index allocation has been processed by the master and the result has been returned to the subagent.
 
virtual void index_deallocated (u_int, u_int, Vbx *, int, AgentXSharedTable *, u_int, Oidx *)
 This method is being called, whenever an index deallocation has been processed by the master and the result has been returned to the subagent.
 
virtual bool add_agent_caps (const NS_SNMP OctetStr &, const Oidx &, const NS_SNMP OctetStr &)
 Add agent capabilities to the sysORTable of the master.
 
virtual void remove_agent_caps (const NS_SNMP OctetStr &, const Oidx &)
 Add agent capabilities to the sysORTable of the master.
 
AgentXSessionget_session ()
 Gets a pointer to the AgentXSession associated with this SubAgentXMib instance.
 
AgentXIndexDBget_index_registry ()
 Gets a pointer to the index registry associated with this subagent.
 

Static Public Member Functions

static AgentXSlaveget_agentx ()
 Get the AgentXSlave instance used for AgentX services.
 

Protected Member Functions

virtual AgentXSessioncreate_session ()
 Create a session that will be used for this Mib instance.
 
virtual void not_connected ()
 This method is called when an attempt has been made to send an AgentX message to the master agent.
 
virtual int find_next (MibContext *, const Oidx &, MibEntryPtr &, Request *req, const int, Oidx &nextOid)
 Find the next MIB entry which has an oid greater than the given oid.
 
virtual void do_process_request (Request *)
 Process an AgentX request.
 
virtual void process_response (AgentXRequest *)
 Process an AgentX response.
 
virtual void synchronize_uptime (u_int)
 Synchronize local sysUpTime with the given time.
 
void remove_pending_messages (MibEntry *)
 Remove pending messages for a MibEntry instance.
 
AgentXPendingMessageget_pending_message (u_int)
 
virtual void init_response_pool ()
 Create and initialize response pool and queue.
 
virtual void delete_request (Request *req)
 Deletes the supplied request unless it is a TestSet or CommitSet PDU.
 

Protected Attributes

AgentXSessionsession
 
agentx_run_status_t status
 
u_char priority
 
AgentXIndexDBindexRegistry
 
List< AgentXPendingMessagependingMessages
 
Synchronized pendingMessagesLock
 
QueuedThreadPool * responsePool
 

Static Protected Attributes

static AgentXSlaveagentx
 

Friends

class AgentXResponse
 

Constructor & Destructor Documentation

SubAgentXMib::SubAgentXMib ( )

Default Constructor.

SubAgentXMib::SubAgentXMib ( const NS_SNMP OctetStr &  )

Constructor with path where persistent MIB objects should be stored to and loaded from.

Parameters
paththe directory to store persistent objects.
virtual SubAgentXMib::~SubAgentXMib ( )
virtual

Destructor.

Member Function Documentation

virtual MibEntryPtr SubAgentXMib::add ( MibEntryPtr  )
virtual

Register a MIB object for the agent's MIB.

If the subagent's connection to the master is established, then the object will be immediately registered at the master.

Parameters
itema pointer to a MibEntry object (i.e., MibLeaf, MibTable, MibGroup, ...).
Returns
The input pointer (if the registered object is of type MibGroup 0).
virtual MibEntry* SubAgentXMib::add ( const NS_SNMP OctetStr &  ,
MibEntry *   
)
virtual

Register a MIB object within a given context.

If the given context is a new context, it will be added to the list of known contexts. If the subagent's connection to the master is established, then the object will be immediately registered at the master.

Note: This method is synchronized using ::lock_mib()

Parameters
contextan OctetStr instance specifiying the target context.
itema pointer to a MibEntry object (i.e., MibLeaf, MibTable, MibGroup, ...).
Returns
the input pointer if the MibEntry could be registered, or 0 otherwise.
virtual bool SubAgentXMib::add_agent_caps ( const NS_SNMP OctetStr &  ,
const Oidx &  ,
const NS_SNMP OctetStr &   
)
virtual

Add agent capabilities to the sysORTable of the master.

Parameters
contexta context. Use "" for the default context.
idan object identifier containing the value of an invocation of the AGENT-CAPABILITIES macro, which the master agent exports as a value of sysORID for the indicated context.
descran OctetStr containing a DisplayString to be used as the value of sysORDescr corresponding to the sysORID value above.
Returns
TRUE if the context could be found.
virtual MibEntryPtr SubAgentXMib::add_no_reg ( MibEntryPtr  )
virtual

Register a MIB object for the agent's MIB.

If the subagent's connection to the master is established, then the object will not be registered at the master, otherwise it will be registered through the reconnect method.

Parameters
itema pointer to a MibEntry object (i.e., MibLeaf, MibTable, MibGroup, ...).
Returns
the input pointer (if the registered object is of type MibGroup 0).
virtual MibEntry* SubAgentXMib::add_no_reg ( const NS_SNMP OctetStr &  ,
MibEntry *   
)
virtual

Register a MIB object within a given context.

If the given context is a new context, it will be added to the list of known contexts. If the subagent's connection to the master is established, then the object will not be registered at the master, otherwise it will be registered through the reconnect method.

Note: This method is synchronized using ::lock_mib()

Parameters
contextan OctetStr instance specifiying the target context.
itema pointer to a MibEntry object (i.e., MibLeaf, MibTable, MibGroup, ...).
Returns
the input pointer if the MibEntry could be registered, or 0 otherwise.
virtual u_int SubAgentXMib::allocate_index ( const NS_SNMP OctetStr &  ,
Vbx *  ,
int  ,
AgentXSharedTable t = 0,
u_char  indexType = 0,
Oidx *  rowIndex = 0 
)
virtual

Allocate a set of index values.

Parameters
contexta context. "" denotes the default context.
indexValuesan array of Vbx instances. The oid portion denotes the oid of the specified index object and the value portion denotes the value of that index object.
sizethe size of the above array.
referencea pointer to an AgentXSharedTable instance association with this index allocation. Default for this parameter is 0.
indexTypethe type of index to be allocated. Possible values are: 0 - index values are given by indexValues AGENTX_NEW_INDEX - allocate unique new index values AGENTX_ANY_INDEX - allocate any new index values
rowIndexthe (optional) row index for which index values are allocated. Because index values can be allocated for one or more sub-indexes of a row index, the rowIndex value is not necessarily equal to the indexValues. The rowIndex will be deleted when the corresponding AgentX packet is deleted (or if the AgentX request could not be sent). Thus, the caller does not need to delete this pointer nor may the caller use it after the call anymore!
Returns
the AgentX packet ID which can be used to associate context information when the corresponding response has been received.
virtual AgentXSession* SubAgentXMib::create_session ( )
protectedvirtual

Create a session that will be used for this Mib instance.

Override this method to create your own session object, i.e., with a non-default timeout value.

Returns
a pointer to an AgentXSession instance. It will be deleted by SubAgentXMib when session is closed.
virtual u_int SubAgentXMib::deallocate_index ( const NS_SNMP OctetStr &  ,
Vbx *  ,
int  ,
AgentXSharedTable table = 0,
Oidx *  rowIndex = 0 
)
virtual

Deallocate a set of index values.

Parameters
contexta context. "" denotes the default context.
indexValuesan array of Vbx instances. The oid portion denotes the oid of the specified index object and the value portion denotes the value of that index object.
sizethe size of the above array.
referencea pointer to an AgentXSharedTable instance association with this index allocation. Default for this parameter is 0.
rowIndexthe (optional) row index for which index values are allocated. Because index values can be allocated for one or more sub-indexes of a row index, the rowIndex value is not necessarily equal to the indexValues. The rowIndex will be deleted when the corresponding AgentX packet is deleted (or if the AgentX request could not be sent). Thus, the caller does not need to delete this pointer nor may the caller use it after the call anymore!
Returns
the AgentX packet ID of the AgentX request which can be used to associate context information when the corresponding response has been received.
virtual void SubAgentXMib::delete_request ( Request *  req)
protectedvirtual

Deletes the supplied request unless it is a TestSet or CommitSet PDU.

Parameters
reqthe Request to delete.
Since
1.4.12
virtual void SubAgentXMib::do_process_request ( Request *  )
protectedvirtual

Process an AgentX request.

Parameters
reqa request.
virtual int SubAgentXMib::find_next ( MibContext *  ,
const Oidx &  ,
MibEntryPtr &  ,
Request *  req,
const int  ,
Oidx &  nextOid 
)
protectedvirtual

Find the next MIB entry which has an oid greater than the given oid.

(Respects AgentX search ranges)

Parameters
contextthe target context.
oidan object identifier.
entrywill be changed to a pointer to the found entry or remain unchanged if the return value is different from SNMP_ERROR_SUCCESS.
requesta pointer to the Request instance for in whose context the find_next is issued.
nextOidreturns the identified successor OID for complex entries. For mib entries where the next OID cannot be determined, the value will remain unchanged.
Returns
SNMP_ERROR_SUCCESS if an entry has been found and sNMP_SYNTAX_NOSUCHOBJECT otherwise.
static AgentXSlave* SubAgentXMib::get_agentx ( )
inlinestatic

Get the AgentXSlave instance used for AgentX services.

Returns
an AgentXSlave instance.
AgentXIndexDB* SubAgentXMib::get_index_registry ( )
inline

Gets a pointer to the index registry associated with this subagent.

The index registry records index registrations to avoid duplicate registrations for some index allocation strategies.

Returns
a pointer to the internal index registry.
AgentXPendingMessage* SubAgentXMib::get_pending_message ( u_int  )
protected
AgentXSession* SubAgentXMib::get_session ( )
inline

Gets a pointer to the AgentXSession associated with this SubAgentXMib instance.

Returns
a pointer to an AgentXSession instance. The content of the session should not be modified. In addition, the memory allocated for the session object may be invalidated when the session is closed.
virtual void SubAgentXMib::index_allocated ( u_int  ,
u_int  ,
Vbx *  ,
int  ,
AgentXSharedTable ,
u_int  ,
Oidx *   
)
virtual

This method is being called, whenever an index allocation has been processed by the master and the result has been returned to the subagent.

Parameters
erroran AgentX error code if the index allocation failed, or 0 if it has been completed successfully.
errorIndexif error is not 0, errorIndex points to the index object within the index that actually failed (starting from 1).
vbsan array of index objects.
sizethe size of the above array.
sharedTablea pointer to an AgentXSharedTable instance that initiated the index allocation. If the index allocation was not initiated by an AgentXSharedTable instance this pointer will be 0.
packetIDthe packet ID of the AgentX request that send the allocation PDU. This value can be used to associate any objects with the (asynchronous) index allocation request.
rowIndexthe row index originally provided to the allocation request.
virtual void SubAgentXMib::index_deallocated ( u_int  ,
u_int  ,
Vbx *  ,
int  ,
AgentXSharedTable ,
u_int  ,
Oidx *   
)
inlinevirtual

This method is being called, whenever an index deallocation has been processed by the master and the result has been returned to the subagent.

Parameters
erroran AgentX error code if the index deallocation failed, or 0 if it has been completed successfully.
errorIndexif error is not 0, errorIndex points to the index object within the index that actually failed (starting from 1).
vbsan array of index objects.
sizethe size of the above array.
sharedTablea pointer to an AgentXSharedTable instance that initiated the index deallocation. If the index deallocation was not initiated by an AgentXSharedTable instance this pointer will be 0.
packetIDthe packet ID of the AgentX request that send the allocation PDU. This value can be used to associate any objects with the (asynchronous) index allocation request.
rowIndexthe row index originally provided to the allocation request.
virtual bool SubAgentXMib::init ( )
virtual

Initialize the sub-agent by opening a session with the master agent and registering all MIB objects already added to the receiver.

Returns
TRUE if connection to master could be established, FALSE otherwise.
virtual void SubAgentXMib::init_response_pool ( )
protectedvirtual

Create and initialize response pool and queue.

virtual void SubAgentXMib::not_connected ( )
protectedvirtual

This method is called when an attempt has been made to send an AgentX message to the master agent.

The default implementation logs a warning message only.

virtual int SubAgentXMib::notify ( const NS_SNMP OctetStr &  ,
const Oidx &  ,
Vbx *  ,
int  ,
unsigned  int = 0 
)
virtual

Send a notification.

Parameters
contextthe context originating the notification ("" for the default context).
trapoidthe oid of the notification.
vbsan array of variable bindings.
sizethe size of the above variable binding array.
timestampan optional timestamp.
Returns
SNMP_ERROR_SUCCESS.
virtual int SubAgentXMib::open_session ( )
virtual

Open session.

virtual unsigned long SubAgentXMib::ping_master ( )
virtual

Send a ping PDU to the master agent to monitor the master agent's ability to receive and send AgentX PDUs over their AgentX session.

Returns
a transaction id to match ping requests to responses later.
virtual void SubAgentXMib::ping_received ( const AgentXPdu )
virtual

This method is called when this subagent received a PING response from its master.

Parameters
pduthe AgentX PDU containing the response for the ping.
virtual void SubAgentXMib::process_response ( AgentXRequest )
protectedvirtual

Process an AgentX response.

Parameters
reqa request.
virtual void SubAgentXMib::reconnect ( )
virtual

(Re)Connect with the master.

Allocates regions for the objects of this Mib instance and also allocates indexes and rows of shared tables.

virtual MibEntry* SubAgentXMib::register_entry ( const NS_SNMP OctetStr &  ,
MibEntry *  ,
u_int   
)
virtual

Register a MIB object within a given context at the master.

If the given context is a new context, it will be added to the list of known contexts. Note that the subagent's connection to the master must be established before this method is called, otherwise this method will return 0.

Note: This method is synchronized using ::lock_mib()

Parameters
contextan OctetStr instance specifiying the target context.
itema pointer to a MibEntry object (i.e., MibLeaf, MibTable, MibGroup, ...).
timeoutthe entry's (region's) timeout value.
Returns
the input pointer if the MibEntry could be registered, or 0 otherwise.
virtual bool SubAgentXMib::register_region ( const NS_SNMP OctetStr &  ,
const AgentXRegion ,
u_int  timeout,
bool  ,
AgentXSharedTable t = 0 
)
virtual

Register a region at the master agent.

Parameters
contextthe context.
regionan AgentXRegion instance.
timeoutthe regions timeout value or 0 for using the sessions timeout value.
modeif TRUE the region is registered at the master, if FALSE the region is deregistered.
referencea pointer to an AgentXSharedTable instance that initiates the registration. If the registration attempt is initiated by any other MIB object instance, then this paramter should be set to 0 or omitted.
Returns
TRUE if the registration message has been successfully sent, FALSE otherwise.
virtual void SubAgentXMib::registration_failed ( const AgentXRegion ,
int  ,
AgentXSharedTable  
)
inlinevirtual

Registration failed.

This method is called when a registration attempt failed.

Parameters
regionthe region.
errorStatusthe error status of the attempt.
referencea pointer to the AgentXSharedTable instance that initiated the registration. This parameter is 0 for other registrations.
virtual void SubAgentXMib::registration_success ( const AgentXRegion ,
AgentXSharedTable  
)
virtual

Registration success.

This method is called when a registration attempt succeeded.

Parameters
regionthe region.
referencea pointer to the AgentXSharedTable instance that initiated the registration. This parameter is 0 for other registrations.
virtual bool SubAgentXMib::remove ( const Oidx &  )
virtual

Unregister a MIB object from the agent's MIB.

This method now (>3.3) works for MibGroups, too.

Note: This method is synchronized. It first acquires ::mib_lock(), then searches for the target MIB object and then acquires target::start_synch(). Then it RELEASES the MIB object lock by calling target::end_synch(). The target object is deleted and the MIB lock is released.

Why is this save?

  • we hold the lock for the MIB (lock_mib())
  • before a request can lock a MibEntry object it must get the MIB lock
  • so if we get the MibEntry lock here no other request can be currently using this object
  • even if we release the lock, because we hold the MIB lock
Parameters
oidthe Oidx instance pointing to the key of the MibEntry to be removed.
Returns
TRUE if the entry could be removed, FALSE otherwise
virtual bool SubAgentXMib::remove ( const NS_SNMP OctetStr &  ,
const Oidx &   
)
virtual

Unregister a MIB object from the agent≥s MIB.

This method now (>3.3) works for MibGroups, too.

Note: This method is synchronized. It first acquires ::mib_lock(), then searches for the target MIB object and then acquires target::start_synch(). Then it RELEASES the MIB object lock by calling target::end_synch(). The target object is deleted and the MIB lock is released.

Why is this save?

  • we hold the lock for the MIB (lock_mib())
  • before a request can lock a MibEntry object it must get the MIB lock
  • so if we get the MibEntry lock here no other request can be currently using this object
  • even if we release the lock, because we hold the MIB lock
Parameters
contextan OctetStr instance specifiying the target context.
oidthe Oidx instance pointing to the key of the MibEntry to be removed.
Returns
TRUE if the entry could be removed, FALSE otherwise
virtual void SubAgentXMib::remove_agent_caps ( const NS_SNMP OctetStr &  ,
const Oidx &   
)
virtual

Add agent capabilities to the sysORTable of the master.

Parameters
contexta context. Use "" for the default context.
idan object identifier containing the value of sysORID that should be no longer exported.
virtual bool SubAgentXMib::remove_no_unreg ( const Oidx &  )
virtual

Unregister a MIB object from the agent's MIB, but do not unregister it with the master.

Use this method when the object to be removed has been registred by add_no_reg().

Parameters
oidthe Oidx instance pointing to the key of the MibEntry to be removed.
Returns
TRUE if the entry could be removed, FALSE otherwise
virtual bool SubAgentXMib::remove_no_unreg ( const NS_SNMP OctetStr &  ,
const Oidx &   
)
virtual

Unregister a MIB object from the given context, but do not unregister it with the master.

Use this method when the object to be removed has been registred by add_no_reg().

Parameters
contextan OctetStr instance specifiying the target context.
oidthe Oidx instance pointing to the key of the MibEntry to be removed.
Returns
TRUE if the entry could be removed, FALSE otherwise
void SubAgentXMib::remove_pending_messages ( MibEntry *  )
protected

Remove pending messages for a MibEntry instance.

Parameters
entrya pointer to a MibEntry instance.
void SubAgentXMib::set_default_priority ( const u_char  p)
inline

Set the default priority for registrations by this sub-agent.

Parameters
prioritya value between 0 and 255 (default is 127).
void SubAgentXMib::set_request_list ( AgentXRequestList )

Set the RequestList to be used for answering request.

Note: The request list is NOT deleted by the receiver's destructor. This should be done outside class Mib.

Parameters
requestListan AgentXRequestList instance with its agentx protocol service set. (If the agentx protocol service is not set, this will end program execution)
virtual void SubAgentXMib::synchronize_uptime ( u_int  )
protectedvirtual

Synchronize local sysUpTime with the given time.

Parameters
timethe 1/100 seconds since the master system started.

Friends And Related Function Documentation

friend class AgentXResponse
friend

Member Data Documentation

AgentXSlave* SubAgentXMib::agentx
staticprotected
AgentXIndexDB* SubAgentXMib::indexRegistry
protected
List<AgentXPendingMessage> SubAgentXMib::pendingMessages
protected
Synchronized SubAgentXMib::pendingMessagesLock
protected
u_char SubAgentXMib::priority
protected
QueuedThreadPool* SubAgentXMib::responsePool
protected
AgentXSession* SubAgentXMib::session
protected
agentx_run_status_t SubAgentXMib::status
protected

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