NAME

snmpMasterHandlerWR( ) - synchronous version of snmpMasterHandlerAsync( )

SYNOPSIS

INT_32_T snmpMasterHandlerWR 
    ( 
    OCTET_T *    pMsg,       /* pointer to the message            */ 
    ALENGTH_T    msgl,       /* length of the message             */ 
    IPCSEND_T *  pIpcSend,   /* send routine                      */ 
    IPCRCV_T *   pIpcRcv,    /* receive routine                   */ 
    IPCFREE_T *  pIpcFree,   /* free routine                      */ 
    IPCAYT_T *   pIpcAyt,    /* status Check Routine              */ 
    PTR_T        ipchandle,  /* ipchandle for the IPC scheme used */ 
    EBUFFER_T *  pBuf,       /* buffer to place reply in          */ 
    VBL_T *      pVblist,    /* place to put varbinds             */ 
    PTR_T        user_priv   /* MIB tree identifier               */ 
    )

DESCRIPTION

This function is called to process the control messages received from subagents when the communication method between master and subagent is synchronous.

To process a registration request, this function extracts the objects from the message and adds them as a group to the master agent's MIB tree. The actual get, test, and set methods for these objects reside in the subagent. To set up local methods for these routines, snmpMasterHandlerAsync( ) uses the function referenced in pIpcSend and pIpcRcv.

The methods local to the master agent use pIpcSend to send queries to the subagent which locally executes the actual method routine for the object. The subagent then transmits the results back to the master agent's public queue. When the function monitoring this queue sees the query response, it transfers the message to the master agent's local queue where the pIpcRcv function is waiting for the response.

To process a deregistration request, this function extracts a group ID from the message and removes that group of objects from the master agent's MIB tree. It also executes the function in pIpcFree to free any resources allocated locally to maintain the IPC link with the deregistered subagent.

The snmpMasterHandlerWR( ) routine returns information using the output parameters pBuf and pVblist and its function return value. If the returned function value indicates success, the master agent sends the message returned in pBuf to the subagent that sent the registration or deregistration request. If the returned value of this function indicates failure, the master agent silently drops the packet.

This function as has the ability to return an opcode value, although this functionality is unused in the shipped version of WindNet SNMP. In fact, if snmpMasterHandlerWR( ) were to return an opcode, the current implementation of the master agent would silently drop the packet. The possibility of returning an opcode is supported to make it possible for you to create subagents that send traps. In this case, snmpMasterHandlerWR( ) would return an opcode and a varbind list using the pVblist parameter. You could then rewrite snmpQueMonitor( ), the master agent function that calls snmpMasterHandlerWR( ), so that it responds appropriately to the returned opcode and forwards the contents of pVblist to the SNMP manager.

Use the snmpMasterHandlerWR( ) parameters as follows:

pMsg
Expects a pointer to an EBUFFER_T structure containing the data part of the message from the subagent. The message shows up on the queue as an SA_MESSAGE_T structure. The message expected by this parameter is contained in the mesg member of the SA_MESSAGE_T structure. To extract this pointer, you can use the EbufferStart macro defined in defined in buffer.h.

msgl
Expects the length of the message referenced in pMsg. To retrieve this length value, use the EBufferUsed macro defined in buffer.h.

pIpcSend
Expects a pointer to the function that method routines should use to send messages to the subagent. This function must be of the form:

INT_32_T masterIpcSend 
   ( 
   EBUFFER_T *        pBuf,      /* message to be sent 
   PTR_T              ipchandle  /* address of subagent 
   )

If snmpMasterHandlerWR( ) is processing a registration request from the subagent, it associates this function pointer with the group of objects it adds to the master agent's MIB tree. The methods for those objects call this routine to send a message to the subagent to make a test, get, or set query against those variables. After using this function to send the message, the master agent then calls the function referenced in pIpcRcv. The pIpcRcv function waits on a local queue for a response from the subagent. For an example of an masterIpcSend( ) routine, see the masterIpcSend( ) defined in masterIoLib.c.

ipcRcv
Expects a pointer to a function of the form:

INT_32_T masterIpcRcv  
   ( 
      EBUFFER_T *        pBuf,        /* buffer to receive message 
      PTR_T              ipchandle    /* address of subagent 
   )

If snmpMasterHandlerWR( ) is processing a registration request from the subagent, it associates this function pointer with the group of objects it adds to the master agent's MIB tree. The methods for those objects call this routine to wait on a local queue for a response from the subagent. For an example of an masterIpcRcv( ), see the masterIpcRcv( ) defined in masterIoLib.c.

ipcFree
Expects a pointer to a function of the form:

void masterIpcFree ( PTR_T ipchandle )

The master agent uses this function to free any resources it allocated to maintain the IPC link with the subagent. The master agent calls this function when a subagent deregisters.

pIpcAyt
Expects a pointer to the function the master agent can use to test the connection with the subagent. This function must be of the form:

INT_32_T masterIpcAyt ( PTR_T ipchandle )

For an example of such a function, see the masterIpcAyt( ) defined in masterIoLib.c.

ipchandle
Expects a pointer to the IPC handle used to access the subagent that sent this message. In the shipped implementation, this is a pointer to a message queue.

pBuf
Expects a pointer to a previously allocated EBUFFER_T. This is an output parameter that snmpMasterHandlerWR( ) uses this to return a reply packet, if one is generated. For example, if snmpMasterHandlerWR( ) successfully processes a registration request, it writes a message to the EBUFFER_T at pBuf. This message contains the group ID for the objects just added to the master agent's MIB tree. When control returns from snmpMasterHandlerWR( ), you must transmit this message back to the subagent, which will store the group ID for use in a deregistration request. In the current implementation, snmpQueMonitor( ) already handles this for you.

pVblist
Expects a pointer to a previously allocated VBL_T. The intended use of this parameter is to provide an output vehicle for the varbind list received in a trap message from a subagent. Because of the application-dependent nature of traps, the shipped implementation of snmpQueMonitor( ) just drops the packet. However, if you want to support traps from your subagents, you can modify snmpQueMonitor( ) to check the returned value of snmpMasterHandlerWR( ) to watch for a trap message. You can then use snmpIoTrapSend( ) to forward the trap message in pVblist to the SNMP manager.

user_priv
Expects a pointer to the MIB tree from which registration and deregistration requests want to add or delete objects or instances. If this pointer is NULL, the default MIB tree specified by mib_root_node is used.

If the message is trap request, it is the responsibility of the user code to acquire any values not specified in the trap message and to send the trap to the manager.

RETURNS

The opcode from the decoded packet or 0 or -1. An returned value of 0 indicates an error for which you should just drop the packet. A return value of -1 indicates success.

If this function returns an opcode, a value from 1 to 127, the shipped implementation just drops the packet. However, to support traps from the subagent, you could modify snmpQueMonitor( ) to note a returned value of SA_TRAP_REQUEST and then forward the varbind list in pVblist to the SNMP manager.

SEE ALSO

subagentLib