VxWorks Reference Manual : Libraries
saIoLib - default transport routines for SNMP subagent
snmpSaInit( ) - initialize the subagent
saIoWrite( ) - send a packet to the master agent's message queue
saIpcFree( ) - free the specified IPC mechanism
saMsgBuild( ) - build and encode a message and send it to the master agent
hdrBlkBuild( ) - create the header block and the demuxer information
envoy_now( ) - return the number of clock ticks elapsed since the timer was set
envoy_call_timer( ) - execute the specified function when the timer expires
This library implements the subagent side of the IPC mechanism used to pass messages between the SNMP master agent and its subagents. In the shipped version of this library, the IPC mechanism is a message queue. However, it is a relatively simple matter to replace the message queue with a socket if you cannot use message queues.
To set up the IPC mechanism and spawn a task to monitor it, call snmpSaInit( ). To send a message to the master agent, you can call saIoWrite( ). However, you will likely never call this function directly. Instead, you will call hdrBlkBuild( ). Internally, hdrBlkBuild( ) calls saMsgBuild( ), which calls snmpSubEncode( ) and finally saIoWrite( ).
The first message you will transmit using hdrBlkBuild( ) will be a registration message that registers objects and instances as a group in the master agent's MIB tree. If successful, the response to this message will contain a group ID. Make sure that you store this ID so that you can later remove the group from the MIB tree when you want to deregister the subagent. You also need this ID if you want to register instances of the object just registered.
Exactly how and when you register a subagent is up to you, but keep in mind that you can do so only after the master agent is up an running.
snmpSaInit( ) - initialize the subagent
PTR_T snmpSaInit ( PTR_T saId, /* ipchandle for socket/queue */ PTR_T sa_root, /* pointer to mib root node */ SA_REG_COMPLETE_T saRegComp /* registration complete routine */ )
Call this routine to initialize an SNMP subagent. Internally, this routine creates an IPC mechanism for receiving messages from the master agent and then spawns a task to run snmpSaMonitor( ), a function that monitors the IPC mechanism created by snmpSaInit( ). As input, snmpSaInit( ) takes the parameters: saId, sa_root, and saRegComp.
- saId
- Expects a null. In most functions in this library, an saId parameter is a pointer to the IPC mechanism used to pass messages to the subagent. However, the IPC mechanism is first created internally to this function. Thus, this saId parameter is not actually used for input nor is it an output parameter. It is included for parallelism with other functions in this library.
- sa_root
- This parameter provides a pointer to the MIB tree for this subagent.
- saRegComp
- Use this routine to pass in a pointer to the function that snmpSaHandlerAsync( ) should execute in response to a registration status message from the master agent. If the registration was successful, the response contains a group ID for the MIB variables registered with the master agent. You will need this group ID when it comes time to deregister this SNMP subagent, or when you need to register instances of the object just registered.
Although this function sets up the IPC mechanism and spawns the task that is effectively the SNMP subagent, this routine does not actually register the subagent with the master agent. The details of how and when one does that are entirely dependent upon the nature of the system you are designing. Thus, no generic registration utility is provided. For more information on sending a registration request to the master agent, see the description of hdrBlkBuild( ).
A pointer to the IPC mechanism created within this function, or NULL on failure.
saIoWrite( ) - send a packet to the master agent's message queue
STATUS saIoWrite ( PTR_T ipchandle, /* Subagent's identifier */ EBUFFER_T * pBuf, /* Encoded buffer */ INT_32_T code /* Message type */ )
This routine is called either from snmpSaHandlerAsync( ) or from the registration routines. ipchandle contains an identifier to the sub agents's message queue except for the case when the message is a response to IPC_AYT. In this case, it contains the identifier to the local queue at the master agent. The pBuf parameter points to the message being sent. The code parameter takes a value that indicates how the master agent should process the message. Value code values are CALL_QUERY_HANDLER, CALL_REG_HANDLER, and IPC_AYT. For more on how these values influence message processing in the master agent, see the description of snmpMonitorSpawn( ).
OK or ERROR.
saIpcFree( ) - free the specified IPC mechanism
void saIpcFree ( PTR_T ipchandle /* pointer to IPC handle */ )
Call this routine to free the IPC mechanism specified by ipchandle. You created this IPC mechanism with a call to snmpSaInit( ). If you rewrote snmpSaInit( ) to use an IPC mechanism other than message queues, you must rewrite saIpcFree( ) to match.
N/A
saMsgBuild( ) - build and encode a message and send it to the master agent
void saMsgBuild ( VBL_T * vblist, /* pointer to varbind list */ SA_HEADER_T * hdr_blk, /* pointer to header block */ SA_DEMUX_T * demuxer, /* pointer to demuxer */ PTR_T saId /* IPC handle */ )
The hdrBlkCreate( ) routine calls saMsgBuild( ) to build a message, encode it, and transmit it to the master agent. The message is built up from the information provided in the input parameters:
- vblist
- Expects a pointer to the VBL_T structure containing the varbind list you want to include in the message.
- hdr_blk
- Expects a pointer to the header for this message.
- demuxer
- Expects a pointer to the demuxer information for this message. The demuxer information consists of a string and an object ID. In a message dealing with a version 1 request, the string is the community string and the object ID is unused. In a message dealing with a version 2 request, the string is the local entity string from the context and the object ID is the local time object ID from the context.
- said
- Expects a pointer to the IPC mechanism (a message queue ID) that the master agent can use to respond to this message.
To encode the message, this routine calls snmpSubEncode( ). To send the message to the master agent, this routine calls saIoWrite( ).
N/A
hdrBlkBuild( ) - create the header block and the demuxer information
void hdrBlkBuild ( SA_HEADER_T * hdr, /* header block */ VBL_T * vblist, /* vblist that was built */ int opt, /* reg_option suggesting reg/dereg */ int group, /* group ID */ PTR_T saId /* ipchandle */ )
This routine is called to start a process that encodes a message and transmits it to the master agent. Internally, this routine first prepares a header block and demuxer information. These are then passed in to a saMsgBuild( ) call, along with a varbind list, and a pointer to the IPC mechanism that the master agent can use to respond to this message. As input, hdrBlkBuild( ) expects:
- hdr
- Expects a pointer to a previously allocated SA_HEADER_T structure. The hdrBlkBuild( ) routine uses this structure as a storage place within which to build the header block for the message to the master agent.
- vblist
- Expects a pointer to the VBL_T structure containing the varbind list that you want to include in the message.
- opt
- Expects an operation code that indicates the type of this message. Valid operation codes are as follows:
SA_REG_OBJ_REQUEST registers an object with the master agent's MIB tree. The response from the master agent will contain an SA_REG_OBJ_REPLY code.
SA_REM_OBJ_REQUEST removes (deregisters) an object from the master agent's MIB tree. The response from the master agent will contain an SA_REM_OBJ_REPLY code.
SA_REG_INST_REQUEST registers an instance with the master agent's MIB tree. The response from the master agent will contain an SA_REG_INST_REPLY code.
SA_REM_INST_REQUEST removes (deregisters) an instance from the master agent's MIB tree. The response from the master agent will contain an SA_REG_OBJ_REPLY code.
SA_QUERY_REQUEST requests SNMP operations. The response from the master agent will contain an SA_QUERY_REPLY code.
SA_TRAP_REQUEST tells the master agent that this message should be handled as a trap. The response from the master agent (if any) will contain an SA_TRAP_REPLY code.
- group
- Expects the group ID that the master agent has assigned to the objects or instances referenced in vblist. This group ID was returned in an If SA_REG_OBJ_REPLY or an SA_REG_INST_REPLY from the master agent. this is an object registration request, you can supply a NULL pointer here.
- said
- Expects a pointer to the IPC mechanism that the master agent can use to respond to the message.
N/A
envoy_now( ) - return the number of clock ticks elapsed since the timer was set
bits32_t envoy_now (void)
Call this function to find out the number of clock ticks elapsed since the timer was set.
Elapsed time, in ticks.
envoy_call_timer( ) - execute the specified function when the timer expires
void envoy_call_timer ( bits32_t when, void (* what)(void) )
This routine executes the what function after when ticks have elapsed. This function is used internally to respond when the interval between the test and set of a "test and set" exceeds the timeout specified by when.
N/A