VxWorks Reference Manual : Libraries
m2IfLib - MIB-II interface-group API for SNMP agents
m2IfAlloc( ) - Allocate the structure for the interface table
m2IfFree( ) - free an interface data structure
m2IfGenericPacketCount( ) - Increment the interface packet counters
m2If8023PacketCount( ) - Increment the interface packet counters for an 802.3
m2IfCounterUpdate( ) - Increment interface counters
m2IfVariableUpdate( ) - Update the contents of an interface non-counter object
m2IfPktCountRtnInstall( ) - Install an interface packet counter routine
m2IfCtrUpdateRtnInstall( ) - Install an interface counter update routine
m2IfVarUpdateRtnInstall( ) - Install an interface variable update routine
m2IfInit( ) - initialize MIB-II interface-group routines
m2IfTableUpdate( ) - Insert or remove an entry in the ifTable
rcvAddrAdd( ) - populate the rcvAddr fields for the ifRcvAddressTable
rcvAddrAdd( ) - add a physical address into the linked list
m2IfTblEntryGet( ) - get a MIB-II interface-group table entry
m2IfDefaultValsGet( ) - get the default values for the counters
m2IfCommonValsGet( ) - get the common values
m2IfTblEntrySet( ) - set the state of a MIB-II interface entry to UP or DOWN
m2IfGroupInfoGet( ) - get the MIB-II interface-group scalar variables
m2IfStackEntryGet( ) - get a MIB-II interface-group table entry
m2IfStackEntrySet( ) - modify the status of a relationship
m2IfRcvAddrEntryGet( ) - get the rcvAddress table entries for a given address
m2IfRcvAddrEntrySet( ) - modify the entries of the rcvAddressTable
m2IfDelete( ) - delete all resources used to access the interface group
nextIndex( ) - the comparison routine for the AVL tree
This library provides MIB-II services for the interface group. It provides routines to initialize the group, access the group scalar variables, read the table interfaces and change the state of the interfaces. For a broader description of MIB-II services, see the manual entry for m2Lib.
This library can be initialized and deleted by calling m2IfInit( ) and m2IfDelete( ) respectively, if only the interface group's services are needed. If full MIB-II support is used, this group and all other groups can be initialized and deleted by calling m2Init( ) and m2Delete( ).
The interface group supports the Simple Network Management Protocol (SNMP) concept of traps, as specified by RFC 1215. The traps supported by this group are "link up" and "link down." This library enables an application to register a hook routine and an argument. This hook routine can be called by the library when a "link up" or "link down" condition is detected. The hook routine must have the following prototype:
void TrapGenerator (int trapType, /* M2_LINK_DOWN_TRAP or M2_LINK_UP_TRAP */ int interfaceIndex, void * myPrivateArg);The trap routine and argument can be specified at initialization time as input parameters to the routine m2IfInit( ) or to the routine m2Init( ).The interface-group global variables can be accessed as follows:
M2_INTERFACE ifVars; if (m2IfGroupInfoGet (&ifVars) == OK) /* values in ifVars are valid */An interface table entry can be retrieved as follows:M2_INTERFACETBL interfaceEntry; /* Specify zero as the index to get the first entry in the table */ interfaceEntry.ifIndex = 2; /* Get interface with index 2 */ if (m2IfTblEntryGet (M2_EXACT_VALUE, &interfaceEntry) == OK) /* values in interfaceEntry are valid */An interface entry operational state can be changed as follows:M2_INTERFACETBL ifEntryToSet; ifEntryToSet.ifIndex = 2; /* Select interface with index 2 */ /* MIB-II value to set the interface */ /* to the down state. */ ifEntryToSet.ifAdminStatus = M2_ifAdminStatus_down; if (m2IfTblEntrySet (&ifEntryToSet) == OK) /* Interface is now in the down state */
m2Lib.h
m2IfLib, m2Lib, m2SysLib, m2IpLib, m2IcmpLib, m2UdpLib, m2TcpLib
m2IfAlloc( ) - Allocate the structure for the interface table
M2_ID * m2IfAlloc ( ULONG ifType, /* If type of the interface */ UCHAR * pEnetAddr, /* Physical address of interface */ ULONG addrLen, /* Address length */ ULONG mtuSize, /* MTU of interface */ ULONG speed, /* Speed of the interface */ char * pName, /* Name of the device */ int unit /* Unit number of the device */ )
This routine is called by the driver during initialization of the interface. The memory for the interface table is allocated here. We also set the default update routines in the M2_ID struct. These fields can later be overloaded using the installed routines in the M2_ID. Once this function returns, it is the drivers responsibility to set the pMib2Tbl pointer in the END object to the new M2_ID.
The local flag, mibStyle, is set to MIB_STYLE_2233 here because this routine will be called only if the driver supports RFC 2233 counters.
Pointer to the M2_ID struct that gets allocated.
m2IfFree( ) - free an interface data structure
STATUS m2IfFree ( M2_ID * pId /* pointer to the driver's M2_ID object */ )
This routine frees the given M2_ID. Note if the driver is not an RFC 2233 driver then the M2_ID will be NULL and this function simply returns.
OK if successful, ERROR otherwise
m2IfGenericPacketCount( ) - Increment the interface packet counters
STATUS m2IfGenericPacketCount ( M2_ID * pId, /* The pointer to the device M2_ID object */ UINT ctrl, /* Update In or Out counters */ UCHAR * pPkt, /* The incoming/outgoing packet */ ULONG pktLen /* Length of the packet */ )
This function is used to update basic interface counters for a packet. It has no idea of the underlying media so only the ifInOctets, ifHCInOctets, ifOutOctets, ifHCOutOctets, and ifCounterDiscontinuityTime variables are incremented. The ctrl argument specifies whether the packet is being sent or just received (M2_PACKET_IN or M2_PACKET_OUT).
ERROR if the M2_ID is NULL, OK if the counters were updated.
m2If8023PacketCount( ) - Increment the interface packet counters for an 802.3
STATUS m2If8023PacketCount ( M2_ID * pId, /* The pointer to the device M2_ID object */ UINT ctrl, /* Update In or Out counters */ UCHAR * pPkt, /* The incoming/outgoing packet */ ULONG pktLen /* Length of the packet */ )
device
This function is used to update basic interface counters for a packet. The ctrl argument specifies whether the packet is being sent or just received (M2_PACKET_IN or M2_PACKET_OUT). This function only works for 802.3 devices as it understand the Ethernet packet format. The following counters are updated:
. ifInOctets
. ifInUcastPkts
. ifInNUcastPkts
. ifOutOctets
. ifOutUcastPkts
. ifOutNUcastPkts
. ifInMulticastPkts
. ifInBroadcastPkts
. ifOutMulticastPkts
. ifOutBroadcastPkts
. ifHCInOctets
. ifHCInUcastPkts
. ifHCOutOctets
. ifHCOutUcastPkts
. ifHCInMulticastPkts
. ifHCInBroadcastPkts
. ifHCOutMulticastPkts
. ifHCOutBroadcastPkts
. ifCounterDiscontinuityTimeThis function should be called right after the netMblkToBufCopy( ) function has has been completed. The first 6 bytes in the resulting buffer must contain the destination MAC address and the second 6 bytes of the buffer must contain the source MAC address.
The type of MAC address (i.e. broadcast, multicast, or unicast) is determined by the following:
. broadcast address: ff:ff:ff:ff:ff:ff . multicast address: first bit is set . unicast address: any other address not matching the above
ERROR if the M2_ID is NULL or the ctrl is invalid, OK if
the counters were updated.
m2IfCounterUpdate( ) - Increment interface counters
STATUS m2IfCounterUpdate ( M2_ID * pId, /* The pointer to the device M2_ID object */ UINT ctrId, /* Counter to update */ ULONG value /* Amount to update the counter by */ )
This function is used to directly update an interface counter. The counter is specified by ctrId and the amount to increment it is specified by value. If the counter would roll over then the ifCounterDiscontinuityTime is updated with the current system uptime.
ERROR if the M2_ID is NULL, OK if the counter was updated.
m2IfVariableUpdate( ) - Update the contents of an interface non-counter object
STATUS m2IfVariableUpdate ( M2_ID * pId, /* The pointer to the device M2_ID object */ UINT varId, /* Variable to update */ caddr_t pData /* Data to use */ )
This function is used to update an interface variable. The variable is specified by varId and the data to use is specified by pData. Note that different variable expect differnet types of data. Here is a list of the variables the the type of data expected. Therefore pData will be cast to the type listed below for each variable.
. ifDescr char *
. ifType UINT
. ifMtu ULONG
. ifSpeed ULONG
. ifPhysAddress M2_PHYADDR *
. ifAdminStatus ULONG
. ifOperStatus ULONG
. ifLastChange ULONG
. ifOutQLen ULONG
. ifSpecific M2_OBJECTID *
. ifName char *
. ifLinkUpDownTrapEnable UINT
. ifHighSpeed ULONG
. ifPromiscuousMode UINT
. ifConnectorPresent UINT
. ifAlias char *
ERROR if the M2_ID is NULL, OK if the variable was updated.
m2IfPktCountRtnInstall( ) - Install an interface packet counter routine
STATUS m2IfPktCountRtnInstall ( M2_ID * pId, M2_PKT_COUNT_RTN pRtn )
This function installs a routine in the M2_ID. This routine is a packet counter which is able to update all the interface counters.
ERROR if the M2_ID is NULL, OK if the routine was installed.
m2IfCtrUpdateRtnInstall( ) - Install an interface counter update routine
STATUS m2IfCtrUpdateRtnInstall ( M2_ID * pId, M2_CTR_UPDATE_RTN pRtn )
This function installs a routine in the M2_ID. This routine is able to update a single specified interface counter.
ERROR if the M2_ID is NULL, OK if the routine was installed.
m2IfVarUpdateRtnInstall( ) - Install an interface variable update routine
STATUS m2IfVarUpdateRtnInstall ( M2_ID * pId, M2_VAR_UPDATE_RTN pRtn )
This function installs a routine in the M2_ID. This routine is able to update a single specified interface variable.
ERROR if the M2_ID is NULL, OK if the routine was installed.
m2IfInit( ) - initialize MIB-II interface-group routines
STATUS m2IfInit ( FUNCPTR pTrapRtn, /* pointer to user trap generator */ void * pTrapArg /* pointer to user trap generator argument */ )
This routine allocates the resources needed to allow access to the MIB-II interface-group variables. This routine must be called before any interface variables can be accessed. The input parameter pTrapRtn is an optional pointer to a user-supplied SNMP trap generator. The input parameter pTrapArg is an optional argument to the trap generator. Only one trap generator is supported.
OK, always.
S_m2Lib_CANT_CREATE_IF_SEM
m2IfLib, m2IfGroupInfoGet( ), m2IfTblEntryGet( ), m2IfTblEntrySet( ), m2IfDelete( )
m2IfTableUpdate( ) - Insert or remove an entry in the ifTable
STATUS m2IfTableUpdate ( struct ifnet * pIfNet, UINT status /* attaching or detaching */ )
This routine is called by if_attach and if_detach to insert/remove an entry from the local m2IfLib ifTable. The status can be one of M2_IF_TABLE_INSERT or M2_IF_TABLE_REMOVE. The ifIndex that is searched for in the AVL tree is specified in given the ifnet struct.
ERROR if entry does not exist, OK if the entry was deleted
rcvAddrAdd( ) - populate the rcvAddr fields for the ifRcvAddressTable
STATUS rcvAddrGet ( struct arpcom * pIfArpcom, /* pointer to the interface's arpcom */ M2_IFINDEX * pIfIndexEntry /* avl node */ )
This function needs to be called to add all physical addresses for which an interface may receive or send packets. This includes unicast and multicast addresses. The address is inserted into the linked list maintained in the AVL node corresponding to the interface. Given the arpcom struct and the AVL node correspnding to the interface, this function goes through all the physical addresses associated with this interface and adds them into the linked list.
OK if successful,
ERROR otherwise
rcvAddrAdd( ) - add a physical address into the linked list
STATUS rcvAddrAdd ( M2_IFINDEX * pIfIndexEntry, /* the avl node */ unsigned char * pEnetAddr /* the addr to be added */ )
This function is called to add a single physical address into the linked list of addresses maintained by the AVL node.
OK if successful,
ERROR otherwise
m2IfTblEntryGet( ) - get a MIB-II interface-group table entry
STATUS m2IfTblEntryGet ( int search, /* M2_EXACT_VALUE or M2_NEXT_VALUE */ void * pIfReqEntry /* pointer to requested interface entry */ )
This routine maps the MIB-II interface index to the system's internal interface index. The internal representation is in the form of a balanced AVL tree indexed by ifIndex of the interface. The search parameter is set to either M2_EXACT_VALUE or M2_NEXT_VALUE; for a discussion of its use, see the manual entry for m2Lib.
OK, or ERROR if the input parameter is not specified, or a match is not found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
m2IfLib, m2Lib, m2IfInit( ), m2IfGroupInfoGet( ), m2IfTblEntrySet( ), m2IfDelete( )
m2IfDefaultValsGet( ) - get the default values for the counters
void m2IfDefaultValsGet ( M2_DATA * pM2Data, /* The requested entry */ M2_IFINDEX * pIfIndexEntry /* The ifindex node */ )
This function fills up the given struct with the default values as specified in the RFC. We will enter this routine only if the ioctl to the driver fails.
n/a
m2IfCommonValsGet( ) - get the common values
void m2IfCommonValsGet ( M2_DATA * pM2Data, /* The requested struct */ M2_IFINDEX * pIfIndexEntry /* The ifindex node */ )
This function updates the requested struct with all the data that is independent of the driver ioctl. This information can be obtained from the ifnet structures.
n/a
m2IfTblEntrySet( ) - set the state of a MIB-II interface entry to UP or DOWN
STATUS m2IfTblEntrySet ( void * pIfReqEntry /* pointer to requested entry to change */ )
This routine selects the interface specified in the input parameter pIfReqEntry and sets the interface parameters to the requested state. It is the responsibility of the calling routine to set the interface index, and to make sure that the state specified in the ifAdminStatus field of the structure at pIfTblEntry is a valid MIB-II state, up(1) or down(2).
The fields that can be modified by this routine are the following: ifAdminStatus, ifAlias, ifLinkUpDownTrapEnable and ifName.
OK, or ERROR if the input parameter is not specified, an interface is no longer valid, the interface index is incorrect, or the ioctl( ) command to the interface fails.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
S_m2Lib_IF_CNFG_CHANGED
m2IfLib, m2IfInit( ), m2IfGroupInfoGet( ), m2IfTblEntryGet( ), m2IfDelete( )
m2IfGroupInfoGet( ) - get the MIB-II interface-group scalar variables
STATUS m2IfGroupInfoGet ( M2_INTERFACE * pIfInfo /* pointer to interface group structure */ )
This routine fills out the interface-group structure at pIfInfo with the values of MIB-II interface-group global variables.
OK, or ERROR if pIfInfo is not a valid pointer.
S_m2Lib_INVALID_PARAMETER
m2IfLib, m2IfInit( ), m2IfTblEntryGet( ), m2IfTblEntrySet( ), m2IfDelete( )
m2IfStackEntryGet( ) - get a MIB-II interface-group table entry
STATUS m2IfStackEntryGet ( int search, /* M2_EXACT_VALUE or M2_NEXT_VALUE */ int * pHighIndex, /* the higher layer's ifIndex */ M2_IFSTACKTBL * pIfReqEntry /* pointer to the requested entry */ )
This routine maps the given high and low indexes to the interfaces in the AVL tree. Using the high and low indexes, we retrieve the nodes in question and walk through their linked lists to get to the right relation. Once we get to the correct node, we can return the values based on the M2_EXACT_VALUE and the M2_NEXT_VALUE searches.
OK, or ERROR if the input parameter is not specified, or a match is not found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
m2IfStackEntrySet( ) - modify the status of a relationship
STATUS m2IfStackEntrySet ( int highIndex, /* The higher layer's ifIndex */ M2_IFSTACKTBL * pIfReqEntry /* The requested entry */ )
This routine selects the interfaces specified in the input parameters pIfReqEntry and highIndex and sets the interface's status to the requested state.
OK, or ERROR if the input parameter is not specified, an interface is no longer valid, or the interface index is incorrect.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
S_m2Lib_IF_CNFG_CHANGED
m2IfRcvAddrEntryGet( ) - get the rcvAddress table entries for a given address
STATUS m2IfRcvAddrEntryGet ( int search, /* exact search or next search */ int * pIndex, /* pointer to the ifIndex */ M2_IFRCVADDRTBL * pIfReqEntry /* struct containing the new values */ )
This function returns the exact or the next value in the ifRcvAddressTable based on the value of the search parameter. In order to identify the appropriate entry, this function needs two identifiers - the ifIndex of the interface and the physical address for which the status or the type is being requested. For a M2_EXACT_VALUE search, this function returns the status and the type of the physical address in the instance. For a M2_NEXT_VALUE search, it returns the type and status of the lexicographic successor of the physical address seen in the instance.
OK, or ERROR if the input parameter is not specified, an interface is no longer valid, or the interface index is incorrect.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
S_m2Lib_IF_CNFG_CHANGED
m2IfRcvAddrEntrySet( ) - modify the entries of the rcvAddressTable
STATUS m2IfRcvAddrEntrySet ( int varToSet, /* entries that need to be modified */ int index, /* search type */ M2_IFRCVADDRTBL * pIfReqEntry /* struct containing the new values */ )
This function modifies the status and type fields of a given recieve address associated with a given interface. varToSet identifies the fields for which the change is being requested. We can also add multicast addresses by creating a new row in the table. The physical address is stripped from the instance value of the SNMP request. This routine does not allow the deletion of a unicast address. Neither does it allow the unicast address to be modified or created.
OK, or ERROR if the input parameter is not specified, an interface is no longer valid, the interface index is incorrect, or the ioctl( ) command to the interface fails.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
S_m2Lib_IF_CNFG_CHANGED
m2IfLib, m2IfInit( ), m2IfGroupInfoGet( ), m2IfTblEntryGet( ), m2IfDelete( )
m2IfDelete( ) - delete all resources used to access the interface group
STATUS m2IfDelete (void)
This routine frees all the resources allocated at the time the group was initialized. The interface group should not be accessed after this routine has been called.
OK, always.
m2IfLib, m2IfInit( ), m2IfGroupInfoGet( ), m2IfTblEntryGet( ), m2IfTblEntrySet( )
nextIndex( ) - the comparison routine for the AVL tree
int nextIndex ( void * pAvlNode, /* The node to compare with */ GENERIC_ARGUMENT key /* The given index */ )
This routine compares the two indexes and returns a code based on wether the index, in question, is lesser than, equal to or greater than the one being compared.
-1 if the given index is lesser,
0 if equal and
1 if greater.