CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
SNMP
CapeSoft Logo

CapeSoft NetTalk
SNMP

Download Latest Version
Installed Version Latest Version

Using the NetSNMP Object

Introduction

A NetSNMP object allows you to use SNMP (Simple Network Management Protocol) in your application. SNMP is a Management Protocol for sending and receiving information across a network. There's no limit as to what it can be used for, but typically it's for talking to hardware devices like routers or power-supplies etc.

Some basics first:
SNMP Management Station - This is the 'client' part of SNMP, it requests information from the Agent.
SNMP Agent - This is the 'server' part of SNMP. It sends back information as responses to the Management Station.
Traps - These are exceptions from the normal client / server model. This allows an Agent to post a warning message to a Management Station. For example your UPS may post a warning message to your machines telling them that they must shutdown as the batteries are almost flat.
MIB (Management Information Base) : This is just a fancy name for the list of data that is stored on the Agent.

There are three operations that a Management Station can initiate, namely:
GetValue() : get a value of a variable from the Agent
GetNextValue() : get the value of the "next" variable on the Agent
SetValue() : set a value on the Agent
These operations involve sending an SNMP packet to the Agent requesting that the operation is performed. The Agent will send back a response with the result in it.

Apart from sending back responses, an Agent can also initiate a trap (message) to the Management Station:
SendTrap() : send a trap to a management station. There are several things that are useful to know before starting to use SNMP:
  1. ) SNMP runs over UDP (different from TCP).
  2. The variables that the management station gets and sets on the agent are stored in a special kind of database on the agent, namely a Management Information Base (MIB). This is implemented as the self.qIBEntries queue on the Agent. The variables in this queue actually all belong to a tree, with the first couple of nodes looking like this:
    SNMP tree For example: interfaces would be .1.3.6.1.2.1.2 (starting at the root, each dot indicates that you go down a level in the tree and each integer is the number of a node you pass through)

    Each node can be represented in two ways: either by the name given at the node (for example interfaces) or by a series of integers separated by dots indicating it position in the tree. The latter (.1.3.6.1.2.1.2) is called an object identifier and is usually written without the leading dot (i.e. interfaces is 1.3.6.1.2.1.2). Notice that all elements in a subtree of the above tree will have the beginning of their names exactly matching the name of the root of the subtree.

    The tree can be represented as a list of (variable) names by ordering the object identifiers from top to bottom and from left to right. So the above tree will give rise to the following list:

    0
    1
    1.3
    1.3.6
    1.3.6.1
    1.3.6.1.1
    1.3.6.1.2
    1.3.6.1.2.1
    1.3.6.1.2.2
            ...
    1.3.6.1.2.7
    1.3.6.1.3
    1.3.6.1.4
    1.3.6.1.4.1
    2

    This is how the variables in the agent's MIBEntries queue should be organized. From this it is clear what is meant by the next variable after a given variable. 

    So how do we add more nodes (variables, object identifiers) to this tree (list)? This is done by loading MIB files into the tree. They are basically text files containing descriptions of new nodes (usually they are referred to as objects in this context) and where in the tree they belong. If we take the root to be level zero, then the above tree up to and including level 6 is actually an MIB file called RFC1155-SMI.mib whereas the remaining subtree below mgmt is RFC1213-MIB.mib.
  3. Every agent/management station belongs to one or more SNMP communities, which is basically just a group of network elements. Each agent stores a list of these community names, the MIB variables that members of each community are allowed to access in the first place (called their MIB View) and the access rights the members have to these MIB variables (Read-Only or Read-Write). One entry in this list is called a Community Profile and the list is implemented as the CommunityProfiles queue.
  4. As mentioned above, for every agent the MIB View of a community is a subset of the agent's MIB that members of that community are allowed to access. In fact, it is a collection of subtrees of the MIB that they are allowed to access. This information is stored in the MIBViews queue: for each subtree in a community's view, the root of the subtree is stored alongside the community name in this queue.
  5. Windows XP: Note that in the case that you are running Windows XP, you can run a Windows XP SNMP service on your computer. When this SNMP service is running, it behaves as an SNMP agent and maintains a MIB with all variables relevant to your computer. To run this service, take the following steps:
    1. Go to Control Panel, then to Administrative Tools and then run the Computer Management program.
    2. Click on Services and Applications, and then on Services.
    3. If SNMP is already installed on you computer, you can should be able to scroll down the list until you find SNMP Service. There will be an option to start the service - click this to start the SNMP agent on your computer.
    If there is no SNMP Service entry, SNMP has not yet been installed on your computer. To install it, follow the steps below. Note that you need to be an Administrator to perform the below actions.

    1. 1) Go to Control Panel, then to Add or Remove Programs and click on the Add or Remove Windows Components button.
    2. Click on Management and Monitoring Tools without selecting or deselecting the checkbox, and click details.
    3. Select the Simple Network Management Protocol checkbox and click OK.
    4. Click Next, and follow the rest of the steps.
