Functions to communicate with the Trap Manager. More...

Functions
netStatus	netSNMP_Trap (const NET_ADDR addr, uint8_t generic, uint8_t specific, const uint16_t obj_list)
	Send a trap message to the Trap Manager. [thread-safe].

netStatus	netSNMP_SetCommunity (const char *community)
	Change SNMP community to a new community. [thread-safe].

netStatus	netSNMP_SetMIB_Table (const NET_SNMP_MIB_INFO *info, uint32_t size)
	Register MIB table to SNMP Agent. [thread-safe].

Description

Functions to communicate with the Trap Manager.

To notify the SNMP manager of significant events, so called traps are used. The Network Component's netSNMP_Trap function is used to send these unsolicited messages to the manager. The SNMP community string is a kind of password that is used to authenticate the SNMP agent (SNMP v1 and v2 only; SNMP v3 has dedicated username/password protection). To change the SNMP community string, use netSNMP_SetCommunity.

Function Documentation

◆ netSNMP_SetCommunity()

netStatus netSNMP_SetCommunity ( const char * community )

Change SNMP community to a new community. [thread-safe].

Parameters

[in] community new community, a null-terminated string.

Returns: status code that indicates the execution status of the function.

The function netSNMP_SetCommunity changes the SNMP community to a new community identified by community.

The argument community is a pointer to a null-terminated string. The function copies the content of the community to the SNMP community. The maximum length of the community string is limited to 18 characters.

Possible netStatus return values:

netOK: The new community successfully set.
netInvalidParameter: Invalid community provided.

Note: When the function ends, the content of community becomes irrelevant and may be discarded.

Code Example

uint16_t obj[2];
 
// Change the community to "private".
netSNMP_SetCommunity ("private");
 
// Add "KeyIn" value to trap message.
obj[0] = 1;
obj[1] = 8;    // Index of "KeyIn" entry in MIB table.
netSNMP_Trap (NULL, 6, 1, obj);

◆ netSNMP_SetMIB_Table()

netStatus netSNMP_SetMIB_Table	(	const NET_SNMP_MIB_INFO *	info,
		uint32_t	size
	)

Register MIB table to SNMP Agent. [thread-safe].

Parameters

[in]	info	pointer to MIB table.
[in]	size	size of MIB table in bytes.

Returns: status code that indicates the execution status of the function.

The function netSNMP_SetMIB_Table registers SNMP-MIB table in SNMP Agent. Until a valid SNMP-MIB table is registered in SNMP Agent, the Agent is not active and does not respond to SNMP requests.

The argument info points to a buffer containing the SNMP-MIB entry info.

The argument size is a size of the SNMP-MIB table.

Possible netStatus return values:

netOK: MIB table successfully registered.
netInvalidParameter: Invalid MIB table provided.

Code Example

// MIB data table
static const NET_SNMP_MIB_INFO mib_table[] = {
  // SysDescr Entry
  { NET_SNMP_MIB_OCTET_STR | NET_SNMP_MIB_ATR_RO,
    8, {NET_SNMP_MIB_OID0(1,3), 6, 1, 2, 1, 1, 1, 0},
    NET_SNMP_MIB_STR("Embedded System SNMP V1.0"),
    NULL },
  ..
}
 
if (netSNMP_SetMIB_Table (mib_table, sizeof(mib_table)) == netOK) {
  // SNMP agent is active now
}

◆ netSNMP_Trap()

netStatus netSNMP_Trap	(	const NET_ADDR *	addr,
		uint8_t	generic,
		uint8_t	specific,
		const uint16_t *	obj_list
	)

Send a trap message to the Trap Manager. [thread-safe].

Parameters

[in]	addr	structure containing IP address of the Trap server. NULL to use Trap server IP address from system configuration.
[in]	generic	generic trap type: 0 = ColdStart trap. 1 = WarmStart trap. 2 = LinkDown trap. 3 = LinkUp trap. 4 = AuthenticationFailure trap. 5 = EgpNeighborLoss trap. 6 = EnterpriseSpecific trap.
[in]	specific	specific trap type for generic enterpriseSpecific trap: must be set to 0 for generic traps 0 ... 5
[in]	obj_list	object list included in trap message.

Returns: status code that indicates the execution status of the function.

The function netSNMP_Trap sends a message to the Trap Manager.

The argument addr points to the IP address and port of the Trap server. If the IP address of the Trap Manager is NULL, then the IP address of Trap Server configured in Net_Config_SNMP_Agent.h is used.

The argument generic specifies the generic trap type:

Type	Description
0	coldStart trap
1	warmStart trap
2	linkDown trap
3	linkUp trap
4	authenticationFailure trap
5	egpNeighborLoss trap
6	enterpriseSpecific trap

The argument specific denotes a specific trap type. It must be set to 0 for all generic traps from 0..5. It defines a specific trap type for generic enterpriseSpecific trap.

The argument obj_list points to the objects from the MIB table, which will be included in the trap message variable-bindings. This argument is a pointer to the object list array. This array is of variable size. The first element specifies the count of objects in the object list array, followed by the object MIB index values.

Array Index	Array Value
obj[0]	number of objects n
obj[1]	MIB index of first object
obj[2]	MIB index of second object
..	..
obj[n]	MIB index of last object

If obj_list is NULL, or obj[0] = 0, then no object values will be bound to the trap message.

Possible netStatus return values:

netOK: Trap message sent successfully.
netInvalidParameter: Invalid parameter provided.
netWrongState: MIB table not registered.
netError: sysObjectId missing in the MIB table or message too big.

Note: The maximum number of objects that can be bound to the trap message is limited to 20 objects.

Code Example

uint16_t obj[2];
 
// Add "KeyIn" value to trap message. 
obj[0] = 1;
obj[1] = 8;    // Index of "KeyIn" entry in MIB table.
netSNMP_Trap (NULL, 6, 1, obj);