pbsw-code.net : pbsw-SNMP

pbsw-SNMP

A set of classes for sending and receiving SNMP (Simple Network Management Protocol) messages. Includes BER (Basic Encoding Rules) encoding/decoding. (Does not currently include MIB parsing).

Handles SNMPv1 Get-Request, Get-Next-Request, and Set-Request PDUs.

Can encode and decode the following BER types: Sequence, Integer, Octet String, Object Identifier, Ip Address, Counter, Gauge, TimeTicks, Opaque, NULL

Requires: REALbasic 5.2.1 (has not been tested on other versions)

WARNING: an understanding of SNMP is required to use these classes! If you do not know exactly what you are doing, you can cause problems with the equipment you are sending SNMP messages to (especially if you are using SNMP Set messages!). You should only be using this code (and programs made with this code) on equipment that is your responsibility to manage, and your responisbility to fix if the configuration is messed up!

The pbsw-SNMP module is built from four classes: pbsw_SNMP_Socket, pbsw_SNMP_Message, pbsw_BER_Part, and pbsw_SNMP_NVPair. The easiest way to begin exploring this module would be to start with the sample project. To get started with a new empty project involves the following basic steps:
  1. Add the pbsw-SNMP modules to your project (drag the folder into the project window)
  2. Create an instance of pbsw_SNMP_Socket on your main window. (This is a little convoluted because REALbasic dosen't have a draggable UDPSocket control yet): Control-click on a blank part of the window to bring up a contextual popup-menu and choose: Add Control -> Any -> SocketCore... -> UDPSocket... -> pbsw_SNMP_Socket
  3. Set the "Port" property of the socket control to some available high numbered port (NOTE: This does not need to be, and should NOT be the standard SNMP port (161)! The messages will be sent to the correct port on the other end, the receiving port can, and should be different.)
  4. Add code to the "MessageReceived" and "Error" events of the socket control to do something with received messages and errors.
  5. Create a new message.
  6. Send it.
(Yes, the last parts are oversimplified, but you will need to write some of your own code...)

Class: pbsw_SNMP_Socket

(Superclass: UDPSocket)

This class is used for sending SNMP messages.

Methods

SendMessage(theDestIP as string, theMessage as pbsw_SNMP_Message) as Boolean
send an SNMP message through the socket
theDestIP is a string containing the IP Address the message should be sent to
theMessage is the message to send
returns true if the message began sending OK

Events

DataAvailable()
This event is a standard event inherited from the SocketCore class
and is overriden by pbsw_SNMP_Socket. You shouldn't under normal
circumstances need to override this event - you should deal with the
"MessageReceived" event.

SendComplete()
This event is a standard event inherited from the SocketCore class

NewEvents

MessageReceived(theMessage as pbsw_SNMP_Message)
This new event gets called when an SNMP message is received back from the network.
theMessage is the received message


Class: pbsw_SNMP_Message

This class represents an SNMP message that can be sent or received by an SNMP Socket.

Methods

GetData() as string
returns the raw data [bytes] as as string

GetDataAsHexBytes() as string
returns the data [bytes] as a human readable string of hex bytes

GetSNMPCommunity() as string
returns the SNMP community string of the message

GetSNMPErrorIndex() as integer
returns the SNMP error index of the message

GetSNMPErrorStatus() as integer
returns the SNMP error status of the message

GetSNMPNVPairs() as Dictionary
returns the Name-Value pairs in the message

GetSNMPPDUType() as integer
returns the SNMP PDU type code

GetSNMPRequestID() as integer
returns the SNMP requestID of the message

GetSNMPVersion() as integer
returns the SNMP version of the message

GetSourceIP() as string
returns the IP address of the device that sent the message

IsMessageOK() as Boolean
returns true if the message appears to be a complete, properly constructed SNMP message
NOTE: a message can be OK and still include an error indicated by the SNMP Error Status
-- being "OK" just means the packet itself was received correctly

pbsw_SNMP_Message(theDatagram as DataGram)
construct an SNMP message object using a DataGram (usually received from a pbsw_SNMP_Socket)

pbsw_SNMP_Message(thePDUType as integer,theCommunity as string, theRequestID as integer, theOID as string, theData as pbsw_BER_Part)
construct an SNMP message object by passing appropriate info

pbsw_SNMP_Message(theHexDataBytes as string)
construct an SNMP message object from a [human readable] string of hex bytes


Class: pbsw_BER_Part

This class represents a BER (Basic Encoding Rules) element.
It can encode and decode BER formatted data.
(A pbsw_BER_Part can be a container of elements, e.g. BER Sequence)

Methods

CountSequenceItems() as integer
returns the number of items in a sequence

GetByteStream() as string
returns the BER part as a stream (string) of bytes

GetByteStreamAsHexBytes() as string
returns a BER part as a string of [human readable] hex bytes

GetNextPart(thePart as pbsw_BER_Part) as pbsw_BER_Part
returns the part in a sequence, following "thePart" passed

GetSequenceItem(theItemNum as integer) as pbsw_BER_Part
returns the n-th item in a sequence where n = theItemNum

GetSize() as integer
returns the size (in bytes) of the part

GetType() as integer
returns the type code of the part

GetTypeName() as string
returns the name of the type of the part

GetValue() as Variant
returns the value of the part
the type of variable returned depends on the type of part:

SNMP Type : REALbasic Type
--------------------------------------
SEQUENCE : dictionary
INTEGER : integer
OCTET STRING : string
OBJECT IDENTIFIER : string
IPADDRESS : string
COUNTER : double
GAUGE : double
TIMETICKS : double
OPAQUE : string
NULL : string (empty)

GetValueAsString() as string
returns the value of the part as a string

IsPartOK() as Boolean
returns true if the part was created without any problems

IsSequence() as Boolean
returns true if the part is a sequence of other parts

pbsw_BER_Part(ByRef theRawData as string)
constructs the part from a raw string of binary data [bytes] passed in as theRawData

pbsw_BER_Part(theType as integer, theData as Variant)
constructs the part from a type code (theType) and value (theData)


Class: pbsw_SNMP_NVPair

This class represents a "Name-Value pair" from an SNMP packet.

Methods

GetName() as string
returns the name as a string

GetType() as integer
returns the type

GetTypeAsString() as string
returns the type as a string (i.e. the name of the type)

GetValue() as string
returns the value stored in the Name-Value pair

pbsw_SNMP_NVPair(theName as string, theType as integer, theValue as string)
constructs the NVPair from theName, theType, and theValue


pbsw-code.net : pbsw-SNMP