subagentlib.html

vxworks相关论文

<dt>
<i>msgl</i>
<dd>

Expects the length of the message starting at <i>pMsg</i>.
<p>
<dt>
<i>pBuf</i>
<dd>

Expects a pointer to a previously allocate <b>EBUFFER_T</b> into which this
function can write a response, if any.  In some cases (if <b>opcode1</b>
is <b>SA_QUERY_REQUEST</b>), instead of indicating an error in the returned value
of <b><i><a href="./subagentLib.html#snmpSaHandlerWR">snmpSaHandlerWR</a></i>(&nbsp;)</b>, the error is encoded into this message.  This is
done for errors more appropriately handled by the SNMP manager.
<p>
<dt>
<i>pHdr</i>
<dd>

Expects a pointer to a previously allocated <b>SA_HEADER_T</b> structure into
which this function can writer header block information, if necessary.
If <b>hdr_blk.sa_error</b> is non-zero, other members might not contain valid
data.
<p>
<dt>
<i>pVblist</i>
<dd>

Expects a pointer to a previously allocated <b>VBL_T</b> structure into which
this function can write the list of nodes found in the original message
from the master agent.
<p>
<dt>
<i>root</i>
<dd>
 Expects a pointer to the root of the subagent's MIB tree.  If <i>root</i>
is NULL, the default <b>mib_root_node</b> is used.
<p>
</dl>

</blockquote><h4>RETURNS</h4><blockquote><p>
<p>
&nbsp;0&nbsp;on&nbsp;success,&nbsp;or&nbsp;a&nbsp;positive&nbsp;value&nbsp;indicating&nbsp;an&nbsp;error.
For return code values, see <b>subagent.h</b>.  Using these values as a switch,
you should call one of the functions you would have specified
for <i>pIoComp</i>, <i>pErrComp</i>, or <i>pRegComp</i> in a call to <b><i><a href="./subagentLib.html#snmpSaHandlerAsync">snmpSaHandlerAsync</a></i>(&nbsp;)</b>.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./subagentLib.html#top">subagentLib</a></b>