When the installation is complete, SNMP will automatically start running on your computer.

NOTE: You can not run more than one SNMP application on the same ports at the same time on a single computer. By default SNMP applications use ports 161 and 162. So for example to run the netdemo.app SNMP example you would need to either change the ports that the demo runs on or stop your Windows XP SNMP Service.

JumpStart

This section exists to get you going quickly. You'll need to read the rest of the documentation to access all the other features and functionality of SNMP, but if you follow the following instructions you can get SNMP going in your application in 10 minutes.

Code Example:
There is a copy of this Jumpstart example in your example folder on your machine. See Clarion/3rdParty/Examples/NetTalk
SNMP jumpstart

Objectives of this Quick Start for SNMP:

Instructions:

  1. Add the "Activate_NetTalk" Global Extension to your application.
  2. Add a window to your application. This will be the window you want the SNMP to be activated from. Add the following to your window:
    • An entry, populated from a string(80)called IPAddress (in the Local Data)
    • Another entry, populated from a string(255)called Community (in the Local Data)
    • A listbox, populated as follows:
      • Populate it from a queue called ResultQueue
      • This queue should have three fields,  Name string(255), Description string (1024) and Value string(255)
      • Add these three fields to the listbox as columns
    • Add a string to the window called Status with a use variable of ?Status
    • Add a long to the local data called timercount
    • Add a timer to the window, set to go off every 100 hundredths of a second
    • Add a button "Get Info" use ?GetInfo
  3. Add the NetTalk procedure extension "IncludeNetTalkObject" to the window in your application that you want to access SNMP from. Set the ObjectName to MyNetSNMP, the Base Class to NetSNMP.
  4. Insert the following into the Accepted embed code of the ?GetInfo button:
    !Clear the current list of retrieved MIB variables and start collecting the new MIB

    free(ResultQueue)
    ?Status{prop:text} = 'Retrieving the MIB Summary Info ...'
    MySNMP.requestID = 1
    MySNMP.packet.ToIP = IPAddress
    MySNMP.community = community
    !Set the starting position to 0.0 - this comes before any variable name that you will ever find in an MIB
    free(MySNMP.qVarBindList)
    MySNMP.qVarBindList.name = '1.3.6.1.2.1.1'
    ! Start here
    add(MySNMP.qVarBindList)
    timercount = 1
    MySNMP.GetNextValue()
  5. Insert the following code into the MyNetSNMP.ErrorTrap() embed:
    ! An error occurred before we could send out the request
    ! SupressErrorMessages is on, so display the error in the
    ! status string and switch the timer off

    timercount = 0
    ?Status{prop:text} = 'Error - ' &clip(errorStr)

     
  6. Insert the following code into the timer event embed:
    ! First check whether the timer is 'switched on',
    ! i.e. whether a getnext packet has been sent out
    if timercount > 0
     
    ! If so, increment the timer
     
    timercount += 1
     
    ! if we have waited for more than a second, we probably wont receive a reply at all
     
    if timercount = 3
        timercount = 0
        ?Status{prop:text} = 'Timed out - no SNMP response received'
      end
    end
  7. Insert the following code into the ThisWindow.init() embed after the MySNMP.Init has been called: MySNMP.open()

    ! The read community for whatever SNMP agent we are querying will probably be the following:
    community = 'public'
    IPAddress = 'localhost'

    ! ----------------------------------------------------------------------------------
    ! Load the Description Map with some descriptions.
    ! This means when you get data from an agent you can see Descriptions for the Data
    ! Not just the dot notation numbers.
    ! In your application you'll want to add your own here
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.1.0', 'A textual description - should include full name and version of the system''s hardware type, software operating-system, and networking software.')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.2.0', 'The vendor''s authoritative identification of the network management subsystem contained in the entity. This value is allocated within the SMI enterprises subtree (1.3.6.1.4.1) and provides an easy and unambiguous means for determining ''what kind of box'' is being managed. For example, if vendor ''Flintstones, Inc.'' was assigned the subtree 1.3.6.1.4.1.4242, it could assign the identifier 1.3.6.1.4.1.4242.1.1 to its ''Fred Router''')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.3.0', 'The time (in hundredths of a second) since the network management portion of the system was last re-initialized.')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.4.0', 'A textual description of the contact person for this managed node, together with his contact information.')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.5.0', 'An administratively-assigned name for this managed node. By convention, this is the node''s fully-qualified domain name.')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.6.0', 'The physical location of this node (e.g. ''telephone closet, 3rd floor'').')
    MySNMP.DescriptionMapAdd ('1.3.6.1.2.1.1.7.0', 'A value which indicates the set of services that this entity primarily offers.')

    ! ----------------------------------------------------------------------------------

    display()
    ! Load the community profiles list with some values
    MySNMP.qCommunityProfiles.CommunityName = 'public'
    MySNMP.qCommunityProfiles.Permission = NetSNMP:ReadOnly
    add(MySNMP.qCommunityProfiles)
    MySNMP.qCommunityProfiles.CommunityName = 'private'
    MySNMP.qCommunityProfiles.Permission = NetSNMP:ReadWrite
    add(MySNMP.qCommunityProfiles)
    ! Load the MIB with some arbitrarily chosen values, in case you decide to query yourself
    ! This is for if there is no SNMP agent running on the network
    MySNMP.qMIBENtries.name = '1.3.6.1.2.1.1.1.0'
    MySNMP.qMIBENtries.valuetype = NetSNMP:String
    MySNMP.qMIBENtries.access = NetSNMP:ReadOnly
    MySNMP.qMIBENtries.status = NetSNMP:Mandatory
    MySNMP.qMIBENtries.description = 'A textual description - should Include full name and version of the system''s hardware type, software operating-system, and networking software.'
    MySNMP.qMIBENtries.value = '(Example Data) Hardware: x86 Family 6 Model 6 Stepping 5 AT/AT COMPATIBLE - Software: Windows 2000 Version 5.0 (Build 2195 Uniprocessor Free)'
    add(MySNMP.qMIBENtries)

    MySNMP.qMIBENtries.name = '1.3.6.1.2.1.1.3.0'
    MySNMP.qMIBENtries.valuetype = NetSNMP:TimeTicks
    MySNMP.qMIBENtries.access = NetSNMP:ReadOnly
    MySNMP.qMIBENtries.status = NetSNMP:Mandatory
    MySNMP.qMIBENtries.description = 'The time (in hundredths of a second) since the network management portion of the system was last re-initialized.'
    MySNMP.qMIBENtries.value = 0
    add(MySNMP.qMIBENtries)

    MySNMP.qMIBENtries.name = '1.3.6.1.2.1.1.4.0'
    MySNMP.qMIBENtries.valuetype = NetSNMP:String
    MySNMP.qMIBENtries.access = NetSNMP:ReadWrite
    MySNMP.qMIBENtries.status = NetSNMP:Mandatory
    MySNMP.qMIBENtries.description = 'A textual description of the contact person for this managed node, together with his contact information.'
    MySNMP.qMIBENtries.value = '(Example Data) Agent Smith, Software Engineer, CapeSoft, South Africa. email: agentsmith@capesoft.com'
    add(MySNMP.qMIBENtries)

    MySNMP.qMIBENtries.name = '1.3.6.1.2.1.1.5.0'
    MySNMP.qMIBENtries.valuetype = NetSNMP:String
    MySNMP.qMIBENtries.access = NetSNMP:ReadWrite
    MySNMP.qMIBENtries.status = NetSNMP:Mandatory
    MySNMP.qMIBENtries.description = 'The physical location of this node (e.g., telephone closet, 3rd floor).'
    MySNMP.qMIBENtries.value = 'Top floor CapeSoft Office.'
    add(MySNMP.qMIBENtries)

    ! Load the qMIBViews queue with some arbitrary values
    MySNMP.qMIBViews.CommunityName = 'public'
    MySNMP.qMIBViews.subtree = '1.3.6.1.2.1'
    add(MySNMP.qMIBViews)

    MySNMP.qMIBViews.CommunityName = 'private'
    MySNMP.qMIBViews.subtree = '1.3.6.1.2.1.1.5'
    add(MySNMP.qMIBViews)

    MySNMP.qMIBViews.CommunityName = 'private'
    MySNMP.qMIBViews.subtree = '1.3.6.1.2.1.1.4'
    add(MySNMP.qMIBViews)
  8. Insert the following into the MyNetSNMP.ProcessResponse() method code embed:
    !Since we have received an SNMP reply, we can switch off the timer

    timercount = 0
    !First check that the received packet has the same request ID as the one we sent out
    if self.requestID <> 1
      ?Status{prop:text} = 'Unexpected SNMP packet was received - discarded'
      display()
      return
    end

    if self.errorstatus = NetSNMP:NoError
     
    ! If no error occurred, we have received the next variable and it's value
      ! So put the received value in the resultqueue and request the
      ! variable following this one in the MIB
      get(self.qVarBindList, 1)
      if errorcode()
        ?Status{prop:text} = 'Error accessing the received data'
        display()
        return
      end
      ResultQueue.Name = self.qVarBindList.Name
      ResultQueue.Value = self.qVarBindList.Value
      ResultQueue.Description = self.qVarBindList.DescriptionIn
      add(ResultQueue)
      display()

      if ResultQueue.Name < '1.3.6.1.2.1.1.7'
        self.packet.ToIP = IPAddress
        self.packet.fromIP = IPAddress
        self.packet.UDPToPort = 161
        timercount = 1
        self.GetNextValue()
      else
        ?Status{prop:text} = 'Done'
        display()
        return
      end
    elsif self.ErrorStatus = NetSNMP:NoSuchName
     
    ! If we get a nosuchname error, it means we have reached the end of the MIB
      ?Status{prop:text} = 'Done'
      display()
    elsif self.ErrorStatus = NetSNMP:GenErr
     
    ! Some general error might have occurred on the agent
      ?Status{prop:text} = 'A general error occurred on the agent'
      display()
    else
      ! Any other error message has no meaning in this (getnext) context
      ?Status{prop:text} = 'An unknown error occurred on the agent'
      display()
    end
  9. Run your application. (NB. There will need to be some machine or other network element on your network that is running SNMP. The best would be to use a computer on the network that has Windows XP installed and is running the SNMP service as is explained in the The NetSNMP Object section, point number 5. You need to enter this machine's IP Address and the relevant read-community (this is usually 'public') before pressing the button).

SNMP Structures

NetSNMP:DescriptionMapType Queue, Type
Name String (256) The object identifier of the MIB entry (name of the MIB variable).
Description String (1024) A text string describing the MIB variable. Usually this tells you more about the variable, it's function, etc
NetSNMP:MibQueueType Queue, Type
Name String (256) The object identifier of the MIB entry (name of the MIB variable).
ValueType long The type of value that the MIB entry holds. See the Equates section.
Access string(20) Access Permission to the MIB variable. This restricts the actions that any network element may perform on the variable. This can be one of:
  • NetSNMP:ReadOnly
  • NetSNMP:ReadWrite
  • 'NetSNMP:WriteOnly
  • NetSNMP:NotAccessible
Status string(20) This is the implementation status of this object. It can be one of:
  • NetSNMP:Mandatory
  • NeSNMP:Optional
  • NetSNMP:Deprecated
  • NetSNMP:Obsolete
Description  String (1024) A text string describing the MIB variable. Usually this tells you more about the variable, it's function, etc.
Value String (256) The actual value of the variable. The value may be a long, ulong or string, depending on the ValueType.
BSsize long In the case that the ValueType is a bitstring, this holds the length of the bitstring in bytes.
BSbits long In the case that the ValueType is a bitstring, this holds the number of unused bits in the last byte of the bitstring.
NetSNMP:ComProfileQueueType Queue, Type
CommunityName String (128 The name of the community.
Permission long The access permission any member of the above community has to it's MIB view on the agent (the collection of subtrees of the MIB that it is allowed to access). This can be one of NetSNMP:ReadOnly or NetSNMP:ReadWrite.
NetSNMP:MIBViewsQueueType Queue, Type
CommunityName  String (128) The name of the community. This name may appear more than once - once for every subtree of the MIB that members of this community are allowed to access.
SubTree String (256) The object identifier of the root of the subtree in this MIB view.
As an example, if 'Public' was the name of a community that was allowed access to subtrees with roots 1.3.6.1.2.1.1 and 1.3.6.1.2.1.2 then there would be two entries for 'Public' in this queue, namely ('Public', '1.3.6.1.2.1.1') and ('Public', '1.3.6.1.2.1.2').
NetSNMP:VarBindListType Queue, Type
Name String (256) The object identifier (name) of the MIB variable.
ValueType long The type of value that this Variable Bindings List entry holds. See the Equates section.
Value String (256) The actual value of the variable. This may be a long, ulong or string, depending on the ValueType
BSsize Long In the case that the ValueType is a bitstring, this holds the length of the bitstring in bytes.
BSbits Long In the case that the ValueType is a bitstring, this holds the number of unused bits in the last byte of the bitstring.
Description String (1024) A text string describing the MIB variable. Usually this tells you more about the variable, it's function, etc.

SNMP Equates

NetSNMP:BitString A string of bits (zeroes and ones). In this implementation this is stored in a usual string with each individual bit in the bitstring being represented by the corresponding bit in the string.

For example, if our bitstring is 11101001101 and our usual clarion string that holds this is bstring then we would set
bstring[1] = chr(11101001b) and
bstring[2] = chr(101b).

Since there might be some trailing zeroes at the end of a bitstring that are relevant, it is important that the length in bytes that the bitstring takes up as well as the number of unused bits in the last byte are recorded.

NetSNMP:Counter This is a value used to represent a count. It is stored in a long and can have a value from 0 to 2e32 - 1.
NetSNMP:Gauge This is a non-negative integer (stored in a long) having a value that may range between 0 and 2e32 - 1. Usually however, there are maximum and/or minimum values for this range and whenever the value goes above or below these limits the maximum/minimum value is maintained.
NetSNMP:Integer This is just the usual integer (stored in a long) with a value ranging from -2e31 to 2e31- 1.
NetSNMP:IPAddress This is just a usual IP address stored in a usual Clarion string e.g. myIpAddress = '196.2.141.67'
NetSNMP:NetworkAddress This is the same thing as NetSNMP:IPAddress, although it was initially intended to store any type of network address.
NetSNMP:Null The value of the involved variable is null.
NetSNMP:ObjectIdentifier Indicates that the value of the variable is an object identifier, i.e. a name of a variable in the MIB. This is stored in a usual Clarion string. Currently this implementation only supports object identifiers that are written in dot notation with integers only, i.e. 1.3.6.1.2.1.2 is an acceptable object identifier but interfaces is not, although they refer to the same object.
NetSNMP:Opaque Used to specify octets (bytes) of binary information. Stored in a usual Clarion string.
NetSNMP:String (also called an OCTETSTRING in SNMP) This is the same as the usual string in clarion.
NetSNMP:TimeTicks This is a non-negative integer ranging from 0 to 2e32 - 1 stored in a long. It is used to specify the time between two events in one-hundredths of a second.

NetSNMP Properties

AgentAddr String(128) This should be set before SendTrap() is called, and is given a value when a trap packet is received in ProcessTrap(). It is the network address of the network element that generated the trap.
Community String(128) This should be set to the name of an appropriate SNMP community to which this object (network element) belongs before a GetValue(), SetValue(), or GetNextValue() operation is performed. If the object belongs to more than one community, the community name that will give it the required access rights to perform the desired operation should be included. 
qCommunityProfiles Queue (NetSNMP:ComProfilesQueueType) This is a list of community profiles on the agent. Each community name is specified in this queue together with an  MIBView name (which is a collection of subtrees that a member of this community may access) and an access permission (which indicates whether a member of this community has read or write access to variables in the MIBView). For more details see NetSNMP:ComProfilesQueueType and the MIBViews property.
 
Enterprise String(128) This should be set before SendTrap() is called, and is given a value when a trap packet is received in ProcessTrap(). This is an object identifier under whose registration authority this trap is defined (for enterprise specific traps).
 
ErrorIndex long This is given a value when a response to a GetValue(), GetNextValue() or SetValue() is received from an agent. If ErrorStatus is zero, this will be too. If an error that occurred on the agent and was caused as a result of a specific entry in the VarBindList, ErrorIndex will contain the position of that variable in the list. Otherwise ErrorIndex will be zero.
 
ErrorStatus long This is given a value when a response to a GetValue(), GetNextValue() or SetValue() is received from an agent, and the best place where this value can be obtained is in the ProcessResponse() procedure. If this has a value other than 0 (NetSNMP:NoError) then the requested operation was not performed on the agent. It's value will be one of the following:
  • NetSNMP:NoError -  If no error occurred on the agent during the operation.
  • NetSNMP:tooBig - The response that would have been sent back from the agent if the operation had been performed would have exceeded the agent's maximum packet size.
  • NetSNMP:NoSuchName - One of the variables that this object wanted to access on the agent had a name that was not in this Object's MIBView on the agent (this may mean that either this object was not allowed the required access to this variable or that no variable with such name exists).
  • NetSNMP:BadValue - This object tried to set a variable on the agent with a value that was an incorrect ValueType.
  • NetSNMP:ReadOnlyErr - This object tried to set a variable in the agent's MIB that had read-only access.
  • NetSNMP:GenErr - An error occurred on the agent that was none of the above.
In the case of NoSuchName, ReadOnlyErr and BadValue, ErrorIndex will be set to the position in the VarBindList of the variable that caused the error.
GenericTrap long This should be set before SendTrap() is called, and is given a value when a trap packet is received in ProcessTrap(). This will be one of:
  • NetSNMP:coldStart - Indicates that the sending agent is going to reinitialize itself such that the agent's configuration will change
  • NetSNMP:warmStart - Indicates that the sending agent is going to reinitialize itself but that the agent's configuration will not change
  • NetSNMP:linkDown - The agent has recognized a failure in one of its communication links. The first entry of the VarBindList will contain the name and value of IfIndex for the affected interface (this is a variable in the rfc1213-MIB).
  • NetSNMP:LinkUp - Indicates that one of the agent's communication links have come up. The first entry of the VarBindList will again contain the name and value of IfIndex for the affected interface (this is a variable in the rfc1213-MIB).
  • NetSNMP:AuthFailure - Indicates that the agent failed to authenticate an SNMP message that it received from this object.
  • NetSNMP:egpNeighbourLoss - Signifies that the agent who sent the trap has had one of its EGP neighbors to which it was a peer marked down.
  • NetSNMP:enterpriseSpecific - Indicates that the trap was enterprise specific (depends on the implementation). SpecificTrap will contain more information about the trap.
qMIBEntries Queue (NetSNMP:MIBQueueType) This queue is intended to contain all of the variables in this particular agent's MIB. The variables should be ordered in this queue as was explained earlier in the The NetSNMP Object section. When an agent receives a request to get or set an MIB variable, this is where the variable and it's value is obtained or changed. See NetSNMP:MIBQueueType for a complete description of the queue fields.
 
qMIBViews Queue (NetSNMP:MIBViewsQueueType) This is a list of SNMP communities and the subtrees of the agent's MIB that members of the community may access. If a view contains more than one subtree, the Name of the view appears once next to each subtree in this queue (i.e. for each subtree there is a separate entry in this queue). For More details see NetSNMP:MIBViewsQueueType and CommunityProfiles.
 
RequestID long This should be assigned a number before a GetValue(), SetValue or GetNextValue() operation is performed on an agent. When a request to perform this operation is sent to the agent, the response the agent sends back contains this exact same RequestID to identify which request the response is to.
 
SendAuthFailureTrap byte If this is set to true, an authentication failure trap will be sent when authentication on a received SNMP message fails. Otherwise no trap will be sent.

This field is meant for use on an SNMP agent.
 

SNMPVersion long The version of SNMP that is being used. Although there are three SNMP versions, this implementation currently only supports SNMP version one and hence this should be set to zero (not one).
 
SpecificTrap long This should be set before SendTrap() is called, and is given a value when a trap packet is received in ProcessTrap(). If GenericTrap has a value of NetSNMP:enterpriseSpecific, this will contain a value indicating what kind of trap this is (this depends on the implementation).
 
TimeStamp long This should be set before SendTrap() is called, and is given a value when a trap packet is received in ProcessTrap(). It is the time that had elapsed in one hundredths of a second between the last initialization of the network management system of the element that generated the trap and the generation of the trap.
 
ToPort long The port to which all SNMP packets to an agent except traps will be sent. This is set to port 161 as default as this is the port number specified in the SNMP specification.
 
TrapToPort long The port to which all SNMP Trap packets to an agent will be sent. This is set to port 162 as default as this is the port number specified in the SNMP specification.
 
qVarBindList Queue (NetSNMP:VarBindListType) This is the variable bindings list of this object. Essentially it is a list of MIB variable names and their corresponding values. It needs to be filled in before doing a GetValue(), GetNextValue(), SetValue() or SendTrap() operation and will be filled with information from a received SNMP packet which can then be accessed in the ProcessResponse() and ProcessTrap() procedures. See NetSNMP:VarBindListType for a complete description of the fields.
 

SNMP Methods

This is similar to GetValue(), and the properties that have to be set are exactly the same. This procedure is generally used for retrieving tables from the MIB of the agent.
The result is still received in ProcessResponse(). The variable names and values in the VarBindList are those of the first variables in the agent's MIB in the sender's MIB View following the ones that were originally entered into the VarBindList when the request was sent (see the The NetSNMP Object section to see what "after" means).
It may however be the case that no reply is received if a "serious" error occurs on the agent's side (for example, it doesn't support SNMP or the given community string is invalid).
CheckAuthenticity (), byte This checks the authenticity of the received SNMP message. If you want to implement any authentication scheme other than trivial authentication (all messages are considered authentic), your code should be placed in this procedure. Otherwise none is necessary. The idea is to check whether the network element that sent the packet does in fact belong to the Community whose name was included in the packet.

When this procedure is called the SNMPVersion and Community properties will already have been extracted and given their values and the packet will only contain the remaining part of the SNMP message that was received. The packet will contain the IP address of whoever sent the packet (self.packet.ToIP). The value returned is 1 if authentication was successful (default), and 0 otherwise.

This procedure is called automatically when an SNMP packet is received and the Process() procedure will receive the result and react accordingly.

Close () Closes any ports that are opened for listening for SNMP responses and traps.
DescriptionMapAdd (string p_Name, string p_Description) Adds items to the .qDescriptionMap queue.
GetValue ()

This procedure attempts to get the values of the variables specified in the VarBindList from the agent whose IP address is specified in the packet.

Before calling this procedure, the SNMPVersion, RequestID and Community properties should be set. The VarBindList should contain the Names of all the variables that you want to get, but their values do not matter. The usual NetSimple properties required to send a packet should also be set.

The result is received in the ProcessResponse() procedure. It may however be the case that no reply is received if a "serious" error occurs on the agent's side (for example, it doesn't support SNMP or the included community string is invalid).

