VxWorks API Reference : OS 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 packet counters for an 802.3 device
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
m2IfTblEntryGet( ) - get a MIB-II interface-group table entry
m2IfTblEntrySet( ) - set the state of a MIB-II interface entry to UP or DOWN
m2IfGroupInfoGet( ) - get the MIB-II interface-group scalar variables
m2IfStackTblUpdate( ) - update the relationship between the sub-layers
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
m2PollStatsIfPoll( ) - read statistics information from an interface's
m2IfUsrCountersInstall( ) - install a pointer to user-defined counters
m2IfUsrCountersRemove( ) - delete the pointer to the user-defined counters
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.
To use this feature, include the following component: INCLUDE_MIB2_IF
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
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 driver's responsibility to set the pMib2Tbl pointer in the END object to the new M2_ID.
When this call returns, the calling routine must set the END_MIB_2233 bit of the flags field in the END object.
Pointer to the M2_ID structure that was 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 is 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 updates the basic interface counters for a packet. It knows nothing of the underlying media. Thus, 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 packet counters for an 802.3 device
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 */ )
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:
This function should be called right after the netMblkToBufCopy( ) function 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.
- ifInOctets - ifInUcastPkts - ifInNUcastPkts - ifOutOctets - ifOutUcastPkts - ifOutNUcastPkts - ifInMulticastPkts - ifInBroadcastPkts - ifOutMulticastPkts - ifOutBroadcastPkts - ifHCInOctets - ifHCInUcastPkts - ifHCOutOctets - ifHCOutUcastPkts - ifHCInMulticastPkts - ifHCInBroadcastPkts - ifHCOutMulticastPkts - ifHCOutBroadcastPkts - ifCounterDiscontinuityTime 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 different types of data. Here is a list of the variables and the type of data expected. Therefore, pData will be cast to the type listed below for each variable.
Variable Casted to Type 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, if successful; ERROR, if an error occurred.
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 */ int (* if_ioctl) /* protocol specific ioctl or null for */ /* default (ethernet) */ (struct socket* ,u_long,caddr_t), STATUS (* addr_get) /* func to grab the interface's addrs, null */ /* for default (ethernet) */ (struct ifnet* , M2_IFINDEX* ) )
This routine is called by if_attach and if_detach to insert/remove an entry from the local m2IfLib ifTable. The status can be either 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. if_ioctl is a function pointer to change the flags on the interface. addr_get is a function pointer to add the interface's addresses to ifRcvAddressTable. Ethernet interfaces can use NULL for both function pointers, other interfaces will need to pass an appropriate function.
ERROR if entry does not exist, OK if the entry was deleted
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. The interface table values are returned in a structure of type M2_DATA, which is passed as the second argument to this routine.
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( )
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 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( )
m2IfStackTblUpdate( ) - update the relationship between the sub-layers
STATUS m2IfStackTblUpdate ( UINT lowerIndex, /* The ifIndex of the lower sub-layer */ UINT higherIndex, /* The ifIndex of the higher sub-layer */ int action /* insert or remove */ )
This function must be called to setup the relationship between the ifIndex values for each sub-layer. This information is required to support the ifStackTable for RFC 2233. Using this data, we can easily determine which sub-layer runs on top of which other.
action is either M2_STACK_TABLE_INSERT or M2_STACK_TABLE_REMOVE.
Each AVL node keeps a linked list of all the layers that are directly beneath it. Thus by walking through the AVL nodes in an orderly way, we can understand the relationships between all the interfaces.
OK upon successful addition
ERROR otherwise.
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 for the 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 receive 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.
m2PollStatsIfPoll( ) - read statistics information from an interface's
STATUS m2PollStatsIfPoll ( END_IFDRVCONF * pDrvConf )
internal counters
This function invokes the EIOCGPOLLSTATS ioctl on a specified interface and, if the ioctl succeeds, it updates its associated MIB2 counters. Only those counters which are marked as valid in the interface's ifValidCounters field in the END_IFDRVCONF structure will be updated. This routine may be invoked either automatically via periodic watchdog timeout, or directly in order to force a counter update if the watchdog has not yet expired.
ERROR if reading the counters fails, otherwise OK.
m2IfUsrCountersInstall( ) - install a pointer to user-defined counters
STATUS m2IfUsrCountersInstall ( M2_ID * pM2Id, /* M2_ID structure for interface */ void * pUsrCounters /* pointer to structure containing counters */ )
This routine installs a pointer pUsrCounters in the M2_ID structure specified by pM2Id. The installed pointer can be used to add additional counters per interface to support RMON, rfc1643 or any other counters. If a counter already exists the installation fails. The counters can be accessed using the m2UsrCounter field in the M2_ID structure for the interface. The pointer will typically refer to a structure which contains all the counters. For example:
struct counters { u_long ctr1; u_long ctr2; };It is the responsibility of the user to allocate and initialize the counter structure before calling this routine.
OK, or ERROR
S_m2Lib_INVALID_PARAMETER
m2IfUsrCountersRemove( ) - delete the pointer to the user-defined counters
STATUS m2IfUsrCountersRemove ( M2_ID * pM2Id /* M2_ID structure for interface */ )
This routine removes the user-defined counters associated with the interface. It is the responsibility of the user to free the counter structure once it has been deleted.
OK, or ERROR if pM2Id is NULL
S_m2Lib_INVALID_PARAMETER