SNMP

Topics
	Read/write callback function signatures
	Function typedefs your callbacks must match. The shape of the callback selects the dispatcher overload automatically.
	Registering SNMP table rows and cells
	Register per-row read callbacks and per-cell write callbacks for tabular MIB objects, and remove rows at runtime.
	Registering scalar (single-value) MIB variables
	Bind one C getter/setter to one OID that ends in .0.
	SMI type aliases, ASN.1 tags, and SET return codes
	The vocabulary used when registering a variable: pick a SMI type for the value, pass the matching ASN_type* tag, return SNMP_SET_OK / SNMP_SET_FAIL from setters.

Classes
class	SnmpServlet
	SNMP agent servlet that listens for and processes SNMP requests. More...
class	snmp_config
	SNMP agent configuration stored in the system configuration framework. More...

Macros
#define	SNMPCOUNTIF(x, i)   {InterfaceBlock * pif=GetInterfaceBlock(i); if(pif) pif->x++; }
	Increment an SNMP counter on a specific network interface.
#define	SNMPCOUNT(x)   (x++)
	Increment an SNMP counter variable.
#define	SNMPDEC(x)   (x--)
	Decrement an SNMP counter variable.
#define	SNMPADD(x, y)   (x=x+y)
	Add a value to an SNMP counter variable.
#define	READ_COMMUNITY_MASK   (0x0001)
	Bitmask indicating read community access.
#define	WRITE_COMMUNITY_MASK   (0x0002)
	Bitmask indicating write community access.

Typedefs
typedef void	PutTrapVarBindsFunc(ASN *put_asn)
	Function type for SNMP trap variable binding callbacks.

Functions
int	StartSnmpProcessor (int priority)
	Start the SNMP processor task.
void	SnmpBasicTrap (IPADDR dest, const char *community_name, int generic_trap, int specific_trap)
	Send an SNMP trap without custom variable bindings.
void	SnmpTrapWithData (IPADDR dest, const char *community_name, int generic_trap, int specific_trap, PutTrapVarBindsFunc *pDataCallbackFunction)
	Send an SNMP trap with custom variable bindings.

Variables
const char *	SYSDESC
	Application-defined system description string for MIB-II sysDescr.
const char *	SYSOID
	Application-defined system object identifier string for MIB-II sysObjectID.
snmp_config	TheSnmpConfig
	Global SNMP configuration instance.
uint32_t(*	SnmpCommunityDecodeFunc )(const unsigned char *name)
	Function pointer for custom SNMP community name validation.

Detailed Description

#include< snmp.h>


NetBurner SNMP (Simple Network Management Protocol) agent interface.

Provides the SNMP agent servlet, configuration, trap generation functions, and SNMP counter macros for the NetBurner RTOS. When ENABLE_SNMP is not defined, all counter macros resolve to no-ops so the system compiles without SNMP support.

The SNMP agent supports SNMPv1 GET, GET-NEXT, and SET operations, as well as sending traps (both basic and with custom variable bindings). The agent runs as a servlet within the system select loop, listening on a configurable UDP port (default 161).

Required Definitions

• SYSDESC - Application-defined system description string (MIB-II sysDescr).
• SYSOID - Application-defined system OID string (MIB-II sysObjectID).

---

Expand for Example Usage

Examples

Basic SNMP Agent Setup

#include <snmp.h>
 
// Required: define the system description and OID for MIB-II
const char *SYSDESC = "My NetBurner SNMP Application";
const char *SYSOID = "1.3.6.1.4.1.8174.2.40";
 
// Create the SNMP servlet (listens on UDP port 161 by default)
SnmpServlet TheSnmpServer;

Sending a Basic Trap

#include <snmp.h>
 
void SendColdStartTrap()
{
    SnmpBasicTrap(IPADDR::NullIP(),   // Use configured trap destination
                  "public",            // Community string
                  0,                   // Generic trap: coldStart
                  0);                  // Specific trap code
}

Sending a Trap with Custom Variable Bindings

#include <snmp.h>
 