<hr>
<a name="snmpSaHandlerContinue"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>snmpSaHandlerContinue</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>snmpSaHandlerContinue</i>(&nbsp;)</strong> - subagent continuation function</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>void snmpSaHandlerContinue
    (
    SNMP_PKT_T * pPkt /* pointer to the SNMP packet */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine is similar to <b><i><a href="./snmpdLib.html#snmpdContinue">snmpdContinue</a></i>(&nbsp;)</b>.  Method routines that do not
complete their tasks before returning should arrange to have this routine
called when the task is finished. This routine should not be called if
you call <b><i><a href="./subagentLib.html#snmpSaHandlerWR">snmpSaHandlerWR</a></i>(&nbsp;)</b>. The <i>pPkt</i> parameter expects a pointer to the
packet.  If <b>SNMP_CONTINUE_REENTRANT</b> is installed, this routine will
attempt to release the per-packet write lock.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./subagentLib.html#top">subagentLib</a></b>

<hr>
<a name="snmpSaHandlerFinish"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>snmpSaHandlerFinish</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>snmpSaHandlerFinish</i>(&nbsp;)</strong> - encode packet for subagent IO completion</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>INT_32_T snmpSaHandlerFinish
    (
    PTR_T         pkt,  /* pointer to the packet */
    SA_HEADER_T * pHdr, /* header block */
    EBUFFER_T *   pBuf  /* buffer to place the result in */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine encodes the packet at <i>pkt</i> and the header block at <i>pHdr</i>.
If <i>pBuf</i> is empty, this routine tries to allocate space.  If it cannot or
if the space provided is too small, an error is returned.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
0 on success, or a non-zero value on failure.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./subagentLib.html#top">subagentLib</a></b>

<hr>
<a name="snmpSaHandlerCleanup"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>snmpSaHandlerCleanup</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>snmpSaHandlerCleanup</i>(&nbsp;)</strong> - cleanup routine for subagent</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>void snmpSaHandlerCleanup
    (
    PTR_T         pPkt, /* pointer to the packet */
    SA_HEADER_T * pHdr  /* header block */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine is called by the IO completion routine if it detects an error.
It either frees or arranges to free any resources that might have been
allocated for processing a query from the master agent.  The information
at <i>pPkt</i> and <i>pHdr</i> is passed unchanged into the completion routine.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./subagentLib.html#top">subagentLib</a></b>

<hr>
<a name="snmpMasterHandlerAsync"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>snmpMasterHandlerAsync</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>snmpMasterHandlerAsync</i>(&nbsp;)</strong> - process messages from the subagent asynchronously</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>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 */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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 <b><i><a href="./subagentLib.html#snmpMasterHandlerWR">snmpMasterHandlerWR</a></i>(&nbsp;)</b>,
a function that supports a synchronous communication scheme.  If you want
master agents and subagents to use an asynchronous communication scheme,
you must rewrite <b><i>snmpQueMonitor</i>(&nbsp;)</b> to call <b><i><a href="./subagentLib.html#snmpMasterHandlerAsync">snmpMasterHandlerAsync</a></i>(&nbsp;)</b> instead
of <b><i><a href="./subagentLib.html#snmpMasterHandlerWR">snmpMasterHandlerWR</a></i>(&nbsp;)</b>.  In addition, because <b><i><a href="./subagentLib.html#snmpMasterHandlerAsync">snmpMasterHandlerAsync</a></i>(&nbsp;)</b>
does not return a function value, you will need to remove the
<b><i>snmpQueMonitor</i>(&nbsp;)</b> code that responded to the <b><i><a href="./subagentLib.html#snmpMasterHandlerWR">snmpMasterHandlerWR</a></i>(&nbsp;)</b> function
value.  The functionality handled by the removed code should instead be
implemented in the function referenced by the <i>ipcComp</i> parameter.
Use the parameters as follows:
<dl>
<dt>
<i>pMsg</i>
<dd>

Expects a pointer to an <b>EBUFFER_T</b> structure containing the data part of
the message from the subagent.  The message shows up on the queue as
an <b>SA_MESSAGE_T</b> structure.  The message expected by this parameter is
contained in the <b>mesg</b> member of this structure.  To extract this
pointer, use <b>EbufferStart</b> macro defined in defined in <b>buffer.h</b>.
<p>
<dt>
<i>msgl</i>
<dd>

Expects the length of the message referenced in <i>pMsg</i>.  To retrieve this
length value, use the <b>EBufferUsed</b> macro defined in <b>buffer.h</b>.
<p>
<dt>
<i>pIpcComp</i>
<dd>

Expects a pointer to the completion function, which must be of the form:
<pre>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 that the message contained */
   PTR_T         ipchandle  /* subagent address */
   )
</pre>
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 <b><i>masterIcpComp</i>(&nbsp;)</b> should be able handle things such
as letting the subagent know the completion status of message it sent to
the master agent.
<p>
For a registration routine, it must send the message
in <i>ebuf</i> 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.
<p>
If you decide to support
traps from subagents, this function must be able to forward the varbind
list in <i>vblist</i> to the SNMP manager.  In addition, it is your responsibility
to acquire any values not specified in <i>vblist</i> and include it in the
message you send the to the SNMP manager.  Use the <i>opcode</i> to know when
you are handling the completion processing for a registration request, a
deregistration request, or a trap from a subagent.
<p>
For an example of an IPC completion routine, see <b><i><a href="./masterIoLib.html#masterIpcComp">masterIpcComp</a></i>(&nbsp;)</b> defined
in <b>masterIoLib.c</b>.
<p>
<dt>
<i>pIpcSend</i>
<dd>

Expects a pointer to the function that method routines should use to send
messages to the subagent.  This function must be of the form:
<pre>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 */
   )
</pre>
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.
<p>
To process a query response, you must
call <b><i><a href="./subagentLib.html#snmpMasterQueryHandler">snmpMasterQueryHandler</a></i>(&nbsp;)</b>.  This function will handle the details of
integrating the message from the subagent into a message to the SNMP manager.
<p>
To clean up after a send that times out, you must call
<b><i><a href="./subagentLib.html#snmpMasterCleanup">snmpMasterCleanup</a></i>(&nbsp;)</b>.  The specifics of the mechanism you use are up to you,
but you will likely need to integrate the mechanism with your <b><i><a href="./masterIoLib.html#masterIpcSend">masterIpcSend</a></i>(&nbsp;)</b>
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 <b><i><a href="./masterIoLib.html#masterIpcSend">masterIpcSend</a></i>(&nbsp;)</b>
using the <i>reqid</i> parameter.  To clean up after a send that times out,
you submit the <i>reqid</i> in a call to <b><i><a href="./subagentLib.html#snmpMasterCleanup">snmpMasterCleanup</a></i>(&nbsp;)</b>.
<p>
For an example of an <b><i><a href="./masterIoLib.html#masterIpcSend">masterIpcSend</a></i>(&nbsp;)</b>, see the <b><i><a href="./masterIoLib.html#masterIpcSend">masterIpcSend</a></i>(&nbsp;)</b>
defined in <b>masterIoLib.c</b>.
<p>
<dt>
<i>pIpcRcv</i>
<dd>

This parameter is not used by <b><i><a href="./subagentLib.html#snmpMasterHandlerAsync">snmpMasterHandlerAsync</a></i>(&nbsp;)</b> and so should
be null.  It is included to maintain parallelism with <b><i><a href="./subagentLib.html#snmpMasterHandlerWR">snmpMasterHandlerWR</a></i>(&nbsp;)</b>.
<p>
<dt>
<i>pIpcFree</i>
<dd>

Expects a pointer to a function of the form:
<pre>void masterIpcFree ( PTR_T ipchandle )
</pre>
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.
<p>
<dt>
<i>pIpcAyt</i>
<dd>

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:
<pre>INT_32_T masterIpcAyt ( PTR_T ipchandle )
</pre>
For an example of such a function, see the <b><i><a href="./masterIoLib.html#masterIpcAyt">masterIpcAyt</a></i>(&nbsp;)</b> defined
in <b>masterIoLib.c</b>.
<p>
<dt>
<i>ipchandle</i>
<dd>

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.
<p>
<dt>
<i>user_priv</i>
<dd>
 Expects a pointer to the MIB tree from which registration and deregistration