GetNextValue ()
Open (ushort port = 161, ushort trapPort = 162) Port is the port that the object will listen on for Response packets, and TrapPort is the port it will listen on for Trap packets. It is recommended that the default ports are used as they are the ones specified in the SNMP specification. Opens ports Port and TrapPort for listening for SNMP packets.
ProcessResponse () This is where the result of a GetValue(), SetValue() or GetNextValue() operation becomes available. If you intend doing anything with the received information you must place your code to do that in here.
The RequestID will contain the value of the RequestID that was set when the original GetValue(), SetValue() or GetNextValue() operation was performed. If no error occurred, the ErrorStatus and ErrorIndex properties will be zero, otherwise they will contain the received values indicating the nature of the error.

If no error occurred, the VarBindList will contain the following values:
  1. For a response to a get operation, the VarBindList will contain the Names and Values of the requested variables
  2. For a response to a set operation, the VarBindList will look exactly the same as it did when the request to set the variables was sent off, except that ErrorStatus and ErrorIndex may contain values other than zero.
  3. For a response to a getnext operation, the VarbindList will look as is explained in the GetNext() procedure section.
ProcessTrap () Whenever a Trap packet is received by this object, this is where the received information becomes available. If you intend doing anything with the received information you must place your code to do that in here.

The Enterprise, AgentAddr, GenericTrap, SpecificTrap and TimeStamp properties will all contain the values received. The VarBindList will possibly be empty or will contain information that the agent considered to be useful, depending on the kind of trap that was generated (as indicated by GenericTrap).
SendTrap () This procedure is used by an agent to send a Trap packet to the management station (whose IP address is specified in the packet) to inform it that an important event has occurred.

Before calling this procedure, the SNMPVersion and Community properties should be set. The Enterprise, AgentAddr, GenericTrap, SpecificTrap and TimeStamp properties should also be set. The VarBindList is meant to contain information that may be interresting to the receiving entity.

The trap will be received by the management station in the ProcessTrap() procedure.
SetValue () This procedure attempts to set the values of the variables specified in the VarBindList on the agent whose IP address is specified in the packet.

Before calling this procedure, the SNMPVersion, RequestID and Community properties should be set. The VarBindListshould contain the Names of all the variables that you want to set, and the corresponding Values that you want to set them to. The ValueType fields in the VarBindList should match the ValueType fields of the variables in the agent's MIB (see Equates). The usual NetSimple properties required to send a packet should also be set.

A response is sent from the agent to indicate the level of success and is received in the ProcessResponse() procedure. It may however be the case that no reply is received if a "serious" error occurs on the agent's side (for example, it doesn't support SNMP or the given community string is invalid).
[End of this document]
Return to NetTalk Documentation Index