// Callback to add custom variable bindings to the trap PDU
void MyTrapVarFunction(ASN *put_asn)
{
    // First variable binding
    put_asn->PutHeader(0x30);                           // SEQUENCE header
    put_asn->PutOidFromString("1.3.6.1.4.1.8174.1");   // Enterprise OID
    put_asn->PutOctetString("Sensor threshold exceeded");
    put_asn->FixUpHeader();
 
    // Second variable binding
    put_asn->PutHeader(0x30);
    put_asn->PutOidFromString("1.3.6.1.4.1.8174.2");
    put_asn->PutInt(42);                                // Current sensor value
    put_asn->FixUpHeader();
}
 
void SendSensorTrap()
{
    SnmpTrapWithData(IPADDR::NullIP(),      // Use configured trap destination
                     "public",               // Community string
                     SNMP_ENTERPRISE_TRAP,   // Generic trap type (6)
                     1,                      // Specific trap code
                     MyTrapVarFunction);     // Callback for variable bindings
}

---

Macro Definition Documentation

SNMPADD

#define SNMPADD	(		x,
			y )   (x=x+y)

#include <snmp.h>

Add a value to an SNMP counter variable.

Parameters

x	The counter variable to add to.
y	The value to add.

SNMPCOUNT

#define SNMPCOUNT

(

x

)

(x++)

#include <snmp.h>

Increment an SNMP counter variable.

Parameters

x	The counter variable to increment.

SNMPCOUNTIF

#define SNMPCOUNTIF	(		x,
			i )   {InterfaceBlock * pif=GetInterfaceBlock(i); if(pif) pif->x++; }

#include <snmp.h>

Increment an SNMP counter on a specific network interface.

Retrieves the InterfaceBlock for the given interface number and increments the specified counter member. If the interface is invalid, the operation is silently skipped.

Parameters

x	The InterfaceBlock SNMP counter member to increment (e.g., EthifInOctets).
i	The interface number to operate on.

SNMPDEC

#define SNMPDEC

(

x

)

(x--)

#include <snmp.h>

Decrement an SNMP counter variable.

Parameters

x	The counter variable to decrement.

Typedef Documentation

PutTrapVarBindsFunc

typedef void PutTrapVarBindsFunc(ASN *put_asn)

#include <snmp.h>

Function type for SNMP trap variable binding callbacks.

A callback of this type is invoked during trap construction to add custom variable bindings to the trap PDU. Use the ASN object's Put methods to encode each variable binding as a SEQUENCE containing an OID and a value.

Parameters

put_asn

Pointer to the ASN encoder for writing variable bindings.

See also

SnmpTrapWithData()

Function Documentation

SnmpBasicTrap()

void SnmpBasicTrap	(	IPADDR	dest,
		const char *	community_name,
		int	generic_trap,
		int	specific_trap )

#include <snmp.h>

Send an SNMP trap without custom variable bindings.

Sends an SNMPv1 trap PDU to the specified destination. If the destination is IPADDR::NullIP(), the trap is sent to the address configured in TheSnmpConfig.trap_destination.

Parameters

dest	Trap destination IP address. Pass IPADDR::NullIP() to use the configured trap_destination.
community_name	Community string to include in the trap PDU.
generic_trap	Generic trap type (0=coldStart, 1=warmStart, 2=linkDown, 3=linkUp, 4=authenticationFailure, 5=egpNeighborLoss, 6=enterpriseSpecific).
specific_trap	Specific trap code (meaningful when generic_trap is 6).

See also

SnmpTrapWithData()

SnmpTrapWithData()

void SnmpTrapWithData	(	IPADDR	dest,
		const char *	community_name,
		int	generic_trap,
		int	specific_trap,
		PutTrapVarBindsFunc *	pDataCallbackFunction )

#include <snmp.h>

Send an SNMP trap with custom variable bindings.

Sends an SNMPv1 trap PDU to the specified destination, invoking the provided callback function to encode custom variable bindings into the trap. If the destination is IPADDR::NullIP(), the trap is sent to the address configured in TheSnmpConfig.trap_destination.

Parameters

dest	Trap destination IP address. Pass IPADDR::NullIP() to use the configured trap_destination.
community_name	Community string to include in the trap PDU.
generic_trap	Generic trap type (0=coldStart, 1=warmStart, 2=linkDown, 3=linkUp, 4=authenticationFailure, 5=egpNeighborLoss, 6=enterpriseSpecific).
specific_trap	Specific trap code (meaningful when generic_trap is 6).
pDataCallbackFunction	Callback function to encode custom variable bindings. Pass NULL for no custom bindings (equivalent to SnmpBasicTrap()).

