VxWorks Reference Manual : Libraries
snmpdLib - entry points to the SNMP v1/v2c agent
snmpdPktProcess( ) - process a packet returned by the transport
snmpdLog( ) - log messages from the SNMP agent
snmpdViewEntrySet( ) - install an entry in the view table
snmpdViewEntryRemove( ) - remove an entry from the view table
snmpdTreeAdd( ) - dynamically add a subtree to the SNMP agent MIB tree
snmpdTreeRemove( ) - dynamically remove part of the SNMP agent MIB tree
snmpdTrapSend( ) - general interface to trap facilities
snmpdInitFinish( ) - complete the initialization of the agent
snmpdExit( ) - exit the SNMP agent
snmpdContinue( ) - continue processing of an SNMP packet
snmpdGroupByGetprocAndInstance( ) - gather set of similar variable bindings
snmpdVbRowExtract( ) - extract required pieces of a row for a set operation
snmpdVbExtractRowLoose( ) - incrementally extract pieces of a row for a set
snmpdPktLockGet( ) - lock an SNMP packet
This module implements the WindNet SNMPv1/v2c agent for VxWorks. This agent provides for the management of objects defined by the MIB-II standard. The agent management information base can be extended to include additional user-defined MIBs. The agent also provides support for asynchronous method routines and dynamic loading of MIBs.
snmpdLib.h
snmpdLib, The SNMP version 1 framework is defined by the following Request For Comments (RFCs): 1155, 1157, 1212. MIB-II is defined by RFC 1213. For more information about SNMP, refer to these documents. For more information about the VxWorks SNMP agent, see the WindNet SNMP VxWorks Component Release Supplement.
snmpdPktProcess( ) - process a packet returned by the transport
void snmpdPktProcess ( int pktSize, /* packe length */ char * pBuf, /* packet buffer */ void * pRemoteAddr, /* remote transport address */ void * pLocalAddr, /* local transport address */ void * pSnmpEndpoint /* snmp transport end point */ )
This routine is invoked by the user-IO layer to process a received packet. The buffer pBuf (provided by the agent designer) must contain a packet of size pktSize. The source address of the sending machine is indicated by pRemoteAddr, and the address of the receiver by pLocalAddr. These three parameters, pRemoteAddr, pLocalAddr, and pSnmpEndpoint, are passed down to user-provided transport routines. The transport endpoint is passed in pSnmpEndpoint
N/A
snmpdLog( ) - log messages from the SNMP agent
void snmpdLog ( int level, /* level of this message */ char * string /* message string */ )
This routine logs messages generated by the SNMP agent. Messages are sent to the standard console. If level is less than or equal to SNMP_TRACE_LEVEL (in configAll.h), the message is printed, otherwise it is ignored. The value of level must be one of 1, 2, or 3.
N/A
snmpdViewEntrySet( ) - install an entry in the view table
STATUS snmpdViewEntrySet ( OIDC_T * pTreeOid, /* sub tree for view */ int treeOidLen, /* length of subtree oid */ UINT_16_T index, /* index of entry */ uchar_t * pMask, /* mask for entry */ int maskLen, /* mask length in bytes */ int viewType /* type of view (INCLUDED/EXCLUDED) */ )
This function creates an entry in the view table. The view subtree is specified by pTreeOid and treeOidLen.
The installed entry has an index of index. The specified view is included in or excluded from the view table depending on the value of viewType (VIEW_INCLUDED or VIEW_EXCLUDED, respectively). The entry mask is specified by pmask; maskLen must be the mask length in bytes.
OK on success, otherwise ERROR
snmpdViewEntryRemove( ) - remove an entry from the view table
void snmpdViewEntryRemove ( OIDC_T * pTreeOid, /* oid of view subtree to remove */ int treeOidLen, /* length of view subtree oid */ UINT_16_T index /* index of entry */ )
This routine removes an entry from the view table and deallocates the associated resources. The entry should have been previously created with snmpdViewEntrySet( ).
N/A
snmpdLib, snmpdViewEntrySet( )
snmpdTreeAdd( ) - dynamically add a subtree to the SNMP agent MIB tree
STATUS snmpdTreeAdd ( char * pTreeOidStr, MIBNODE_T * pTreeAddr )
This routine adds the specified MIB subtree, located in memory at the address pTreeAddr, to the agent's MIB data tree at the node with the object identifier specified by pTreeOidStr. This subtree is normally generated with the -start option to mibcomp.
OK on success, otherwise ERROR.
snmpdLib, WindNet SNMPv1v2c VxWorks Component Release Supplement
snmpdTreeRemove( ) - dynamically remove part of the SNMP agent MIB tree
void snmpdTreeRemove ( char * pTreeOidStr /* char string specifying oid of tree to remove */ )
This routine deletes part of the SNMP agent MIB tree at runtime. Once the specified subtree is deleted, any further requests to access objects of that subtree fail.
N/A
snmpdLib, WindNet SNMPv1v2c VxWorks Component Release Supplement
snmpdTrapSend( ) - general interface to trap facilities
void snmpdTrapSend ( void * pSnmpEndpoint, /* snmp agent transport endpoint */ int numDestn, /* number of destinations */ void * * ppDestAddrTbl, /* array of ptrs to destinations */ void * pLocalAddr, /* local address */ int version, /* SNMP version */ char * pTrapCmnty, /* trap community string */ OIDC_T * pMyOid, /* agent object identifier */ int myOidLen, /* length of agent object identifier */ u_long * pIpAddr, /* ip address of sender */ int trapType, /* trap type */ int trapSpecific, /* trap specific code */ int numVarBinds, /* number of varbinds in packet */ FUNCPTR trapVarBindsRtn, /* routine to bind varbinds */ void * pCookie /* argument to binding routine */ )
This routine sends a trap of type trapType and specific trapSpecific to all the specified destinations, given an array of destinations in ppDestAddrTbl of len numDestn.
The version parameter is either SNMP_VERSION_1 or SNMP_VERSION_2, depending on whether a v1-style or v2-style trap is to be generated. The community used is specified by pTrapCmnty. pLocalAddr indicates a local address to use for a sending endpoint. pMyOid and myOidlen specify the system object identifier (sysObjId) to use.
numVarBinds indicates the number of variable bindings that are to be encoded in the packet. trapVarBindsRtn is the routine to use for doing the variable bindings. pCookie is passed to this routine as shown below:
(*trapVarBindsRtn) (pPkt, pCookie)
N/A
snmpdInitFinish( ) - complete the initialization of the agent
void snmpdInitFinish ( VOIDFUNCPTR pPrivRlse, /* user's privare release routine */ FUNCPTR pSetPduVldt, /* user's set pdu validate routine */ FUNCPTR pPreSet, /* user's pre set routine */ FUNCPTR pPostSet, /* user's post set routine */ FUNCPTR pSetFailed /* user's set failed routine */ )
This routine is required to be called by the user to complete the initialization of the SNMP agent after the transport endpoint has been initialized. This routine must be called \f2after\fR the endpoint has been established, since it depends on that endpoint to function correctly.
This routine also installs any user-supplied hooks for customizing the agent. If a hook is not required, a NULL pointer should be passed in that position. The function snmpIoTrapSend( ) is invoked by this routine, so any configuration required by that routine should be done prior to calling snmpdInitFinish( ).
The hook routines are as follows:
- pPrivRlse
- This routine is used by the agent to free any memory attached to the private field of the SNMP_PKT_T structure.
- pSetPduVldt
- This routine is called before any processing of a set request has taken place. It can be used to perform global validation of the request, if needed. The return values for this routine must meet the following requirements:
0 - indicates that the set PDU is valid, and processing should continue.
1 - indicates that the set PDU is valid, and that this routine has already completed all the required set operations.
-1 - indicates that the set PDU is invalid and should be rejected.
- pPreSet
- This routine is called after all testproc operations have completed successfully, but before any setproc operation is begun. Return value requirements are as follows
0 - indicates that the set PDU is valid, and processing should continue.
1 - indicates that the set PDU is valid, and that this routine has already completed all the required set operations.
-1 - indicates that the set PDU is invalid and should be rejected.
- pPostSet
- This routine is called after all setproc have completed successfully. This routine can be used to free resources allocated during set processing.
- pSetFailed
- This routine is possibly called under two sets of circumstances: after all testproc operations have returned and some of them have failed, and/or after all undoproc operations have returned and some setproc operations have failed. It can be used to do any required cleanup.
N/A
snmpdExit( ) - exit the SNMP agent
void snmpdExit (void)
This routine causes the SNMP agent to exit. It is available in case the user encounters some problem after a successful startup.
This routine must be called from the main thread. Any other tasks spawned by the user (for asynchronous method routines) should be deleted prior to calling this function.
N/A
snmpdContinue( ) - continue processing of an SNMP packet
void snmpdContinue ( SNMP_PKT_T * pktp /* snmp packet */ )
This routine continues processing a packet. snmpdPktProcess( ) begins the method routines needed to fulfill the request, while this routine determines whether the current set of method routines have finished; it then either starts more method routines or sends a response packet.
If a method routine returns before completing its task, it must arrange for snmpdContinue( ) to be called when the task is completed. You must obtain the write-lock on this packet by calling snmpdPktLockGet( ) prior to calling snmpdContinue( ). snmpdContinue( ) releases the write-lock when it completes.
pktp is a pointer to the structure that contains the packet.
N/A
snmpdGroupByGetprocAndInstance( ) - gather set of similar variable bindings
void snmpdGroupByGetprocAndInstance ( SNMP_PKT_T * pktp, /* snmp packet */ VB_T * firstVbp, /* first var bind */ int compc, /* component count */ OIDC_T * compl /* component length */ )
This routine gathers a set of similar variable bindings together by searching the variable bindings in pktp, starting at firstVbp for a match of the getproc pointer of firstVbp and with an instance specified by compc and compl. This routine then links the variable bindings found which match firsVbp.
This routine does not set any flags in the variable bindings. It is left to the calling routine to decide whether the tested or set flags should be set.
N/A
snmpdVbRowExtract( ) - extract required pieces of a row for a set operation
VB_T * snmpdVbRowExtract ( SNMP_PKT_T * pktp, /* snmp packet */ int start_index, /* starting index */ int compc, /* component count */ OIDC_T * compl, /* component length */ int row_structure_length, /* length of row structure */ struct create_row * row /* row structure */ )
This routine assists in implementing row-creation set operations. It is typically used by the testproc routine for a table. It scans the SNMP packet looking for all the pieces that go together for the purposes of creating a new row in an SNMP table.
The parameter row describes what this routine is looking for. row is a list of MIB leaf pointers referring to variables in the table in question, and a flag indicating if this variable (column) in the table is required. This routine searches the variable bindings in pktp for a match of the MIB leaf pointer specified in the row array and the instance specified by compc and compl. It links the variable bindings found from the first MIB leaf node in the row array. This first variable binding must be in the packet whether it is marked as needed or not, and is the return value of snmpdVbRowExtract( ).
If snmpdVbRowExtract( ) does not find a matching variable binding and that leaf is flagged ROW_FLAG_NEEDED in the row array, the routine returns NULL to indicate an error.
This routine marks the variable bindings in the resulting list as already tested except for the first entry, which is marked as already set. As a result, the agent only calls the set routine associated with the first MIB leaf in the row array. This set routine should handle creation of the necessary data structures and reading the variable binding list to execute the required set operations. You can force other entries set routines to be called by flagging entries with ROW_FLAG_CALL_SET.
a pointer to the first variable binding if successful, otherwise NULL.
snmpdVbExtractRowLoose( ) - incrementally extract pieces of a row for a set
VB_T * snmpdVbExtractRowLoose ( SNMP_PKT_T * pktp, /* snmp packet */ int indx, /* index */ MIBLEAF_T * * leaves, /* mib leaves */ int compc, /* component count */ OIDC_T * compl /* component length */ )
This routine assists in implementing row-creation set operations, especially in the case of `dribble creation. In `dribble creation, the network management station may choose to break the creation of a new entry in some table into multiple packets. Using multiple packets does not work with snmpdVbRowExtract( ), which requires at least one specified item to be in the packet.
In dribble creation, there is no single item that is guaranteed to be in every packet. As its name implies, this routine is similar to snmpdVbRowExtract( ). It searches the variable bindings in pktp starting at indx for a match of the MIB leaf pointer specified in the leaves array and with an instance specified by compc and compl. The routine then links the variable bindings found from the last variable binding found.
If no variable bindings are found, this routine returns a NULL pointer. This routine does not set any of the flags in the variable bindings. It is left to the calling routine to decide if the tested or set flags should be set.
a pointer to the last variable binding if successful, otherwise NULL.
snmpdPktLockGet( ) - lock an SNMP packet
STATUS snmpdPktLockGet ( SNMP_PKT_T * pktp /* snmp packet */ )
This routine obtains a lock on the SNMP packet being processed, which must be obtained by any asynchronous method routine prior to calling any of the routines getproc_*, nextproc_*, testproc_*, or setproc_*, or also snmpdContinue( ). snmpdContinue( ) releases the lock before returning. No other routine can release this lock.
This routine blocks until the lock is obtained.
Returns: OK, or ERROR on failure.