NAME

snmpMasterHandlerAsync( ) - process messages from the subagent asynchronously

SYNOPSIS

void snmpMasterHandlerAsync 
    ( 
    OCTET_T *       pMsg,       /* pointer to the message            */ 
    ALENGTH_T       msgl,       /* length of the message             */ 
    IPCCOMP_T *     pIpcComp,   /* completion routine                */ 
    IPCSEND_AS_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 */ 
    PTR_T           user_priv   /* MIB tree identifier               */ 
    )

DESCRIPTION

This function provides support for an asynchronous communication scheme between the master agent and its subagents. The shipped version of WindNet SNMP does not call this function. Instead, it calls snmpMasterHandlerWR( ), a function that supports a synchronous communication scheme. If you want master agents and subagents to use an asynchronous communication scheme, you must rewrite snmpQueMonitor( ) to call snmpMasterHandlerAsync( ) instead of snmpMasterHandlerWR( ). In addition, because snmpMasterHandlerAsync( ) does not return a function value, you will need to remove the snmpQueMonitor( ) code that responded to the snmpMasterHandlerWR( ) function value. The functionality handled by the removed code should instead be implemented in the function referenced by the pIpcComp parameter. Use the 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 this structure. To extract this pointer, use 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.

pIpcComp
Expects a pointer to the completion function, which must be of the form:

void masterIpcComp 
   ( 
   OCTET_T       opcode,    /* this specifies what needs to be done 
   EBUFFER_T *   ebuf,      /* reply message to be sent 
   VBL_T *       vblist,    /* list of varbinds message contained 
   PTR_T         ipchandle  /* subagent address 
   )

The master agent executes this function upon completing processing for an unsolicited control message from a subagent (primarily registration requests, although a trap from the subagent will eventually find its way to this function). Your masterIcpComp( ) should be able handle things such as letting the subagent know the completion status of message it sent to the master agent.

For a registration routine, it must send the message in ebuf back to the subagent. This message contains the group ID of the MIB variables added to the master agent's MIB tree. The subagent needs this ID to make a deregistration request.

If you decide to support traps from subagents, this function must be able to forward the varbind list in vblist to the SNMP manager. In addition, it is your responsibility to acquire any values not specified in vblist and include it in the message you send the to the SNMP manager. Use the opcode to know when you are handling the completion processing for a registration request, a deregistration request, or a trap from a subagent.

For an example of an IPC completion routine, see masterIpcComp( ) defined in masterIoLib.c.

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 
   UINT_16_T          reqid      /* ID for request sent 
   )

To make the communication between the master agent and subagent asynchronous, this send routine should send the message to the subagent and return. Eventually, a response shows up on the master agent's local queue, or the query times out. How you process a query response or a query time out is almost entirely up to you.

To process a query response, you must call snmpMasterQueryHandler( ). This function will handle the details of integrating the message from the subagent into a message to the SNMP manager.

To clean up after a send that times out, you must call snmpMasterCleanup( ). The specifics of the mechanism you use are up to you, but you will likely need to integrate the mechanism with your masterIpcSend( ) routine. That is because this function gets the request ID that you will need for clean up. The request ID is a number generated internally to the SNMP master agent. It passes this value into your masterIpcSend( ) using the reqid parameter. To clean up after a send that times out, you submit the reqid in a call to snmpMasterCleanup( ).

For an example of an masterIpcSend( ), see the masterIpcSend( ) defined in masterIoLib.c.

pIpcRcv
This parameter is not used by snmpMasterHandlerAsync( ) and so should be null. It is included to maintain parallelism with snmpMasterHandlerWR( ).

pIpcFree
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 might have 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.

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.

RETURNS

N/A

SEE ALSO

subagentLib