---

Expand for Example Usage

Examples

Sending a Trap with Variable Bindings

#include <snmp.h>
 
void TrapVarFunction(ASN *put_asn)
{
    // Encode a variable binding: OID + string value
    put_asn->PutHeader(0x30);                           // SEQUENCE
    put_asn->PutOidFromString("1.3.6.1.4.1.8174.1");   // OID
    put_asn->PutOctetString("Alert: high temperature"); // Value
    put_asn->FixUpHeader();                             // Close SEQUENCE
 
    // Encode a second variable binding: OID + integer value
    put_asn->PutHeader(0x30);
    put_asn->PutOidFromString("1.3.6.1.4.1.8174.2");
    put_asn->PutInt(85);                                // Temperature reading
    put_asn->FixUpHeader();
}
 
void SendTemperatureTrap()
{
    SnmpTrapWithData(IPADDR::NullIP(),      // Use configured destination
                     "public",               // Community string
                     6,                      // Enterprise-specific trap
                     1,                      // Specific trap code
                     TrapVarFunction);       // Variable binding callback
}

---

See also

SnmpBasicTrap()

PutTrapVarBindsFunc

StartSnmpProcessor()

int StartSnmpProcessor

(

int

priority

)

#include <snmp.h>

Start the SNMP processor task.

Deprecated

Use SnmpServlet instead. Create a SnmpServlet object to start the SNMP agent as part of the system servlet select loop.

Parameters

priority

The UCOS task priority to run at.

Return values

0	CMD_OK - SNMP processor started successfully.
-1	CMD_FAIL - Failed to start SNMP processor.

Variable Documentation

SnmpCommunityDecodeFunc

uint32_t(* SnmpCommunityDecodeFunc) (const unsigned char *name) ( const unsigned char * name )

extern

#include <snmp.h>

Function pointer for custom SNMP community name validation.

Override this function pointer to implement custom community name processing logic. The default implementation checks the community name against the configured ReadCommunity and WriteCommunity strings.

Parameters

name	The community name from the incoming SNMP request.

Returns

A bitmask of access permissions:

• READ_COMMUNITY_MASK (0x0001) if the name grants read access.
• WRITE_COMMUNITY_MASK (0x0002) if the name grants write access.
• 0 if the community name is not recognized.

---

Expand for Example Usage

Examples

Custom Community Name Validation

#include <snmp.h>
 
uint32_t MyCommDecode(const unsigned char *name)
{
    if (strcmp((const char *)name, "secretRead") == 0)
        return READ_COMMUNITY_MASK;
    if (strcmp((const char *)name, "secretWrite") == 0)
        return READ_COMMUNITY_MASK | WRITE_COMMUNITY_MASK;
    return 0;  // Deny access
}
 
void InitCustomSnmp()
{
    SnmpCommunityDecodeFunc = MyCommDecode;
}

---

SYSDESC

const char* SYSDESC

extern

#include <snmp.h>

Application-defined system description string for MIB-II sysDescr.

This variable must be defined by the application. It is returned in response to SNMP queries for the sysDescr OID (1.3.6.1.2.1.1.1).

Application-defined system description string for MIB-II sysDescr.

This string is returned when an SNMP manager queries the system description. It should describe the device and its purpose.

SYSOID

const char* SYSOID

extern

#include <snmp.h>

Application-defined system object identifier string for MIB-II sysObjectID.

This variable must be defined by the application. It is returned in response to SNMP queries for the sysObjectID OID (1.3.6.1.2.1.1.2). The value should be a dotted-decimal OID string (e.g., "1.3.6.1.4.1.8174.2.40").

Application-defined system object identifier string for MIB-II sysObjectID.

This OID uniquely identifies the device type within the enterprise namespace. Structure: 1.3.6.1.4.1.8174.2.40

• 1.3.6.1.4.1 = ISO.org.dod.internet.private.enterprises
• 8174 = NetBurner's IANA-assigned enterprise number
• 2.40 = Product/application identifier (vendor-defined)

TheSnmpConfig

snmp_config TheSnmpConfig

extern

#include <snmp.h>

Global SNMP configuration instance.

Provides access to all SNMP configuration parameters. This object is automatically created by the SNMP subsystem and registered in the system configuration tree.